4.8. Program Class

Program objects allow Qore programs to support subprograms with restricted capabilities, for example, to support user-defined logic for application actions.

Parsing in Qore happens in two steps; first all code is parsed to pending data structures, and then in the second stage, all references are resolved, and, if there are no errors, then all changes are committed to the Program object. Note that all parse actions (Program::parse(), Program::parsePending(), Program::parseCommit(), and Program::parseRollback()) are atomic; there is a thread lock on each Program object to ensure atomicity, and if any parse errors occur in any stage of parsing, any pending changes to the Program object are automatically rolled back. However parse actions that affect only one stage of the two stages of parsing (Program::parsePending(), Program::parseCommit() and Program::parseRollback()) are atomic within themselves, but not between calls, so one thread may inadvertently commit changes to a Program object if two or more threads are trying to perform transaction-safe two-stage parsing on a Program object without explicit user locking.

The constants in the following table can be used to limit the capabilities of a Program object. These options should be binary-OR'ed together and passed to the Program object's constructor. Also see Command-Line Parsing for equivalent command-line options, and Parse Directives for equivalent parse directives.

Note that a program can provide controlled access to functionality otherwise restricted by parse options by exporting a custom API into the child program object using either the Program::importFunction() or Program::importGlobalVariable() method. This is possible because code (functions or object methods) imported into and called from a subprogram will run in the parent's space and therefore with the parent's capabilities.

The following constants are all in the Qore namespace.

Table 4.337. Parse Options

Constant

Details

Description

PO_NO_GLOBAL_VARS

%no-global-vars

Disallows the use of global variables.

PO_NO_SUBROUTINE_DEFS

%no-subroutine-defs

Disallows subroutine (function) definitions.

PO_NO_THREADS

%no-threads

Disallows any thread operations (the background operator and the thread_exit statement, for example) and the use of thread-relevant classes and functions (equivalent to PO_NO_THREAD_CLASSES | PO_NO_THREAD_CONTROL).

PO_NO_THREAD_CLASSES

%no-thread-classes

Disallows access to any thread classes.

PO_NO_THREAD_CONTROL

%no-thread-control

Disallows access to any thread-control functions and thread-relevant statements and operators (for example the background operator and the thread_exit statement).

PO_NO_TOP_LEVEL_STATEMENTS

no-top-level

Disallows top level code.

PO_NO_CLASS_DEFS

no-class-defs

Disallows class definitions.

PO_NO_NAMESPACE_DEFS

no-namespace-defs

Disallows new namespace definitions.

PO_NO_CONSTANT_DEFS

no-constant-defs

Disallows constant definitions.

PO_NO_NEW

no-new

Disallows use of the new operator.

PO_NO_SYSTEM_CLASSES

n/a

Prohibits system classes from being imported into the new Program object.

PO_NO_USER_CLASSES

n/a

Prohibits user classes from being imported into the new Program object.

PO_NO_CHILD_PO_RESTRICTIONS

no-child-restrictions

Allows child program objects to have fewer parse restrictions than the parent object.

PO_NO_EXTERNAL_PROCESS

no-external-process

Disallows any access to external processes (with system(), backquote(), exec(), etc).

PO_REQUIRE_OUR

require-our

Requires global variables to be declared with our before use.

PO_NO_PROCESS_CONTROL

no-process-control

Disallows access to functions that would affect the current process (exit(), exec(), fork(), etc).

PO_NO_NETWORK

no-network

Disallows access to network functions.

PO_NO_FILESYSTEM

no-filesystem

Disallows access to the filesystem.

PO_LOCK_WARNINGS

lock-warnings

Disallows changes to the warning mask.

PO_NO_DATABASE

no-database

Disallows access to database functionality.

PO_NO_GUI

no-gui

Disallows access to functionality that draws graphics to the display.

PO_NO_TERMINAL_IO

no-terminal-io

Disallows access to reading from and/or writing to the terminal.


