Loading...
Searching...
No Matches
Qore::Program Class Reference

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>`

## Public Member Functions

auto | callFunction (string name,...)
| Calls a function in the program object and returns the return value.
auto | callFunctionArgs (string name, *softlist< auto > vargs)
| Calls a function in the program object giving the arguments to the function as a list and returns the return value.
auto | callStaticMethod (string class_name, string method,...)
| Calls a static method of an object, passing the arguments to the function as arguments to the method.
auto | callStaticMethodArgs (string class_name, string method, *softlist< auto > call_args)
| Calls a static method of an object, passing the arguments to the function as arguments to the method.
| constructor (softint po=PO_DEFAULT)
| Creates the program object and optionally sets program capabilities (parse options)
| copy ()
| Throws an exception to prevent objects of this class from being copied.
nothing | define (string def, auto val)
| Sets a parse define for the current Program.
| destructor ()
| Waits for all threads to finish executing, then deletes all global variables, dereferences the internal Program object and deletes the Qore object.
nothing | disableParseOptions (softint opt)
| Removes the given parse options to the current parse option mask.
bool | existsFunction (string name)
| Checks if a user function exists in the program object.
list< hash< auto > > | findFunctionVariants (string function)
| finds all variants of a function or class method and returns a list of the results
*hash< auto > | getAllDefines ()
| Retrieves all parse defines in the current Program.
code | getCallReference (string identifier)
| resolve the string as a call reference in the given Program
auto | getDefine (string def)
| Retrieves the value of the given parse define in the current Program.
Expression | getExpression (string source, string label)
| returns an expression object for the given source code
list< string > | getFeatureList ()
| Returns a list of strings of the builtin and module-supplied features of Qore.
auto | getGlobalVariable (string varname, *reference< bool > rexists)
| Returns a the value of the global variable identified by the first string argument.
hash< auto > | getGlobalVars ()
| returns a hash of global variables
list< string > | getParseOptionStringList ()
| returns a list of parse option strings for the program object
int | getParseOptions ()
| Returns the current binary-or'ed parse option mask for the Program object.
ProgramControl | getProgram ()
| Get ProgramControl.
int | getProgramId ()
| Get program id.
*string | getScriptDir ()
| Returns the current script directory as a string or NOTHING if not set.
*string | getScriptName ()
| Returns the current script name as a string or NOTHING if not set.
*string | getScriptPath ()
| Returns the current script directory and filename if known, otherwise returns NOTHING.
list< int > | getThreadList ()
| returns a list of thread IDs active in this Program
TimeZone | getTimeZone ()
| Returns the default local time zone for the object.
softlist< string > | getUserFunctionList ()
| Returns a list of strings of all user functions defined in the program object.
nothing | importClass (string cls, *string new_name, *softbool inject, int module_visibility=CSP_UNCHANGED)
| 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.
nothing | importFunction (string func)
| Imports a function into the program object's space; any calls to the imported function will run with the parent Program object's permissions.
nothing | importFunction (string func, string new_name, *softbool inject)
| 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.
nothing | importGlobalVariable (string varname, bool readonly=False)
| Imports a global variable into the program object's space.
nothing | importHashDecl (string name, *string new_name)
| Imports a typed hash declaration into the program object's space.
| importSystemApi ()
| imports system classes and 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, Qore::PO_NO_INHERIT_SYSTEM_HASHDECLS, Qore::PO_NO_INHERIT_SYSTEM_CONSTANTS, and Qore::PO_NO_INHERIT_SYSTEM_CLASSES
| 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
| 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
| 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
| 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
bool | isDefined (string def)
| 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.
nothing | issueModuleCmd (string module, string cmd)
| issues a module command for the given module; the module is loaded into the current Program object if it is not already present
| loadApplyToPrivateUserModule (string name, int warning_mask=WARN_MODULES)
| Loads a Qore user module privately into the given Program container at run-time; after this call the Program object is owned by the user module and is no longer accessible in the object used for the call.
*hash< ExceptionInfo > | loadApplyToPrivateUserModuleWarn (string name, int warning_mask=WARN_MODULES)
| Loads a Qore user module privately into the given Program container at run-time; after this call the Program object is owned by the user module and is no longer accessible in the object used for the call.
| loadApplyToUserModule (string name, *softbool reinject, int warning_mask=WARN_MODULES, bool reexport=False)
| Loads a Qore user module into the given Program container at run-time; after this call the Program object is owned by the user module and is no longer accessible in the object used for the call.
*hash< ExceptionInfo > | loadApplyToUserModuleWarn (string name, *softbool reinject, int warning_mask=WARN_MODULES, bool reexport=False)
| Loads a Qore user module into the given Program container at run-time; after this call the Program object is owned by the user module and is no longer accessible in the object used for the call.
| loadModule (string name, int warning_mask=WARN_MODULES)
| Loads a Qore module into the Program object at run-time.
*hash< ExceptionInfo > | loadModuleWarn (string name, int warning_mask=WARN_MODULES)
| Loads a Qore module into the Program object at run-time.
| loadUserModuleWithProgram (string name, Qore::Program pgm, int warning_mask=WARN_MODULES)
| 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.
*hash< ExceptionInfo > | loadUserModuleWithProgramWarn (string name, Qore::Program pgm, int warning_mask=WARN_MODULES)
| 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.
nothing | lockOptions ()
| Locks parse options so that they cannot be changed.
*hash< ExceptionInfo > | parse (string code, string label, *softint warning_mask, *string source, *softint offset, softbool format_label=True)
| Parses the string argument and adds the code to the Program object.
nothing | parseCommit ()
| Commits and pending code processed with Program::parsePending() to the Program object after resolving all outstanding references in the pending code.
*hash< ExceptionInfo > | parseCommit (int warning_mask)
| Commits and pending code processed with Program::parsePending() to the Program object after resolving all outstanding references in the pending code.
*hash< ExceptionInfo > | parsePending (string code, string label, *softint warning_mask, *string source, *softint offset, softbool format_label=True)
| Parses the text passed to pending lists in the Program object; does not resolve all references or commit the code to the Program object.
nothing | parseRollback ()
| Removes all partially or fully-parsed code from the object along with other builtin objects; a Program object is not usable after calling this method; do not use this method but instead destroy the Program object.
nothing | replaceParseOptions (softint opt)
| Replaces the parse options for the Program object.
auto | run ()
| Runs the program and optionally returns a value if the top-level code exits with a return statement.
nothing | setGlobalVarValue (string name, auto value)
| set the value of a global variable
nothing | setParseOptions (softint opt=PO_DEFAULT)
| Sets parse options in the parse option mask for the Program object.
nothing | setScriptPath (*string path)
| Sets (or clears) the script path (directory and filename) for the object.
bool | setThreadInit (*code init)
| Sets a call reference or closure to run every time a new thread is started.
nothing | setTimeZone (TimeZone zone)
| Sets the default local time zone for the object.
nothing | setTimeZoneRegion (string region)
| Sets the default local time zone for the object from a path to a zoneinfo time zone region file.
nothing | setTimeZoneUTCOffset (softint seconds_east)
| 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.
nothing | undefine (string def)
| Unsets a parse define for the current Program.

## Detailed Description

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.

## Member Function Documentation

## callFunction()

auto Qore::Program::callFunction | ( | string | name,
|  |  | ...
| ) |  |

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

  name | The name of the function to call
  ... | The remaining arguments passed to the method are passed to the function to be called

Returns
  Depends on the function being called

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

Exceptions

  INVALID-FUNCTION-ACCESS | Parse options do not allow this builtin function to be called
  NO-FUNCTION | The function does not exist
  ENCODING-CONVERSION-ERROR | the function name could not be converted to the default character encoding

Note
  The function called could also cause other exceptions to be thrown

## callFunctionArgs()

auto Qore::Program::callFunctionArgs | ( | string | name,
|  | *softlist< auto > | vargs
| ) |  |

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

  name | The name of the function to call
  vargs | The arguments to the function to be called

Returns
  Depends on the function being called

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

Exceptions

  INVALID-FUNCTION-ACCESS | Parse options do not allow this builtin function to be called
  NO-FUNCTION | The function does not exist
  ENCODING-CONVERSION-ERROR | the function name could not be converted to the default character encoding

Note
  The function called could also cause other exceptions to be thrown

## callStaticMethod()

auto Qore::Program::callStaticMethod | ( | string | class_name,
|  | string | method,
|  |  | ...
| ) |  |

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

  class_name | the with an optional namespace prefix
  method | the static method to call
  ... | any additional arguments to the method

Returns
  the value returned by the method call

Exceptions

  METHOD-DOES-NOT-EXIST | The named method does not exist in this class
  ILLEGAL-EXPLICIT-METHOD-CALL | The named method may not be called explicitly
  METHOD-IS-PRIVATE | The named method is private and therefore can only be called within the class
  BASE-CLASS-IS-PRIVATE | The named method is a member of a privately inherited base class

Note
  the method called could cause additional exceptions to be thrown

See also
  - call_static_method()
  - Program::callStaticMethodArgs()

Since
  Qore 0.9.5

## callStaticMethodArgs()

auto Qore::Program::callStaticMethodArgs | ( | string | class_name,
|  | string | method,
|  | *softlist< auto > | call_args
| ) |  |

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

  class_name | the with an optional namespace prefix
  method | the static method to call
  call_args | any additional arguments to the method

Returns
  the value returned by the method call

Exceptions

  METHOD-DOES-NOT-EXIST | The named method does not exist in this class
  ILLEGAL-EXPLICIT-METHOD-CALL | The named method may not be called explicitly
  METHOD-IS-PRIVATE | The named method is private and therefore can only be called within the class
  BASE-CLASS-IS-PRIVATE | The named method is a member of a privately inherited base class

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()

Qore::Program::constructor | ( | softint | po = `PO_DEFAULT` | ) |

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

  po | A binary OR'ed product of parse options

Example:
  Program pgm();

Exceptions

  PROGRAM-OPTION-ERROR | invalid parse options used

## copy()

Qore::Program::copy | ( |  | ) |

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

Exceptions

  PROGRAM-COPY-ERROR | copying Program objects is currently unsupported

## define()

nothing Qore::Program::define | ( | string | def,
|  | auto | val
| ) |  |

Sets a parse define for the current Program.

Parameters

  def | The parse define to assign
  val | The value to assign to the define

Example:
  pgm.define("PRODUCTION", True);

## disableParseOptions()

nothing Qore::Program::disableParseOptions | ( | softint | opt | ) |

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

  opt | A single parse option or binary-or'ed combination of parse options to unset in the parse option mask for the object; any bit set in this argument will be unset (ie zeroed out or combined with inverse binary and) in the Program's parse option mask

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

Exceptions

  OPTIONS-LOCKED | Parse options have been locked and cannot be changed
  PROGRAM-OPTION-ERROR | invalid parse options used

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

## existsFunction()

bool Qore::Program::existsFunction | ( | string | name | ) |

Checks if a user function exists in the program object.

Code Flags:
  RET_VALUE_ONLY

Parameters

  name | The name of the function to check

Returns
  True if the function exists, False if not

Example:
  if (pgm.existsFunction("my_func"))
  printf("my_func() exists in the Program\n");

Exceptions

  ENCODING-CONVERSION-ERROR | the function name could not be converted to the default character encoding

## findFunctionVariants()

list< hash< auto > > Qore::Program::findFunctionVariants | ( | string | function | ) |

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

Parameters

  function | the function or class method name; may also be namespace-justified

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

  PROGRAM-ERROR | thrown if the function cannot be found

Since
  Qore 0.8.13

Note
  the reflection module supercedes this functionality

## getAllDefines()

*hash< auto > Qore::Program::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<auto> 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()

code Qore::Program::getCallReference | ( | string | identifier | ) |

resolve the string as a call reference in the given Program

Code Flags:
  RET_VALUE_ONLY

Parameters

  identifier | the string to resolve; function or static class method, can include namespace path

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

  CALL-REFERENCE-ERROR | cannot resolve call reference; method not accessible in the calling context

Note
  - use <object>::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()
  - <object>::getCallReference()

Since
  Qore 0.9.4

## getDefine()

auto Qore::Program::getDefine | ( | string | def | ) |

Retrieves the value of the given parse define in the current Program.

Returns
  the value of the given parse define in the current Program

Code Flags:
  RET_VALUE_ONLY

Example:
  auto val = pgm.getDefine("PRODUCTION");

Exceptions

  ENCODING-CONVERSION-ERROR | this error is thrown if the string cannot be converted to the default character encoding

Note
  A parse define may be defined with no value; use Program::isDefined() to check if a parse define is actually defined or not

## getExpression()

Expression Qore::Program::getExpression | ( | string | source,
|  | string | label
| ) |  |

returns an expression object for the given source code

Parameters

  source | The source to the expression
  label | the label for the expression

Since
  Qore 0.9.5

## getFeatureList()

list< string > Qore::Program::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()

auto Qore::Program::getGlobalVariable | ( | string | varname,
|  | *reference< bool > | rexists
| ) |  |

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

Parameters

  varname | The string name of the global variable to find, not including the leading `"$"` character
  rexists | An lvalue reference to a bool to determine if the global variable exists (because this method could return NOTHING when the variable exists as well as when it does not)

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()

hash< auto > Qore::Program::getGlobalVars | ( |  | ) |

returns a hash of global variables

Code Flags:
  CONSTANT

Example:
  hash<auto> h = pgm.getGlobalVars();

Returns
  a hash of global variables and their values

See also
  Qore::get_global_vars()

Since
  Qore 0.8.13

## getParseOptions()

int Qore::Program::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()

list< string > Qore::Program::getParseOptionStringList | ( |  | ) |

returns a list of parse option strings for the program object

Code Flags:
  CONSTANT

Example:
  list<string> l = pgm.getParseOptionStringList();

Returns
  a list of parse option strings for the program object

Since
  Qore 0.9

## getProgram()

ProgramControl Qore::Program::getProgram | ( |  | ) |

Get ProgramControl.

Restrictions:
  MUST HAVE: Qore::PO_ALLOW_DEBUGGER

Code Flags:
  RET_VALUE_ONLY

## getProgramId()

int Qore::Program::getProgramId | ( |  | ) |

Get program id.

Code Flags:
  CONSTANT

See also
  Program::getProgramId

Since
  Qore 0.8.13

## getScriptDir()

*string Qore::Program::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()

*string Qore::Program::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()

*string Qore::Program::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()

list< int > Qore::Program::getThreadList | ( |  | ) |

returns a list of thread IDs active in this Program

Code Flags:
  CONSTANT

Example:
  list<int> l = pgm.getThreadList();

Returns
  a list of thread IDs active in this Program

Since
  Qore 0.8.13

## getTimeZone()

TimeZone Qore::Program::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()

softlist< string > Qore::Program::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<string> l = pgm.getUserFunctionList();

Note
  the reflection module supercedes this functionality

## importClass()

nothing Qore::Program::importClass | ( | string | cls,
|  | *string | new_name,
|  | *softbool | inject,
|  | int | module_visibility = `CSP_UNCHANGED`
| ) |  |

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

  cls | the name of the class to import into the Program object
  new_name | the name of the class in the imported Program object; can be a fully-qualified namespace path, in which case the namespace path will be created in the target Program object if necessary as well (ex: `"Ns1::Ns2::MyClass"`)

  inject

  if True then the imported class will be marked as a dependency injection and therefore will not be overritten by subsequent calls to Program::importSystemClasses(), Program::importSystemHashDecls(), Program::importSystemConstants(), Program::importSystemApi(), Program::loadApplyToPrivateUserModule(), or Program::loadApplyToUserModule(); note that for this call to succeed, the Program must have Qore::PO_ALLOW_INJECTION set

  module_visibility | see Import Visibility Constants for valid values

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

Exceptions

  CLASS-IMPORT-ERROR | Cannot import a class into the same Program object; class or namespace with this name already exists or the source class does not exist; injection indicated but Qore::PO_ALLOW_INJECTION not set
  ENCODING-CONVERSION-ERROR | the class name could not be converted to the default character encoding

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]

nothing Qore::Program::importFunction | ( | string | func | ) |

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

  func | the name of the function to import into the Program object

Example:
  pgm.importFunction("log");

Exceptions

  FUNCTION-IMPORT-ERROR | Cannot import a function into the same Program object; function with this name already exists
  PROGRAM-IMPORTFUNCTION-NO-FUNCTION | The function does not exist
  ENCODING-CONVERSION-ERROR | the function name could not be converted to the default character encoding

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

## importFunction() [2/2]

nothing Qore::Program::importFunction | ( | string | func,
|  | string | new_name,
|  | *softbool | inject
| ) |  |

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

  func | the name of the function to import into the Program object
  new_name | the name of the function as it will be known in the Program object once imported; can be a fully- qualified namespace path, in which case the namespace path will be created in the target Program object if necessary as well (ex: `"Ns1::Ns2::my_func"`)
  inject | if True then the imported function will be marked as a dependency injection and therefore will not be overritten by subsequent calls to Program::importSystemFunctions(), Program::importSystemApi(), Program::loadApplyToPrivateUserModule(), or Program::loadApplyToUserModule(); note that for this call to succeed, the Program must have Qore::PO_ALLOW_INJECTION set

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

Exceptions

  FUNCTION-IMPORT-ERROR | Cannot import a function into the same Program object; function with this name already exists; target namespace does not exist; injection indicated but Qore::PO_ALLOW_INJECTION not set
  PROGRAM-IMPORTFUNCTION-NO-FUNCTION | The function does not exist
  ENCODING-CONVERSION-ERROR | the function name could not be converted to the default character encoding

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()

nothing Qore::Program::importGlobalVariable | ( | string | varname,
|  | bool | readonly = `False`
| ) |  |

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

  varname | The name of the global variable without the `"$"`
  readonly | If this argument is True, then the variable will be imported read-only, and cannot be changed by the subprogram (note that if the imported

Example:
  pgm.importGlobalVariable("var");

Exceptions

  PROGRAM-IMPORTGLOBALVARIABLE-EXCEPTION | The global variable does not exist in the source program, or the target variable already exists
  ENCODING-CONVERSION-ERROR | the global variablt name could not be converted to the default character encoding

## importHashDecl()

nothing Qore::Program::importHashDecl | ( | string | name,
|  | *string | new_name
| ) |  |

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

  name | the name of the typed hash declaration to import into the Program object
  new_name | the name of the typed hash declaration in the imported Program object; can be a fully-qualified namespace path, in which case the namespace path will be created in the target Program object if necessary as well (ex: `"Ns1::Ns2::MyClass"`)

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

Exceptions

  HASHDECL-IMPORT-ERROR | Cannot import a hashdecl into the same Program object; conflict with an existing definition
  ENCODING-CONVERSION-ERROR | the hashdecl name could not be converted to the default character encoding

Since
  Qore 0.8.13

## importSystemApi()

Qore::Program::importSystemApi | ( |  | ) |

imports system classes and 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, Qore::PO_NO_INHERIT_SYSTEM_HASHDECLS, Qore::PO_NO_INHERIT_SYSTEM_CONSTANTS, and Qore::PO_NO_INHERIT_SYSTEM_CLASSES

Example:
  pgm.importSystemApi();

Exceptions

  IMPORT-SYSTEM-API-ERROR | objects already imported; parse options are locked on the Program object; conflicting object found; system API incorrectly imported; in case this exception is raised, the Program object will not contain the full system API and is most likely unusable

Note
  removes Qore::PO_NO_INHERIT_SYSTEM_CLASSES, Qore::PO_NO_INHERIT_SYSTEM_HASHDECLS, Qore::PO_NO_INHERIT_SYSTEM_CONSTANTS, and Qore::PO_NO_INHERIT_SYSTEM_FUNC_VARIANTS from the parse option mask after a successful completion

Since
  Qore 0.8.12

## importSystemClasses()

Qore::Program::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

  IMPORT-SYSTEM-API-ERROR | objects already imported; parse options are locked on the Program object; conflicting object found; system API incorrectly imported; in case this exception is raised, the Program object will not contain the full system API and is most likely unusable

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

Since
  Qore 0.8.12

## importSystemConstants()

Qore::Program::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

  IMPORT-SYSTEM-API-ERROR | objects already imported; parse options are locked on the Program object; conflicting object found; system API incorrectly imported; in case this exception is raised, the Program object will not contain the full system API and is most likely unusable

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

Since
  Qore 0.8.12

## importSystemFunctions()

Qore::Program::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

  IMPORT-SYSTEM-API-ERROR | objects already imported; parse options are locked on the Program object; conflicting object found; system API incorrectly imported; in case this exception is raised, the Program object will not contain the full system API and is most likely unusable

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

Since
  Qore 0.8.12

## importSystemHashDecls()

Qore::Program::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

  IMPORT-SYSTEM-API-ERROR | objects already imported; parse options are locked on the Program object; conflicting object found; system API incorrectly imported; in case this exception is raised, the Program object will not contain the full system API and is most likely unusable

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

Since
  Qore 0.8.13

## isDefined()

bool Qore::Program::isDefined | ( | string | def | ) |

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

  def | The name of the define to check

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

  ENCODING-CONVERSION-ERROR | this error is thrown if the string cannot be converted to the default character encoding

## issueModuleCmd()

nothing Qore::Program::issueModuleCmd | ( | string | module,
|  | string | cmd
| ) |  |

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

  module | the module name
  cmd | the command string to execute to be parsed by the module

Exceptions

  PARSE-COMMAND-ERROR | the module does not support commands

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()

Qore::Program::loadApplyToPrivateUserModule | ( | string | name,
|  | int | warning_mask = `WARN_MODULES`
| ) |  |

Loads a Qore user module privately into the given Program container at run-time; after this call the Program object is owned by the user module and is no longer accessible in the object used for the call.

This method allows a user module to be privately loaded with a custom API already present in the user module's Program container.

Restrictions:
  Qore::PO_NO_MODULES

Parameters

  name | the name or path of the user module to load
  warning_mask | the warning mask to use when loading the module; note that warnings are treated as errors

Exceptions

  LOAD-MODULE-ERROR | module cannot be loaded: binary modules cannot be loaded in Program containers, etc

Note
  - after this call the Program object will be owned by the user module and will no longer be valid, so any accesses to the object after this call will result in an exception
  - this module will not be available for use in other Program objects; this method is useful for loading modules that register themselves with an injected API in code that does not have Qore::PO_ALLOW_INJECTION set or where the module's functionality should be protected from other Qore code

See also
  - Program::loadApplyToPrivateUserModuleWarn()
  - Program::loadApplyToUserModule()
  - Program::loadApplyToUserModuleWarn()
  - Program::loadModule()
  - Program::loadModuleWarn()
  - Program::loadUserModuleWithProgram()
  - Program::loadUserModuleWithProgramWarn()
  - get_module_hash()
  - get_feature_list()

Since
  Qore 0.9 added the `warning_mask` parameter

## loadApplyToPrivateUserModuleWarn()

*hash< ExceptionInfo > Qore::Program::loadApplyToPrivateUserModuleWarn | ( | string | name,
|  | int | warning_mask = `WARN_MODULES`
| ) |  |

Loads a Qore user module privately into the given Program container at run-time; after this call the Program object is owned by the user module and is no longer accessible in the object used for the call.

This method allows a user module to be privately loaded with a custom API already present in the user module's Program container.

Restrictions:
  Qore::PO_NO_MODULES

Parameters

  name | the name or path of the user module to load
  warning_mask | the warning mask to use when loading the module; any warnings will be returned in the return value

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

Exceptions

  LOAD-MODULE-ERROR | module cannot be loaded: binary modules cannot be loaded in Program containers, etc

Note
  - after this call the Program object will be owned by the user module and will no longer be valid, so any accesses to the object after this call will result in an exception
  - this module will not be available for use in other Program objects; this method is useful for loading modules that register themselves with an injected API in code that does not have Qore::PO_ALLOW_INJECTION set or where the module's functionality should be protected from other Qore code

See also
  - Program::loadApplyToPrivateUserModuleWarn()
  - Program::loadApplyToUserModule()
  - Program::loadApplyToUserModuleWarn()
  - Program::loadModule()
  - Program::loadModuleWarn()
  - Program::loadUserModuleWithProgram()
  - Program::loadUserModuleWithProgramWarn()
  - get_module_hash()
  - get_feature_list()

Since
  Qore 0.9 added the `warning_mask` parameter

## loadApplyToUserModule()

Qore::Program::loadApplyToUserModule | ( | string | name,
|  | *softbool | reinject,
|  | int | warning_mask = `WARN_MODULES`,
|  | bool | reexport = `False`
| ) |  |

Loads a Qore user module into the given Program container at run-time; after this call the Program object is owned by the user module and is no longer accessible in the object used for the call.

This method allows a user module to be loaded with a custom API already present in the user module's Program container.

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

Parameters

  name | the name or path of the user module to load
  reinject | if True then the module will be reloaded even if already loaded previously; if the module was not already loaded then it is loaded with this call
  warning_mask | the warning mask to use when loading the module; note that warnings are treated as errors
  reexport | reexport symbols from the imported module (only valid when used in a user module)

Exceptions

  LOAD-MODULE-ERROR | module cannot be loaded: binary modules cannot be loaded in Program containers, etc

Note
  - it is not an error to set the reinject argument to True when the given module has not already been loaded
  - after this call the Program object will be owned by the user module and will no longer be valid, so any accesses to the object after this call will result in an exception

See also
  - Program::loadApplyToPrivateUserModule()
  - Program::loadApplyToPrivateUserModuleWarn()
  - Program::loadApplyToUserModuleWarn()
  - Program::loadModule()
  - Program::loadModuleWarn()
  - Program::loadUserModuleWithProgram()
  - Program::loadUserModuleWithProgramWarn()
  - get_module_hash()
  - get_feature_list()

Since
  - Qore 0.9 added the `warning_mask` parameter
  - Qore 0.9.4 added the `reexport` parameter

## loadApplyToUserModuleWarn()

*hash< ExceptionInfo > Qore::Program::loadApplyToUserModuleWarn | ( | string | name,
|  | *softbool | reinject,
|  | int | warning_mask = `WARN_MODULES`,
|  | bool | reexport = `False`
| ) |  |

Loads a Qore user module into the given Program container at run-time; after this call the Program object is owned by the user module and is no longer accessible in the object used for the call.

This method allows a user module to be loaded with a custom API already present in the user module's Program container.

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

Parameters

  name | the name or path of the user module to load
  reinject | if True then the module will be reloaded even if already loaded previously; if the module was not already loaded then it is loaded with this call
  warning_mask | the warning mask to use when loading the module; any warnings will be returned in the return value
  reexport | reexport symbols from the imported module (only valid when used in a user module)

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

Exceptions

  LOAD-MODULE-ERROR | module cannot be loaded: binary modules cannot be loaded in Program containers, etc

Note
  - it is not an error to set the reinject argument to True when the given module has not already been loaded
  - after this call the Program object will be owned by the user module and will no longer be valid, so any accesses to the object after this call will result in an exception

See also
  - Program::loadApplyToPrivateUserModule()
  - Program::loadApplyToPrivateUserModuleWarn()
  - Program::loadApplyToUserModule()
  - Program::loadModule()
  - Program::loadModuleWarn()
  - Program::loadUserModuleWithProgram()
  - Program::loadUserModuleWithProgramWarn()
  - get_module_hash()
  - get_feature_list()

Since
  - Qore 0.9 added the `warning_mask` parameter
  - Qore 0.9.4 added the `reexport` parameter

## loadModule()

Qore::Program::loadModule | ( | string | name,
|  | int | warning_mask = `WARN_MODULES`
| ) |  |

Loads a Qore module into the Program object at run-time.

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

Parameters

  name | either a feature name (a module will be searched with this feature name) or a path to a module to load
  warning_mask | the warning mask to use when loading the module; note that warnings are treated as errors

Example:
  pgm.loadModule("mysql");

Exceptions

  LOAD-MODULE-ERROR | module cannot be loaded: API incompatibility, module defines symbols already defined in the target object, etc

See also
  - Program::loadApplyToPrivateUserModule()
  - Program::loadApplyToPrivateUserModuleWarn()
  - Program::loadApplyToUserModule()
  - Program::loadApplyToUserModuleWarn()
  - Program::loadModuleWarn()
  - Program::loadUserModuleWithProgram()
  - Program::loadUserModuleWithProgramWarn()
  - get_module_hash()
  - get_feature_list()

Since
  - Qore 0.8.7 introduced this method
  - Qore 0.9 added the `warning_mask` parameter

## loadModuleWarn()

*hash< ExceptionInfo > Qore::Program::loadModuleWarn | ( | string | name,
|  | int | warning_mask = `WARN_MODULES`
| ) |  |

Loads a Qore module into the Program object at run-time.

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

Parameters

  name | either a feature name (a module will be searched with this feature name) or a path to a module to load
  warning_mask | the warning mask to use when loading the module; any warnings will be returned in the return value

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

Example:
  pgm.loadModule("mysql");

Exceptions

  LOAD-MODULE-ERROR | module cannot be loaded: API incompatibility, module defines symbols already defined in the target object, etc

See also
  - Program::loadApplyToPrivateUserModule()
  - Program::loadApplyToPrivateUserModuleWarn()
  - Program::loadApplyToUserModule()
  - Program::loadApplyToUserModuleWarn()
  - Program::loadModule()
  - Program::loadUserModuleWithProgram()
  - Program::loadUserModuleWithProgramWarn()
  - get_module_hash()
  - get_feature_list()

Since
  Qore 0.9 introduced this method

## loadUserModuleWithProgram()

Qore::Program::loadUserModuleWithProgram | ( | string | name,
|  | Qore::Program | pgm,
|  | int | warning_mask = `WARN_MODULES`
| ) |  |

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

  name | the name or path of the user module to load
  pgm | the Program object to use as a container for the new user module, presumably this has a custom API that the user module can use; note that after this call the Program object will be owned by the user module, therefore the object itself will no longer be valid and any accesses to the object after this call will result in an exception
  warning_mask | the warning mask to use when loading the module; note that warnings are treated as errors

Exceptions

  LOAD-MODULE-ERROR | module cannot be loaded: binary modules cannot be loaded in Program containers, module defines symbols already defined in the target object, etc

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()

*hash< ExceptionInfo > Qore::Program::loadUserModuleWithProgramWarn | ( | string | name,
|  | Qore::Program | pgm,
|  | int | warning_mask = `WARN_MODULES`
| ) |  |

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

  name | the name or path of the user module to load
  pgm | the Program object to use as a container for the new user module, presumably this has a custom API that the user module can use; note that after this call the Program object will be owned by the user module, therefore the object itself will no longer be valid and any accesses to the object after this call will result in an exception
  warning_mask | the warning mask to use when loading the module; any warnings will be returned in the return value

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

Exceptions

  LOAD-MODULE-ERROR | module cannot be loaded: binary modules cannot be loaded in Program containers, module defines symbols already defined in the target object, etc

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()

nothing Qore::Program::lockOptions | ( |  | ) |

Locks parse options so that they cannot be changed.

Example:
  pgm.lockOptions();

## parse()

*hash< ExceptionInfo > Qore::Program::parse | ( | string | code,
|  | string | label,
|  | *softint | warning_mask,
|  | *string | source,
|  | *softint | offset,
|  | softbool | format_label = `True`
| ) |  |

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

  code | The code to parse into the Program object
  label | The label for the code; this label will be given if any parse or run-time errors are raised for the code given
  warning_mask | An optional warning mask; see Warning Constants for values to combine by binary-or; if this argument is 0 or not given then no warnings will be checked or issued and the return value will always be NOTHING
  source | An optional source file name for the code being parsed; this is useful if sections of a file are parsed
  offset | An optional line offset for use with the source parameter; this gives the line offset in the file to the code being parsed
  format_label | obsolete / ignored since Qore 0.9

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<ExceptionInfo> 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

  PROGRAM-PARSE-ERROR | this exception is thrown if any parse actions are started while the Program object has running threads

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]

nothing Qore::Program::parseCommit | ( |  | ) |

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:
  pgm.parseCommit();

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

  PROGRAM-PARSE-ERROR | this exception is thrown if any parse actions are started while the Program object has running threads

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]

*hash< ExceptionInfo > Qore::Program::parseCommit | ( | int | warning_mask | ) |

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<ExceptionInfo> 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

  PROGRAM-PARSE-ERROR | this exception is thrown if any parse actions are started while the Program object has running threads

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()

*hash< ExceptionInfo > Qore::Program::parsePending | ( | string | code,
|  | string | label,
|  | *softint | warning_mask,
|  | *string | source,
|  | *softint | offset,
|  | softbool | format_label = `True`
| ) |  |

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

  code | The code to parse into the Program object
  label | The label for the code; this label will be given if any parse or run-time errors are raised for the code given
  warning_mask | An optional warning mask; see Warning Constants for values to combine by binary-or; if this argument is 0 or not given then no warnings will be checked or issued and the return value will always be NOTHING
  source | An optional source file name for the code being parsed; this is useful if sections of a file are parsed
  offset | An optional line offset for use with the source parameter; this gives the line offset in the file to the code being parsed
  format_label | obsolete / ignored since Qore 0.9

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<ExceptionInfo> 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

  PROGRAM-PARSE-ERROR | this exception is thrown if any parse actions are started while the Program object has running threads

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()

nothing Qore::Program::parseRollback | ( |  | ) |

Removes all partially or fully-parsed code from the object along with other builtin objects; a Program object is not usable after calling this method; do not use this method but instead destroy the Program object.

Code Flags:
  DEPRECATED

See also
  - Qore::Program::parse()
  - Qore::Program::parseCommit()
  - Qore::Program::parsePending()
  - Qore::parse()

Exceptions

  PROGRAM-PARSE-ERROR | this exception is thrown if any parse actions are started while the Program object has running threads

Deprecated:
  if parsing fails or is rolled back, the Program object is no longer usable

## replaceParseOptions()

nothing Qore::Program::replaceParseOptions | ( | softint | opt | ) |

Replaces the parse options for the Program object.

An `OPTION-ERROR` exception is thrown if the calling Program object does not have PO_NO_CHILD_PO_RESTRICTIONS set.

Parameters

  opt | A single parse option or binary-or'ed combination of parse options to unset in the parse option mask for the object

Example:
  # disallow threading and GUI operations
  pgm.replaceParseOptions(PO_NO_THREADS | PO_NO_GUI);

Exceptions

  OPTION-ERROR | The calling Program does not have the PO_NO_CHILD_PO_RESTRICTIONS option set, and therefore cannot call Program::replaceParseOptions()

See also
  Program::setParseOptions() and Program::disableParseOptions().

## run()

auto Qore::Program::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:
  pgm.run();

## setGlobalVarValue()

nothing Qore::Program::setGlobalVarValue | ( | string | name,
|  | auto | value
| ) |  |

set the value of a global variable

Example:
  pgm.setGlobalVarValue("a", 1);

Parameters

  name | the name of the variable
  value | the value to assign

Exceptions

  UNKNOWN-VARIABLE | the variable is not a global variable

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()

nothing Qore::Program::setParseOptions | ( | softint | opt = `PO_DEFAULT` | ) |

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

  opt | A single parse option or binary-or'ed combination of parse options to set in the parse option mask for the object; the given argument will be combined with binary or with the existing parse option mask

Example:
  # disable threading and GUI operations
  pgm.setParseOptions(PO_NO_THREADS | PO_NO_GUI);

Exceptions

  OPTIONS-LOCKED | Parse options have been locked and cannot be changed
  PROGRAM-OPTION-ERROR | invalid parse options used

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

## setScriptPath()

nothing Qore::Program::setScriptPath | ( | *string | path | ) |

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

Parameters

  path | The path (directory and filename) for the current script; if the directory component is missing, then the current directory is assumed

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

## setThreadInit()

bool Qore::Program::setThreadInit | ( | *code | init | ) |

Sets a call reference or closure to run every time a new thread is started.

This code can be used to initialize global thread-local variables, for example.

Restrictions:
  Qore::PO_NO_THREAD_CONTROL

Parameters

  init | a call reference or closure to run every time a new thread is started or NOTHING to clear any thread initialization code

Returns
  True if there was already user initialization code set, False if not

Example:
  pgm.setThreadInit(sub () { var = 123; });

Note
  the code will be run for all new threads, but is not run by this method for the current thread

See also
  Qore::set_thread_init()

Since
  Qore 0.8.13

## setTimeZone()

nothing Qore::Program::setTimeZone | ( | TimeZone | zone | ) |

Sets the default local time zone for the object.

Example:
  TimeZone tz("Europe/Prague");
  pgm.setTimeZone(tz);

See also
  TimeZone::set()

## setTimeZoneRegion()

nothing Qore::Program::setTimeZoneRegion | ( | string | region | ) |

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

  region | The path to the zoneinfo file for the time zone region to set as the local time zone for the Program object

Example:
  pgm.setTimeZoneRegion("Europe/Prague");

Exceptions

  TZINFO-ERROR | Unable to read zoneinfo file; invalid file magic; error parsing zoneinfo file, etc

## setTimeZoneUTCOffset()

nothing Qore::Program::setTimeZoneUTCOffset | ( | softint | seconds_east | ) |

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

  seconds_east | The number of seconds east of UTC; for zones west of UTC, use negative numbers

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()

nothing Qore::Program::undefine | ( | string | def | ) |

Unsets a parse define for the current Program.

Parameters

  def | The name of the define to undefine; if the given define is not defined anyway, the operation is ignored

Example:
  pgm.undefine("PRODUCTION");