Qore Programming Language Reference Manual: Qore::Program Class Reference (original) (raw)

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

#include <[QC_Program.dox.h](%5Fq%5Fc%5F%5F%5Fprogram%5F8dox%5F8h%5Fsource.html)>

Program objects allow Qore programs to support subprograms with the option to restrict 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.

A complete parse action (Program::parse() or Program::parseCommit()) can only be performed once; subsequent attempts to parse code into the same Program object will fail with an exception. If parsing fails due to a parse exception, the Program object is generally no longer usable and must be recreated to be used.

Parse option constants 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 qore Executable Command-Line Processing 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.

Classes, constants, namespaces, functions, and global variables are only inherited into child Program objects if they are declared public and no parse options prohibit it.

Symbols can also be imported into Program objects singly using methods such as Program::importClass() and Program::importGlobalVariable(), etc.

◆ callFunction()

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.

Parameters

Returns

Depends on the function being called

Example:

auto result = pgm.callFunction("func_name", arg1, arg2);

Exceptions

Note

The function called could also cause other exceptions to be thrown

◆ callFunctionArgs()

Calls a function in the program object giving the arguments to the function as a list and returns the return value.

The function runs with the permissions of the Program object containing the function.

Parameters

Returns

Depends on the function being called

Example:

auto result = pgm.callFunctionArgs("func_name", (arg1, arg2));

Exceptions

Note

The function called could also cause other exceptions to be thrown

◆ callStaticMethod()

Calls a static method of an object, passing the arguments to the function as arguments to the method.

Example:

auto result = p.callStaticMethod("Namespace::Class::method", arg1, arg2);

Parameters

Returns

the value returned by the method call

Exceptions

Note

the method called could cause additional exceptions to be thrown

See also

• call_static_method()
• Program::callStaticMethodArgs()

Since

Qore 0.9.5

◆ callStaticMethodArgs()

Calls a static method of an object, passing the arguments to the function as arguments to the method.

Example:

auto result = p.callStaticMethodArgs("Namespace::Class::method", (arg1, arg2));

Parameters

Returns

the value returned by the method call

Exceptions

Note

the method called could cause additional exceptions to be thrown

See also

• call_static_method_args()
• Program::callStaticMethod()

Since

Qore 0.9.5

◆ constructor()

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

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. Additionally in this case module-specific- program data is not imported into the child Program object.

ProgramControl provides internal Program data for debugging purposes.

Use the ProgramControl::getProgram() method to attach to the currently running program

Restrictions:

Qore::PO_NO_EMBEDDED_LOGIC

Parameters

Example:

Exceptions

◆ copy()

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

Exceptions

◆ define()

Sets a parse define for the current Program.

Parameters

Example:

pgm.define("PRODUCTION", True);

◆ disableParseOptions()

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

An OPTIONS-LOCKED exception is thrown if parse options have been locked (for example with Program::lockOptions())

Parameters

Example:

pgm.disableParseOptions(PO_NO_THREADS | PO_NO_GUI);

Exceptions

See also

Program::setParseOptions() for a reciprocal method that enables parse options; also see Program::replaceParseOptions()

◆ existsFunction()

Checks if a user function exists in the program object.

Code Flags:

RET_VALUE_ONLY

Parameters

Returns

True if the function exists, False if not

Example:

if (pgm.existsFunction("my_func"))

printf("my_func() exists in the Program\n");

Exceptions

◆ findFunctionVariants()

finds all variants of a function or class method and returns a list of the results

Parameters

Returns

a list of hashes for each resolved name; when matched, each hash element has the following keys:

• desc: a string description of the call which includes the name and the full text call signature
• params: a QoreListNode object that gives the params in a format that can be used by ProgramControl::findFunctionStatementId

Exceptions

Since

Qore 0.8.13

Note

the reflection module supercedes this functionality

◆ getAllDefines()

Retrieves all parse defines in the current Program.

Returns

the hash of values of all parse defines in the current Program

Code Flags:

CONSTANT

Example:

*hash val = pgm.getAllDefines();

Note

A parse define may be defined with no value then values may have nothing values

Since

Qore 0.8.13

◆ getCallReference()

resolve the string as a call reference in the given Program