Table 4.338. Program Method Overview

Method

Except?

Description

Program::constructor()

N

Creates the program object and optionally sets program capabilities (parse options)

Program::destructor()

N

Destroys the object. Blocks until all threads have terminated.

Program::copy()

Y

Throws an exception to prevent objects of this class from being copied.

Program::callFunction()

Y

Calls a function in the program object and returns the return value.

Program::callFunctionArgs()

Y

Calls a function in the program object with the arguments given as a list

Program::disableParseOptions()

Y

Removes the given parse options to the current parse option mask.

Program::existsFunction()

N

Checks if a user function exists in the program object

Program::getGlobalVariable()

N

Returns a the value of the global variable identified by the first string argument.

Program::getParseOptions()

N

Returns a code of parse options set in the object.

Program::getScriptDir()

N

Returns the current script directory (if any).

Program::getScriptName()

N

Returns the current script name (if any).

Program::getScriptPath()

N

Returns the current script directory and filename (if any).

Program::getUserFunctionList()

N

Returns a list of all user functions defined in the program object.

Program::importFunction()

Y

Imports a user function into the program object's space; any calls to the function will run in the parent's space.

Program::importGlobalVariable()

Y

Imports a global variable into the Program object's space. If the variable is an object, then any methods called will run in the parent's space.

Program::lockOptions()

N

Locks parse options so that they cannot be changed.

Program::parse()

Y

Performs a complete parse and commit of the string passed

Program::parseCommit()

Y

Commits all pending changes to the program object.

Program::parsePending()

Y

Performs a 1st stage parse of the string passed

Program::parseRollback()

Y

Rolls back all pending changes to the program object

Program::run()

Y

Runs the top-level code of the program object

Program::setParseOptions()

Y

Adds the given parse options to the current parse option mask.

Program::setScriptPath()

N

Sets the script path (directory and filename) for the object.


4.8.1. Program::constructor()

Synopsis

Creates the Program object. It accepts one optional argument that will set the program capabilities for the program object.

Usage
new Program([integer:parse_options])
Example
$pgm = new Program();

Table 4.339. Arguments for Program::constructor()

Argument

Type

Description

parse_options

Integer

A binary OR'ed product of parse options.


Table 4.340. Return Values for Program::constructor()

Return Type

Description

Object

The Program object created.


4.8.2. Program::destructor()

Synopsis

Destroys the object. If any threads are running in the program, the destructor will block until the threads terminate.

Usage
delete lvalue
Example
delete $pgm;

4.8.3. Program::copy()

Synopsis

Throws an exception; objects of this class cannot be copied.

Table 4.341. Arguments for Program::copy()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.342. Return Values for Program::copy()

Return Type

Description

n/a

This method returns no value because it throws an exception.


Table 4.343. Exceptions Thrown by Program::copy()

err

desc

PROGRAM-COPY-ERROR

Objects of this class cannot be copied.


4.8.4. Program::callFunction()

Synopsis

Calls a function in the program object and returns the return value. The function runs with the permissions of the Program object containing the function.

Usage
Program::callFunction(string:function_name, [args ...])
Example
$result = $pgm.callFunction("func_name", $arg1, $arg2);

Table 4.344. Arguments for Program::callFunction()

Argument

Type

Description

function_name

String

The name of the function to call.

[args ...]

Any

The remaining arguments passed to the method are passed to the function to be called.


Table 4.345. Return Values for Program::callFunction()

Return Type

Description

Any

Depends on the function being called.


Table 4.346. Exceptions Thrown by Program::callFunction()

err

desc

INVALID-FUNCTION-ACCESS

Parse options do not allow this builtin function to be called.

NO-FUNCTION

The function does not exist.


4.8.5. Program::callFunctionArgs()

Synopsis

Calls a function in the program object and returns the return value, using the second argument as the argument list for the function call. The function runs with the permissions of the Program object containing the function.

