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 | Disallows the use of global variables. | |
PO_NO_SUBROUTINE_DEFS | Disallows subroutine (function) definitions. | |
PO_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 | Disallows access to any thread classes. | |
PO_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 | Disallows top level code. | |
PO_NO_CLASS_DEFS | Disallows class definitions. | |
PO_NO_NAMESPACE_DEFS | Disallows new namespace definitions. | |
PO_NO_CONSTANT_DEFS | Disallows constant definitions. | |
PO_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 | Allows child program objects to have fewer parse restrictions than the parent object. | |
PO_NO_EXTERNAL_PROCESS | Disallows any access to external processes (with system(), backquote(), exec(), etc). | |
PO_REQUIRE_OUR | Requires global variables to be declared with our before use. | |
PO_NO_PROCESS_CONTROL | Disallows access to functions that would affect the current process (exit(), exec(), fork(), etc). | |
PO_NO_NETWORK | Disallows access to network functions. | |
PO_NO_FILESYSTEM | Disallows access to the filesystem. | |
PO_LOCK_WARNINGS | Disallows changes to the warning mask. | |
PO_NO_DATABASE | Disallows access to database functionality. | |
PO_NO_GUI | Disallows access to functionality that draws graphics to the display. | |
PO_NO_TERMINAL_IO | Disallows access to reading from and/or writing to the terminal. |
Table 4.338. Program Method Overview
Method | Except? | Description |
---|---|---|
N | Creates the program object and optionally sets program capabilities (parse options) | |
N | Destroys the object. Blocks until all threads have terminated. | |
Y | Throws an exception to prevent objects of this class from being copied. | |
Y | Calls a function in the program object and returns the return value. | |
Y | Calls a function in the program object with the arguments given as a list | |
Y | Removes the given parse options to the current parse option mask. | |
N | Checks if a user function exists in the program object | |
N | Returns a the value of the global variable identified by the first string argument. | |
N | Returns a code of parse options set in the object. | |
N | Returns the current script directory (if any). | |
N | Returns the current script name (if any). | |
N | Returns the current script directory and filename (if any). | |
N | Returns a list of all user functions defined in the program object. | |
Y | Imports a user function into the program object's space; any calls to the function will run in the parent's space. | |
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. | |
N | Locks parse options so that they cannot be changed. | |
Y | Performs a complete parse and commit of the string passed | |
Y | Commits all pending changes to the program object. | |
Y | Performs a 1st stage parse of the string passed | |
Y | Rolls back all pending changes to the program object | |
Y | Runs the top-level code of the program object | |
Y | Adds the given parse options to the current parse option mask. | |
N | Sets the script path (directory and filename) for the object. |
Creates the Program object. It accepts one optional argument that will set the program capabilities for the program object.
new Program([integer:parse_options
])
$pgm = new Program();
Table 4.339. Arguments for Program::constructor()
Argument | Type | Description |
---|---|---|
| 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. |
Destroys the object. If any threads are running in the program, the destructor will block until the threads terminate.
delete lvalue
delete $pgm;
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 |
---|---|
| Objects of this class cannot be copied. |
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.
Program::callFunction(string:function_name, [args ...]
)
$result = $pgm.callFunction("func_name", $arg1, $arg2);
Table 4.344. Arguments for Program::callFunction()
Argument | Type | Description |
---|---|---|
| String | The name of the function to call. |
| 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 |
---|---|
| Parse options do not allow this builtin function to be called. |
| The function does not exist. |
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.
Program::callFunctionArgs(string:function_name, [arg_list]
)
$result = $pgm.callFunctionArgs("func_name", $arg_list);
Table 4.347. Arguments for Program::callFunctionArgs()
Argument | Type | Description |
---|---|---|
| String | The name of the function to call. |
| 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 |
---|---|
| Parse options do not allow this builtin function to be called. |
| The function does not exist. |
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().
Program::disableParseOptions(options
)
# allow threading and GUI operations $pgm.disableParseOptions(PO_NO_THREADS | PO_NO_GUI);
Table 4.350. Arguments for Program::disableParseOptions()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| Parse options have been locked and cannot be changed. |
Checks if a user function exists in the program object.
Program::existsFunction(function_name
)
$bool = $pgm.existsFunction("func_name");
Table 4.353. Arguments for Program::existsFunction()
Argument | Type | Description |
---|---|---|
| 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. |
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).
Program::getGlobalVariable(var_name, [exists_ref]
)
$val = $pgm.getGlobalVariable("error_count", \$exists);
Table 4.355. Arguments for Program::getGlobalVariable()
Argument | Type | Description |
---|---|---|
| String | The string name of the variable to find, not including the leading "$" character. |
| 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.
Returns the current binary-or parse option mask for the Program object.
Program::getParseOptions()
$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. |
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.
Program::getScriptDir()
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.
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.
Program::getScriptName()
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.
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.
Program::getScriptPath()
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.
Returns a list of all user functions defined in the Program object.
Program::getUserFunctionList()
$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. |
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.
Program::importFunction(function_name
)
$pgm.importFunction("function");
Table 4.367. Arguments for Program::importFunction()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| No function name was passed to the method. |
| Cannot import a function into the same Program object. |
| The function does not exist. |
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.
Program::importGlobalVariable(string:name, [boolean:read_only]
)
$pgm.importGlobalVariable("var");
Table 4.370. Arguments for Program::importGlobalVariable()
Argument | Type | Description |
---|---|---|
| String | The name of the global variable without the $ |
| 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 |
---|---|
| No variable name was passed to the method. |
| The global variable does not exist. |
Locks parse options so they cannot be changed.
Program::lockParseOptions()
$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.
Parses the string argument and adds the code to the program object.
Program::parse(string
,label
)
$pgm.parse($code, "label");
Table 4.375. Arguments for Program::parse()
Argument | Type | Description |
---|---|---|
| String | The code to parse. |
| 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 |
---|---|
| An error occurred parsing the text. |
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.
Program::parseCommit()
$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 |
---|---|
| An error occurred parsing the text. |
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.
Program::parsePending(string
,label
)
$pgm.parsePending($code, "label");
Table 4.381. Arguments for Program::parsePending()
Argument | Type | Description |
---|---|---|
| String | The code to parse. |
| 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 |
---|---|
| An error occurred parsing the text. |
Rolls back any pending code processed with Program::parsePending() that has not yet been committed to the Program object with Program::parseCommit()
Program::parseRollback()
$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. |
Runs the program and optionally returns a value if the top-level code exits with a return statement.
Program::run()
$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. |
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().
Program::setParseOptions(options
)
# disallow threading and GUI operations $pgm.setParseOptions(PO_NO_THREADS | PO_NO_GUI);
Table 4.388. Arguments for Program::setParseOptions()
Argument | Type | Description |
---|---|---|
| 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 |
---|---|
| Parse options have been locked and cannot be changed. |
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.
Program::setScriptPath(path_string
)
$pgm.setScriptPath("/users/test/test.q");
Table 4.391. Arguments for Program::setScriptPath()
Argument | Type | Description |
---|---|---|
| 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.