Code Flags:

RET_VALUE_ONLY

Parameters

Returns

the call reference to the given function or static method; the string is resolved as follows:

• if in a class method, a non-static method lookup is made
• if not found, then a static method lookup is made
• if not found, then a function lookup is made
• if not found, an CALL-REFERENCE-ERROR exception is thrown

Exceptions

Note

• use ::getCallReference() to get call references to non-public class methods; this builtin function will always run without any class context, however pseudo-methods run with the class context of the caller, which enables it to access any accessible private method
• call references to non-static methods contain a weak reference to the object; the lifetime of the object is not extended by the call reference

See also

• Qore::get_call_reference()
• ::getCallReference()

Since

Qore 0.9.4

◆ getDefine()

◆ getExpression()

returns an expression object for the given source code

Parameters

Since

Qore 0.9.5

◆ getFeatureList()

Returns a list of strings of the builtin and module-supplied features of Qore.

Code Flags:

RET_VALUE_ONLY

Returns

a list of strings of the builtin and module-supplied features of Qore

Since

Qore 1.0

◆ getGlobalVariable()

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

Parameters

Returns

the value of the global variable identified by the first string argument giving the name of the variable (without any leading "$" symbol)

Example:

bool existsv;

auto val = pgm.getGlobalVariable("error_count", \existsv);

◆ getGlobalVars()

returns a hash of global variables

Code Flags:

CONSTANT

Example:

hash h = pgm.getGlobalVars();

Returns

a hash of global variables and their values

See also

Qore::get_global_vars()

Since

Qore 0.8.13

◆ getParseOptions()

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

Returns

the current binary-or'ed parse option mask for the Program object

Code Flags:

CONSTANT

Example:

int mask = pgm.getParseOptions();

◆ getParseOptionStringList()

returns a list of parse option strings for the program object

Code Flags:

CONSTANT

Example:

list l = pgm.getParseOptionStringList();

Returns

a list of parse option strings for the program object

Since

Qore 0.9

◆ getProgram()

◆ getProgramId()

◆ getScriptDir()

Returns the current script directory as a string or NOTHING if not set.

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.

Returns

Returns the current script directory as a string or NOTHING if not set; if a string is returned, it should normally include the trailing directory separator character ("/" on UNIX, "\\" on Windows)

Code Flags:

CONSTANT

Example:

*string dir = pgm.getScriptDir();

◆ getScriptName()

Returns the current script name as a string or NOTHING if not set.

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_name() function if called from within the Program.

Returns

the current script name as a string or NOTHING if not set

Code Flags:

CONSTANT

Example:

*string name = pgm.getScriptName();

◆ getScriptPath()

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

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.

Returns

the current script directory and filename if known, otherwise returns NOTHING

Code Flags:

CONSTANT

Example:

*string path = pgm.getScriptPath();

◆ getThreadList()

returns a list of thread IDs active in this Program

Code Flags:

CONSTANT

Example:

list l = pgm.getThreadList();

Returns

a list of thread IDs active in this Program

Since

Qore 0.8.13

◆ getTimeZone()

Returns the default local time zone for the object.

Returns

the default local time zone for the object

Code Flags:

CONSTANT

Example:

TimeZone tz = pgm.getTimeZone();

◆ getUserFunctionList()

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

Returns

a list of strings of all user functions defined in the program object

Code Flags:

CONSTANT

Example:

list l = pgm.getUserFunctionList();

Note

the reflection module supercedes this functionality

◆ importClass()

Imports a class into the program object's space; any calls to the imported class's code will run with the parent Program object's permissions.

This allows a user-defined API with greater capabilities than the embedded Program object to be imported into the embedded code.

Parameters

Example:

pgm.importClass("MyNamespace::MyClass");

Exceptions

Since

• This method was first implemented in Qore 0.8.7
• Qore 0.8.12 added the new_name and inject parameters
• Qore 0.9,3 added the module_visibility parameter

◆ importFunction() [1/2]

Imports a function into the program object's space; any calls to the imported function will run with the parent Program object's permissions.

This allows a user-defined API with greater capabilities than the embedded Program object to be imported into the embedded code.

Parameters

Example:

pgm.importFunction("log");

Exceptions

Since