Usage
Program::callFunctionArgs(string:function_name, [arg_list])
Example
$result = $pgm.callFunctionArgs("func_name", $arg_list);

Table 4.347. Arguments for Program::callFunctionArgs()

Argument

Type

Description

function_name

String

The name of the function to call.

[arg_list]

List

Argument list to be passed to the function.


Table 4.348. Return Values for Program::callFunctionArgs()

Return Type

Description

Any

Depends on the function being called.


Table 4.349. Exceptions Thrown by Program::callFunctionArgs()

err

desc

INVALID-FUNCTION-ACCESS

Parse options do not allow this builtin function to be called.

NO-FUNCTION

The function does not exist.


4.8.6. Program::disableParseOptions()

Synopsis

Disables parse options in the parse option mask for the Program object. An exception is thrown if parse options have been locked (for example with Program::lockOptions()). For a reciprocal method that sets parse options, see Program::setParseOptions().

Usage
Program::disableParseOptions(options)
Example
# allow threading and GUI operations
$pgm.disableParseOptions(PO_NO_THREADS | PO_NO_GUI);

Table 4.350. Arguments for Program::disableParseOptions()

Argument

Type

Description

options

Integer

A single parse option or binary-or combination of parse options to disable in the parse option mask for the current object.


Table 4.351. Return Values for Program::disableParseOptions()

Return Type

Description

n/a

This method returns no value; if an error occurs an exception is raised.


Table 4.352. Exceptions Thrown by Program::disableParseOptions()

err

desc

OPTIONS-LOCKED

Parse options have been locked and cannot be changed.


4.8.7. Program::existsFunction()

Synopsis

Checks if a user function exists in the program object.

Usage
Program::existsFunction(function_name)
Example
$bool = $pgm.existsFunction("func_name");

Table 4.353. Arguments for Program::existsFunction()

Argument

Type

Description

function_name

String

The name of the function to check.


Table 4.354. Return Values for Program::existsFunction()

Return Type

Description

Boolean

Returns True if the function exists, False if not.


4.8.8. Program::getGlobalVariable()

Synopsis

