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.290. Parse Options
Constant | Details | Description |
|---|---|---|
| Prohibits the use of the | |
| Assume local variable scope when variables are first referenced if no my or our is present. | |
| no parse options | This option is the empty option, meaning no options are set. |
| Sets both | |
| Disallows the use of global variables. | |
| Disallows subroutine (function) definitions. | |
| 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). | |
| Disallows access to any thread classes. | |
| Disallows access to any thread-control functions and thread-relevant statements and operators (for example the background operator and the thread_exit statement). | |
| Disallows top level code. | |
| Disallows class definitions. | |
| Disallows new namespace definitions. | |
| Disallows constant definitions. | |
| Disallows use of the new operator. | |
| n/a | Prohibits system classes from being imported into the new Program object. |
| n/a | Prohibits user classes from being imported into the new Program object. |
| Allows child program objects to have fewer parse restrictions than the parent object. | |
| Disallows access to functionality that provides information about the computing environment. | |
| Disallows any access to external processes (with system(), backquote(), exec(), etc). | |
| Requires global variables to be declared with our before use. | |
| Disallows access to functions that would affect the current process (exit(), exec(), fork(), etc). | |
| Prohibits the warning mask from being changed. | |
| Disallows access to network functions. | |
| Disallows access to the filesystem. | |
| Disallows changes to the warning mask. | |
| Disallows access to database functionality. | |
| Disallows access to functionality that draws graphics to the display. | |
| Disallows access to reading from and/or writing to the terminal. | |
| Disallows access to functionality that provides information about threading. | |
| Disallows access to functionality that can change locale parameters. | |
| Requires all function and method parameters and return types to have type declarations. Variables and object members are not required to have type declarations. | |
| Requires all function and method parameters, return types, variables, and object members to have type declarations. Additionally, this option implies | |
| Prohibits access to builtin functions and methods flagged with |
Table 4.291. 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 | Sets a parse define for the current Program. |
|
| Y | Removes the given parse options to the current parse option mask. |
|
| N | Checks if a user function exists in the program object |
|
| N | Retrieves the value of the given parse define in the current Program. |
|
| 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 as a string or NOTHING if not set. | |
N | Returns the current script name as a string or NOTHING if not set. | |
N | Returns the current script directory and filename as a string or NOTHING if not set. | |
N | Returns the default local time zone for the object. | |
N | Returns a list of strings 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 | Returns |
N | Locks parse options so that they cannot be changed. | |
|
| Y | Performs a complete parse and commit of the string passed; if a warning mask is given and warnings are raised, then the method returns an exception hash. |
|
| Y | Commits all pending changes to the program object; if a warning mask is given and warnings are raised, then the method returns an exception hash. |
|
| Y | Performs a 1st stage parse of the string passed; if a warning mask is given and warnings are raised, then the method returns an exception hash. |
N | Rolls back all pending changes to the program object | |
Y | Runs the top-level code of the program object | |
|
| Y | Replaces the current parse option mask with the parse options given as an argument; an exception is thrown if the calling Program object does not have PO_NO_CHILD_PO_RESTRICTIONS set. |
|
| Y | Adds the given parse options to the current parse option mask. |
|
| N | Sets (or clears) the script path (directory and filename) for the object. |
|
| N | Sets the default local time zone for the object. |
|
| Y | Sets the default local time zone for the object from a path to a zoneinfo time zone region file. |
|
| N | Sets the default local time zone for the object from a UTC offset in seconds east of UTC; for zones west of UTC, use negative numbers. |
|
| Y | Undefines the given parse define in the current Program. |
Creates the Program object. It accepts one optional argument that will set the program capabilities for the program object.
Note that if PO_NO_CHILD_PO_RESTRICTIONS is not set in the parent Program when the new Program object is created, then the created Program object will have the parent's parse options added to its parse options as given by the argument to the constructor; in other words, if PO_NO_CHILD_PO_RESTRICTIONS is not set, it's not possible to create a child Program object with fewer restrictions than the parent Program object (any attempt to do so will be silently ignored). However, if PO_NO_CHILD_PO_RESTRICTIONS is set in the parent Program object, then the parse option argument to the constructor will be applied literally to the child object.
Program::constructor(softint $options = PO_DEFAULT)
my Program $pgm();
Table 4.292. Arguments for Program::constructor()
Argument | Description |
|---|---|
| A binary OR'ed product of parse options. |
Destroys the object. If any threads are running in the program, the destructor will block until the threads terminate.
delete $pgm;
Throws an exception; objects of this class cannot be copied.
Table 4.293. 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.
any Program::callFunction(string $func, ...)
$result = $pgm.callFunction("func_name", $arg1, $arg2);
Table 4.294. Arguments for Program::callFunction()
Argument | Description |
|---|---|
| The name of the function to call. |
| The remaining arguments passed to the method are passed to the function to be called. |
Table 4.295. Return Values for Program::callFunction()
Return Type | Description |
|---|---|
Depends on the function being called. |
Table 4.296. 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.
any Program::callFunctionArgs(string $func, list $args)
any Program::callFunctionArgs(string $func, any $args)
$result = $pgm.callFunctionArgs("func_name", $arg_list);
Table 4.298. Return Values for Program::callFunctionArgs()
Return Type | Description |
|---|---|
Depends on the function being called. |
Table 4.299. Exceptions Thrown by Program::callFunctionArgs()
err | desc |
|---|---|
| Parse options do not allow this builtin function to be called. |
| The function does not exist. |
Sets a parse define for the current Program.
nothing Program::define(string $def, any $val)
$pgm.define("PRODUCTION", True);
This method will only throw an exception if the old value of the define was an object, and this call causes the object to go out of scope, and the object's destructor throws an exception.
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().
See also Program::replaceParseOptions().
nothing Program::disableParseOptions(int $options = PO_DEFAULT)
# allow threading and GUI operations $pgm.disableParseOptions(PO_NO_THREADS | PO_NO_GUI);
Table 4.301. Arguments for Program::disableParseOptions()
Argument | Description |
|---|---|
| A single parse option or binary-or combination of parse options to disable in the parse option mask for the current object. |
Table 4.302. 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 Program::existsFunction(string $func)
Table 4.303. Arguments for Program::existsFunction()
Argument | Description |
|---|---|
| The name of the function to check. |
Table 4.304. Return Values for Program::existsFunction()
Return Type | Description |
|---|---|
Returns |
Retrieves the value of the given parse define in the current Program.
any Program::getDefine(string $def)
my any $val = $pgm.getDefine("PRODUCTION");
Table 4.305. Arguments for Program::getDefine()
Argument | Description |
|---|---|
| The name of the define to retrieve. |
Table 4.306. Return Values for Program::getDefine()
Return Type | Description |
|---|---|
The value of the given parse define; note that a parse define may be defined with no value; use Program::isDefined to check if a parse define is actually defined or 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).
any Program::getGlobalVariable(string $name)
any Program::getGlobalVariable(string $name, reference $found)
$val = $pgm.getGlobalVariable("error_count", \$exists);
Table 4.307. Arguments for Program::getGlobalVariable()
Argument | Description |
|---|---|
| The string name of the variable to find, not including the leading "$" character. |
| If a reference is passed in this position, it will contain a boolean value after the method exits: if this value is |
This method does not throw any exceptions.
Returns the current binary-or parse option mask for the Program object.
$mask = $pgm.getParseOptions();
Table 4.309. Return Values for Program::getParseOptions()
Return Type | Description |
|---|---|
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.
my *string $dir = $pgm.getScriptDir();
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.
my *string $name = $pgm.getScriptName();
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.
my *string $path = $pgm.getScriptPath();
This method does not throw any exceptions.
Returns the default local time zone for the object.
See also TimeZone::get()
my TimeZone $zone = $pgm.getTimeZone();
Table 4.313. Return Values for Program::getTimeZone()
Return Type | Description |
|---|---|
Returns the default local time zone for the object. |
This method does not throw any exceptions.
Returns a list of all user functions defined in the Program object.
my list $l = $pgm.getUserFunctionList();
Table 4.314. Return Values for Program::getUserFunctionList()
Return Type | Description |
|---|---|
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.
nothing Program::importFunction(string $name)
nothing Program::importFunction(string $name, string $new_name)
$pgm.importFunction("function");
Table 4.316. Exceptions Thrown by Program::importFunction()
err | desc |
|---|---|
| Cannot import a function into the same Program object; function with this name already exists. |
| 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.
nothing Program::importGlobalVariable(string $name, bool $readonly = False)
$pgm.importGlobalVariable("var");
Table 4.318. Exceptions Thrown by Program::importGlobalVariable()
err | desc |
|---|---|
| The global variable does not exist. |
Returns True if the given parse define is defined in the current Program (does not have to have a value defined to return True).
bool Program::isDefined(string $def)
my bool $b = $pgm.isDefined("PRODUCTION");
Table 4.319. Arguments for Program::isDefined()
Argument | Description |
|---|---|
| The name of the define to check. |
Table 4.320. Return Values for Program::isDefined()
Return Type | Description |
|---|---|
|
Locks parse options so they cannot be changed.
$pgm.lockOptions();
This method does not throw any exceptions.
Parses the string argument and adds the code to the program object.
If a warning mask is given and masked warnings are raised during parsing, this method will return a hash with warning information.
nothing Program::parse(string $code, string $label)
*hash Program::parse(string $code, string $label, softint $warn_mask)
$pgm.parse($code, "label");
Table 4.321. Arguments for Program::parse()
Argument | Description |
|---|---|
| The code to parse. |
| A label identifying the code. |
| An optional warning mask of bitwise-ORed warning values; if this option is non-zero and any warnings are raised during parsing, then a hash is returned of warning information. |
Table 4.322. Return Values for Program::parse()
Return Type | Description |
|---|---|
If a warning mask is set and any masked warnings are raised during parsing, then an exception hash of warning information is returned (multiple warnings are linked in the hash through the "next" key, as with chained exceptions). |
Table 4.323. 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.
If a warning mask is given and masked warnings are raised during parsing, this method will return a hash with warning information.
nothing Program::parseCommit()
*hash Program::parseCommit(softint $warn_mask)
$pgm.parseCommit();
Table 4.324. Arguments for Program::parseCommit()
Argument | Description |
|---|---|
| An optional warning mask of bitwise-ORed warning values; if this option is non-zero and any warnings are raised during parsing, then a hash is returned of warning information. |
Table 4.325. Return Values for Program::parseCommit()
Return Type | Description |
|---|---|
If a warning mask is set and any masked warnings are raised during parsing, then an exception hash is returned of warning information (multiple warnings are linked in the hash through the "next" key, as with chained exceptions). |
Table 4.326. 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.
If a warning mask is given and masked warnings are raised during parsing, this method will return a hash with warning information.
nothing Program::parsePending(string $code, string $label)
*hash Program::parsePending(string $code, string $label, softint $warn_mask)
$pgm.parsePending($code, "label");
Table 4.327. Arguments for Program::parsePending()
Argument | Description |
|---|---|
| The code to parse. |
| A label identifying the code. |
| An optional warning mask of bitwise-ORed warning values; if this option is non-zero and any warnings are raised during parsing, then a hash is returned of warning information. |
Table 4.328. Return Values for Program::parsePending()
Return Type | Description |
|---|---|
If a warning mask is set and any masked warnings are raised during parsing, then an exception hash is returned of warning information (multiple warnings are linked in the hash through the "next" key, as with chained exceptions). |
Table 4.329. 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()
$pgm.parseRollback();
Runs the program and optionally returns a value if the top-level code exits with a return statement.
$pgm.run();
Table 4.330. Return Values for Program::run()
Return Type | Description |
|---|---|
Depends on the program; any return statement at the top level of the program will return a value to this method. |
Replaces the parse options for the Program object; an exception is thrown if the calling Program object does not have PO_NO_CHILD_PO_RESTRICTIONS set.
See also Program::setParseOptions() and Program::disableParseOptions().
nothing Program::replaceParseOptions(int $options)
# disallow threading and GUI operations $pgm.replaceParseOptions(PO_NO_THREADS | PO_NO_GUI);
Table 4.331. Arguments for Program::replaceParseOptions()
Argument | Description |
|---|---|
| A single parse option or binary-or combination of parse options to set in the parse option mask for the current object. |
Table 4.332. Exceptions Thrown by Program::replaceParseOptions()
err | desc |
|---|---|
| the calling Program does not have the PO_NO_CHILD_PO_RESTRICTIONS option set, and therefore cannot call Program::replaceParseOptions(). |
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().
See also Program::replaceParseOptions().
nothing Program::setParseOptions(int $options = PO_DEFAULT)
# disallow threading and GUI operations $pgm.setParseOptions(PO_NO_THREADS | PO_NO_GUI);
Table 4.333. Arguments for Program::setParseOptions()
Argument | Description |
|---|---|
| A single parse option or binary-or combination of parse options to set in the parse option mask for the current object. |
Table 4.334. 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.
nothing Program::setScriptPath(string $path)
$pgm.setScriptPath("/users/test/test.q");
Table 4.335. Arguments for Program::setScriptPath()
Argument | Description |
|---|---|
| The path (directory and filename) for the current script. If the directory component is missing, then "./" is assumed. |
This method does not throw any exceptions.
Sets the default local time zone for the object.
See also TimeZone::set().
nothing Program::setTimeZone(TimeZone $zone)
$pgm.setTimeZone($zone);
Table 4.336. Arguments for Program::setTimeZone()
Argument | Description |
|---|---|
| The time zone to set as the local time zone for the Program object. |
This method does not throw any exceptions.
Sets the default local time zone for the object from a path to a zoneinfo time zone region file; if there are errors reading or parsing the file, an exception is thrown.
See also TimeZone::setRegion().
nothing Program::setTimeZoneRegion(string $region)
$pgm.setTimeZoneRegion("Europe/Prague");
Table 4.337. Arguments for Program::setTimeZoneRegion()
Argument | Description |
|---|---|
| The path to the zoneinfo file for the time zone region to set as the local time zone for the Program object. |
Table 4.338. Exceptions Thrown by Program::setTimeZoneRegion()
err | desc |
|---|---|
| Unable to read zoneinfo file; invalid file magic; error parsing zoneinfo file, etc |
Sets the default time zone for the Program object based on the number of seconds east of UTC; for zones west of UTC, use negative numbers.
Time zones set with this method cannot have any daylight savings time information; to set a zone with daylight savings time information, use Program::setTimeZoneRegion() instead.
See also TimeZone::setUTCOffset().
nothing Program::setTimeZoneUTCOffset(softint $secs_east)
The following examples are all equivalent, setting the time zone to +02 UTC:
$pgm.setTimeZoneUTCOffset(7200);
$pgm.setTimeZoneUTCOffset(2h);
$pgm.setTimeZoneUTCOffset(PT2H);
Table 4.339. Arguments for Program::setTimeZone()
Argument | Description |
|---|---|
| The number of seconds east of UTC; for zones west of UTC, use negative numbers |
This method does not throw any exceptions.
Undefines the given parse define in the current Program.
nothing Program::undefine(string $def)
$pgm.undefine("PRODUCTION");
Table 4.340. Arguments for Program::undefine()
Argument | Description |
|---|---|
| The name of the define to remove. |
This method will only throw an exception if the old value of the define was an object, and this call causes the object to go out of scope, and the object's destructor throws an exception.