Qore 0.8.4 the function name can include a namespace path (ex "Namespace::func")

◆ importFunction() [2/2]

Imports a function into the program object's space and gives it a new name; any calls to the imported function will run with the parent Program object's permissions.

This allows a user-defined API with greater capabilities than the embedded Program object to be imported into the embedded code.

Parameters

Example:

pgm.importFunction("service_log", "log");

Exceptions

Since

• Qore 0.8.4 the function name can include a namespace path (ex "Namespace::func")
• Qore 0.8.12 added the inject parameter

◆ importGlobalVariable()

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

Parameters

Example:

pgm.importGlobalVariable("var");

Exceptions

◆ importHashDecl()

Imports a typed hash declaration into the program object's space.

This allows a user-defined API with greater capabilities than the embedded Program object to be imported into the embedded code.

Parameters

Example:

pgm.importHashDecl("MyNamespace::MyHash");

Exceptions

Since

Qore 0.8.13

◆ importSystemApi()

◆ importSystemClasses()

imports system classes into a Program container at runtime; will throw an exception if the Program was not created with Qore::PO_NO_INHERIT_SYSTEM_CLASSES

Example:

pgm.importSystemClasses();

Exceptions

Note

removes Qore::PO_NO_INHERIT_SYSTEM_CLASSES from the parse option mask after a successful completion

Since

Qore 0.8.12

◆ importSystemConstants()

imports system constants into a Program container at runtime; will throw an exception if the Program was not created with Qore::PO_NO_INHERIT_SYSTEM_CONSTANTS

Example:

pgm.importSystemConstants();

Exceptions

Note

removes Qore::PO_NO_INHERIT_SYSTEM_CONSTANTS from the parse option mask after a successful completion

Since

Qore 0.8.12

◆ importSystemFunctions()

imports system functions into a Program container at runtime; will throw an exception if the Program was not created with Qore::PO_NO_INHERIT_SYSTEM_FUNC_VARIANTS

Example:

pgm.importSystemFunctions();

Exceptions

Note

removes Qore::PO_NO_INHERIT_SYSTEM_FUNC_VARIANTS from the parse option mask after a successful completion

Since

Qore 0.8.12

◆ importSystemHashDecls()

imports system hashdecls into a Program container at runtime; will throw an exception if the Program was not created with Qore::PO_NO_INHERIT_SYSTEM_HASHDECLS

Example:

pgm.importSystemHashDecls();

Exceptions

Note

removes Qore::PO_NO_INHERIT_SYSTEM_HASHDECLS from the parse option mask after a successful completion

Since

Qore 0.8.13

◆ isDefined()

Returns True if the given parse define is defined in the current Program (does not have to have a value defined to return True), False if not.

Code Flags:

RET_VALUE_ONLY

Parameters

Returns

True if the given parse define is defined in the current Program (does not have to have a value defined to return True), False if not

Example:

bool b = pgm.isDefined("PRODUCTION");

Exceptions

◆ issueModuleCmd()

issues a module command for the given module; the module is loaded into the current Program object if it is not already present

Example:

pgm.issueModuleCmd("jni", "define-class " + java_class_path_name + " " + byte_code.toBase64());

Parameters

Exceptions

Note

command errors can result in other module- and command-specific exceptions being thrown; see documentation for the module and command in question for more details

Since

Qore 0.9

◆ loadApplyToPrivateUserModule()

◆ loadApplyToPrivateUserModuleWarn()

◆ loadApplyToUserModule()

◆ loadApplyToUserModuleWarn()

◆ loadModule()

◆ loadModuleWarn()

◆ loadUserModuleWithProgram()

Loads a Qore user module into the Program object at run-time using the given Program object as the container for the user module code.

This method allows a user module to be loaded with a custom API already present in the user module's Program container. If a feature with the same name already exists, then this feature's code is imported into the current Program object if necessary and no further action is taken.

Note that modules providing objects resolved at parse time (classes, constants, functions, etc) must be loaded prior to parsing.

Restrictions:

Qore::PO_NO_MODULES, MUST HAVE: Qore::PO_ALLOW_INJECTION

Example:

pgm.loadUserModuleWithProgram("MyModule", p);

Parameters