Returns the value of the global variable identified by the first string argument giving the name of the variable (without any leading "$" symbol. An lvalue reference can be passed as the second argument in order to determine if the global variable exists (because this method could return NOTHING when the variable exists as well as when it does not).

Usage
Program::getGlobalVariable(var_name, [exists_ref])
Example
$val = $pgm.getGlobalVariable("error_count", \$exists);

Table 4.355. Arguments for Program::getGlobalVariable()

Argument

Type

Description

var_name

String

The string name of the variable to find, not including the leading "$" character.

[exists]

Reference

If a reference is passed in this position, it will contain a boolean value after the method exits: if this value is True, that means that the variable exists in the Program object, False means that the variable does not exist.


Table 4.356. Return Values for Program::getParseOptions()

Return Type

Description

Any

The value of the global variable (or NOTHING if it does not exist; note that also the variable could exist and return NOTHING as well; use a reference as the second argument to the method to determine if the variable exists or not).


This method does not throw any exceptions.

4.8.9. Program::getParseOptions()

Synopsis

Returns the current binary-or parse option mask for the Program object.

Usage
Program::getParseOptions()
Example
$mask = $pgm.getParseOptions();

Table 4.357. Arguments for Program::getParseOptions()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.358. Return Values for Program::getParseOptions()

Return Type

Description

Integer

A mask of all parse options set (combined with binary or) for the current object.


4.8.10. Program::getScriptDir()

Synopsis

Gets the script directory set with Program::setScriptPath(). This is the same value that will be returned in the Qore program code with the get_script_dir() function if called from within the Program. The value returned should normally include the trailing '/' character.

Usage
Program::getScriptDir()
Example
my $dir = $pgm.getScriptDir();

Table 4.359. Arguments for Program::getScriptDir()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.360. Return Values for Program::getScriptDir()

Return Type

Description

String

The current script directory.


This method does not throw any exceptions.

4.8.11. Program::getScriptName()

Synopsis

Gets the script filename set with Program::setScriptPath(). This is the same value that will be returned in the Qore program code with the get_script_path() function if called from within the Program.

Usage
Program::getScriptName()
Example
my $name = $pgm.getScriptName();

Table 4.361. Arguments for Program::getScriptName()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.362. Return Values for Program::getScriptName()

Return Type

Description

String

The current script name if known, otherwise returns NOTHING.


This method does not throw any exceptions.

4.8.12. Program::getScriptPath()

Synopsis

Gets the script directory and filename set with Program::setScriptPath(). This is the same value that will be returned in the Qore program code with the get_script_path() function if called from within the Program.

Usage
Program::getScriptPath()
Example
my $path = $pgm.getScriptPath();

Table 4.363. Arguments for Program::getScriptPath()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.364. Return Values for Program::getScriptPath()

Return Type

Description

String

The current script directory and filename if known, otherwise returns NOTHING.


This method does not throw any exceptions.

4.8.13. Program::getUserFunctionList()

Synopsis

Returns a list of all user functions defined in the Program object.

Usage
Program::getUserFunctionList()
Example
$list = $pgm.getUserFunctionList();

Table 4.365. Arguments for Program::getUserFunctionList()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.366. Return Values for Program::getUserFunctionList()

Return Type

Description

List

A list of strings giving the names of all functions implemented in the program object.


4.8.14. Program::importFunction()

Synopsis

Imports a user function into the program object's space; any calls to the imported function will run in the parent's space. This allows a user-defined API with greater capabilities than the embedded Program object to be imported into the embedded code.

Usage
Program::importFunction(function_name)
Example
$pgm.importFunction("function");

Table 4.367. Arguments for Program::importFunction()

Argument

Type

Description

function_name

String

The name of the function to import.


Table 4.368. Return Values for Program::importFunction()

Return Type

Description

n/a

This method does not return any value.


Table 4.369. Exceptions Thrown by Program::importFunction()

err

desc

PROGRAM-IMPORTFUNCTION-PARAMETER-ERROR

No function name was passed to the method.

PROGRAM-IMPORTFUNCTION-PARAMETER-ERROR

Cannot import a function into the same Program object.

PROGRAM-IMPORTFUNCTION-NO-FUNCTION

The function does not exist.


4.8.15. Program::importGlobalVariable()

Synopsis

Imports a global variable into the program object's space. If the variable is an object, then any methods called from the subprogram will run in the parent's space.

Usage
Program::importGlobalVariable(string:name, [boolean:read_only])
Example
$pgm.importGlobalVariable("var");

Table 4.370. Arguments for Program::importGlobalVariable()

Argument

Type

Description

name

String

The name of the global variable without the $

[read_only]

Boolean

If this argument is present and is True, then the variable will be imported read-only, and cannot be changed by the subprogram.


Table 4.371. Return Values for Program::importGlobalVariable()

Return Type

Description

n/a

This method does not return any value.


Table 4.372. Exceptions Thrown by Program::importGlobalVariable()

err

desc

PROGRAM-IMPORTGLOBALVARIABLE-PARAMETER-ERROR

No variable name was passed to the method.

PROGRAM-IMPORTGLOBALVARIABLE-EXCEPTION

The global variable does not exist.


4.8.16. Program::lockOptions()

Synopsis

Locks parse options so they cannot be changed.

Usage
Program::lockParseOptions()
Example
$pgm.lockParseOptions();

Table 4.373. Arguments for Program::lockParseOptions()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.374. Return Values for Program::lockOptions()

Return Type

Description

n/a

This method does not return any value; it always succeeds.


This method does not throw any exceptions.

4.8.17. Program::parse()

Synopsis

Parses the string argument and adds the code to the program object.

Usage
Program::parse(string, label)
Example
$pgm.parse($code, "label");

Table 4.375. Arguments for Program::parse()

Argument

Type

Description

string

String

The code to parse.

label

String

The code to parse.


Table 4.376. Return Values for Program::parse()

Return Type

Description

n/a

This method does not return any value.


Table 4.377. Exceptions Thrown by Program::parse()

err

desc

PARSE-ERROR

An error occurred parsing the text.


4.8.18. Program::parseCommit()

Synopsis

Commits and pending code processed with Program::parsePending() to the Program object and resolves all outstanding references in the pending code. An exception in this method causes all pending code to be rolled back immediately.

Usage
Program::parseCommit()
Example
$pgm.parseCommit();

Table 4.378. Arguments for Program::parseCommit()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.379. Return Values for Program::parseCommit()

Return Type

Description

n/a

This method does not return any value.


Table 4.380. Exceptions Thrown by Program::parseCommit()

err

desc

PARSE-ERROR

An error occurred parsing the text.


4.8.19. Program::parsePending()

Synopsis

Parses the text passed to pending lists in the Program object; does not resolve all references or commit the code to the Program object. References are resolved in the Program::parseCommit() method. If an exception occurs in this method, all pending code is backed out, not just code parsed by this method.

Usage
Program::parsePending(string, label)
Example
$pgm.parsePending($code, "label");

Table 4.381. Arguments for Program::parsePending()

Argument

Type

Description

string

String

The code to parse.

label

String

The code to parse.


Table 4.382. Return Values for Program::parsePending()

Return Type

Description

n/a

This method does not return any value.


Table 4.383. Exceptions Thrown by Program::parsePending()

err

desc

PARSE-ERROR

An error occurred parsing the text.


4.8.20. Program::parseRollback()

Synopsis

Rolls back any pending code processed with Program::parsePending() that has not yet been committed to the Program object with Program::parseCommit()

Usage
Program::parseRollback()
Example
$pgm.parseRollback();

Table 4.384. Arguments for Program::parseRollback()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.385. Return Values for Program::parseRollback()

Return Type

Description

n/a

This method does not return any value.


4.8.21. Program::run()

Synopsis

Runs the program and optionally returns a value if the top-level code exits with a return statement.

Usage
Program::run()
Example
$pgm.run();

Table 4.386. Arguments for Program::run()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.387. Return Values for Program::run()

Return Type

Description

Any

Depends on the program - any final return statement will return a value to this method.


4.8.22. Program::setParseOptions()

Synopsis

Sets parse options in the parse option mask for the Program object. An exception is thrown if parse options have been locked (for example with Program::lockOptions()). For a reciprocal method that disables parse options, see Program::disableParseOptions().

Usage
Program::setParseOptions(options)
Example
# disallow threading and GUI operations
$pgm.setParseOptions(PO_NO_THREADS | PO_NO_GUI);

Table 4.388. Arguments for Program::setParseOptions()

Argument

Type

Description

options

Integer

A single parse option or binary-or combination of parse options to set in the parse option mask for the current object.


Table 4.389. Return Values for Program::setParseOptions()

Return Type

Description

n/a

This method returns no value; if an error occurs an exception is raised.


Table 4.390. Exceptions Thrown by Program::setParseOptions()

err

desc

OPTIONS-LOCKED

Parse options have been locked and cannot be changed.


4.8.23. Program::setScriptPath()

Synopsis

Sets the script path (directory and filename) for later retrieval with Program::getScriptPath(), Program::getScriptDir(), or Program::getScriptName() calls, or from code within the Program object with the get_script_path(), get_script_dir(), or get_script_name() functions.

Usage
Program::setScriptPath(path_string)
Example
$pgm.setScriptPath("/users/test/test.q");

Table 4.391. Arguments for Program::setScriptPath()

Argument

Type

Description

path_string

String

The path (directory and filename) for the current script. If the directory component is missing, then "./" is assumed.


Table 4.392. Return Values for Program::setScriptPath()

Return Type

Description

n/a

This method does not return any value.


This method does not throw any exceptions.