Exceptions

See also

• Program::loadApplyToPrivateUserModule()
• Program::loadApplyToPrivateUserModuleWarn()
• Program::loadApplyToUserModule()
• Program::loadApplyToUserModuleWarn()
• Program::loadModule()
• Program::loadModuleWarn()
• Program::loadUserModuleWithProgramWarn()
• get_module_hash()
• get_feature_list()

Since

• Qore 0.8.12 introduced this method
• Qore 0.9 added the warning_mask parameter

◆ loadUserModuleWithProgramWarn()

Loads a Qore user module into the Program object at run-time using the given Program object as the container for the user module code.

This method allows a user module to be loaded with a custom API already present in the user module's Program container. If a feature with the same name already exists, then this feature's code is imported into the current Program object if necessary and no further action is taken.

Note that modules providing objects resolved at parse time (classes, constants, functions, etc) must be loaded prior to parsing.

Restrictions:

Qore::PO_NO_MODULES, MUST HAVE: Qore::PO_ALLOW_INJECTION

Example:

pgm.loadUserModuleWithProgram("MyModule", p);

Parameters

Returns

any warnings found while parsing the module (if the module is a user module)

Exceptions

See also

• Program::loadApplyToPrivateUserModule()
• Program::loadApplyToPrivateUserModuleWarn()
• Program::loadApplyToUserModule()
• Program::loadApplyToUserModuleWarn()
• Program::loadModule()
• Program::loadModuleWarn()
• Program::loadUserModuleWithProgram()
• get_module_hash()
• get_feature_list()

Since

Qore 0.9 introduced this method

◆ lockOptions()

Locks parse options so that they cannot be changed.

Example:

◆ parse()

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

This method causes both stages of parsing to be executed; if this method is successful, then the code parsed is committed to the Program object. This method is equivalent to calling Program::parsePending() and Program::parseCommit() in one atomic call.

If an exception occurs in this method, all pending code is backed out, not just code parsed by this method (for example, in case uncommitted code added by Program::parsePending() also exists in the Program object before calling this method).

Restrictions:

Qore::PO_NO_EMBEDDED_LOGIC

Parameters

Returns

if warnings included in the warning mask are raised during parsing, this method will return an ExceptionInfo hash with warning information, otherwise NOTHING is returned

Example:

*hash wh = pgm.parse(code, "label", WARN_DEFAULT);

while (wh) {

printf("warning: %s:%d: %s: %s\n", wh.file, wh.line, wh.err, wh.desc);

wh = wh.next;

}

Note

This method could throw many parse exceptions which are not enumerated here; any parse errors will result in an appropriate exception.

See also

• Qore::Program::parsePending()
• Qore::Program::parseCommit()
• Qore::parse()

Exceptions

Note

A complete parse action (Program::parse() or Program::parseCommit()) can only be performed once; subsequent attempts to parse code into the same Program object will fail with an exception. If parsing fails due to a parse exception, the Program object is generally no longer usable and must be recreated to be used.

Since

• Qore 0.8.7 the source, offset, and format_label arguments were added
• Qore 0.9 parsing can only be executed once per Program object
• Qore 0.9 the format_label is obsolete / ignored

◆ parseCommit() [1/2]

Commits and pending code processed with Program::parsePending() to the Program object after resolving all outstanding references in the pending code.

An exception in this method causes all pending code to be rolled back immediately.

Example:

Note

This method could throw many parse exceptions related to resolving references which are not enumerated here; any parse errors will result in an appropriate exception.

See also

• Qore::Program::parse()
• Qore::Program::parsePending()
• Qore::Program::parseRollback()
• Qore::parse()

Exceptions

Note

A complete parse action (Program::parse() or Program::parseCommit()) can only be performed once; subsequent attempts to parse code into the same Program object will fail with an exception. If parsing fails due to a parse exception, the Program object is generally no longer usable and must be recreated to be used.

Since

Qore 0.9 parsing can only be executed once per Program object

◆ parseCommit() [2/2]

Commits and pending code processed with Program::parsePending() to the Program object after resolving all outstanding references in the pending code.

An exception in this method causes all pending code to be rolled back immediately.

Example:

*hash wh = pgm.parseCommit(WARN_DEFAULT);

while (exists wh) {

printf("warning: %s:%d: %s: %s\n", wh.file, wh.line, wh.err, wh.desc);

wh = wh.next;

}

Note

This method could throw many parse exceptions related to resolving references which are not enumerated here; any parse errors will result in an appropriate exception.

See also

• Qore::Program::parse()
• Qore::Program::parsePending()
• Qore::Program::parseRollback()
• Qore::parse()

Exceptions

Note

A complete parse action (Program::parse() or Program::parseCommit()) can only be performed once; subsequent attempts to parse code into the same Program object will fail with an exception. If parsing fails due to a parse exception, the Program object is generally no longer usable and must be recreated to be used.

Since

Qore 0.9 parsing can only be executed once per Program object

◆ parsePending()

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.

Program::parseCommit() must be called to resolve all references and commit the code to the Program object; until Program::parseCommit() is called, none of the code parsed by this method will be available for execution in the Program object.

If an exception occurs in this method, all pending code is backed out, not just code parsed by this method.

Restrictions:

Qore::PO_NO_EMBEDDED_LOGIC

Parameters

Returns

if warnings included in the warning mask are raised during parsing, this method will return an ExceptionInfo hash with warning information, otherwise NOTHING is returned

Example:

*hash wh = pgm.parsePending(code, "label", WARN_DEFAULT);

while (wh) {

printf("warning: %s:%d: %s: %s\n", wh.file, wh.line, wh.err, wh.desc);

wh = wh.next;

}

pgm.parseCommit();

Note

This method could throw many parse exceptions which are not enumerated here; any parse errors will result in an appropriate exception.

See also

• Qore::Program::parse()
• Qore::Program::parseCommit()
• Qore::Program::parseRollback()
• Qore::parse()

Exceptions

Note

A complete parse action (Program::parse() or Program::parseCommit()) can only be performed once; subsequent attempts to parse code into the same Program object will fail with an exception. If parsing fails due to a parse exception, the Program object is generally no longer usable and must be recreated to be used.

Since

• Qore 0.8.7 the source, offset, and format_label arguments were added
• Qore 0.9 parsing can only be executed once per Program object
• Qore 0.9 the format_label is obsolete / ignored

◆ parseRollback()

◆ replaceParseOptions()

◆ run()

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

Returns

the value given to the return statement at the top-level, if any, otherwise NOTHING

Example:

◆ setGlobalVarValue()

set the value of a global variable

Example:

pgm.setGlobalVarValue("a", 1);

Parameters

Exceptions

Note

other exceptions could be thrown if the value cannot be assigned to the given variable

See also

Qore::set_global_var_value()

Since

Qore 0.8.13

◆ setParseOptions()

Sets parse options in the parse option mask for the Program object.

An OPTIONS-LOCKED exception is thrown if parse options have been locked (for example with Program::lockOptions())

Parameters

Example:

pgm.setParseOptions(PO_NO_THREADS | PO_NO_GUI);

Exceptions

See also

Program::disableParseOptions() for a reciprocal method that disables parse options; also see Program::replaceParseOptions()

◆ setScriptPath()

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

Parameters

Example:

pgm.setScriptPath("/users/test/test.q");

◆ setThreadInit()

◆ setTimeZone()

Sets the default local time zone for the object.

Example:

TimeZone tz("Europe/Prague");

pgm.setTimeZone(tz);

See also

TimeZone::set()

◆ setTimeZoneRegion()

Sets the default local time zone for the object from a path to a zoneinfo time zone region file.

If there are errors opening, reading, or parsing the file (or the Windows registry entry, depending on the platform), an exception is thrown

Parameters

Example:

pgm.setTimeZoneRegion("Europe/Prague");

Exceptions

◆ setTimeZoneUTCOffset()

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

Parameters

Example:

The following examples are all equivalent, setting the time zone to +02 UTC:

pgm.setTimeZoneUTCOffset(7200);

pgm.setTimeZoneUTCOffset(2h);

pgm.setTimeZoneUTCOffset(PT2H);

See also

TimeZone::setUTCOffset()

◆ undefine()

Unsets a parse define for the current Program.

Parameters

Example:

pgm.undefine("PRODUCTION");