 |
Qore Programming Language Reference Manual
1.8.0
|
|
Qore Programming Language Reference Manual
1.8.0
|
Qore supports the use of parse directives in order to set parsing options, load modules, control warnings, and include other files.
Parse directives that set parsing options can be used any time parse options have not been locked on a Program object. They are used most often when it's not possible or desirable to set the parse options in the qore command line.
The following are the recommended parse directives for Qore programming (note that Qore is moving toward establishing %new-style as the default syntax; all examples given in the Qore documentation are given assuming %new-style):
Parse Directives
| Directive | Description |
| %allow-bare-refs | Prohibits the use of the "$" character in variable names, method calls, and object member references. This makes Qore scripts appear superficially more like C++ or Java programs.This parse option is set by default with %new-style. Name resolution is made in the following order when this option is set: local variables, class constants and static class vars (when parsing in class code), global variables, and (non-class) constants. Note that implicit arguments are still referenced with the "$" character even when this parse option is set; see also %require-dollar Since Qore 0.8.1 |
| %allow-debugger | Allows debugging actions that could be insecure such as reading the thread local variable stack<br> Since Qore 0.8.13 |
| %allow-injection | Allows code and dependency injections into the given Program object |
| %allow-returns | Allows the use of the deprecated returns keyword<br>Since Qore 0.9.4 |
| %allow-weak-references | Allows the use of the weak assignment operator (:=) Since Qore 0.8.13 |
| %append-include-path | Appends the given directories to qore's include path; also performs environment variable substitution |
| %append-module-path | Appends the given directories to qore's module path; also performs environment variable substitution Since Qore 0.8.6 |
| %assume-global | Resets the default Qore behavior of assuming global variable scope when variables are first referenced if no my or our is present; use after %assume-local to reset the default parsing behavior. This parse option is also set with %old-style Since Qore 0.8.4 |
| %assume-local | Assume local variable scope when variables are first referenced if no my or our is present. When used with %allow-bare-refs, local variables without my must be declared with a data type restriction (can be any). This parse option is set by default with %new-style; see also %assume-global Since Qore 0.8.1 |
| %broken-cast | Use old pre-0.9.4 broken cast<> operator handling where NOTHING would be accepted without an error |
| %broken-int-assignments | Use old pre-0.8.12 broken int and softint runtime handling where type errors were ignored at runtime |
| %broken-list-parsing | Use old pre-0.8.12 broken list parsing where certain lists without parentheses would be rewritten to make top-level statements like list l = 1, 2, 3; valid |
| %broken-logic-precedence | Use old pre-0.8.12 precedence of logical and bitwise operators |
| %broken-loop-statement | Accept break and continue outside of loops as with pre-0.8.13 |
| %broken-operators | Accept spaces in multi-character operators as with pre-0.8.12 |
| %broken-range | Include the upper limit in range() and xrange() as with pre-0.9.5 |
| %broken-references | Do not enforce reference and *reference type restrictions as with pre-0.8.13 |
| %broken-sprintf | Use pre-0.9 sprintf format handling where no argument is handled differently than NOTHING |
| %correct-cast | revert the effect of the %broken-cast parse option |
| %correct-int-assignments | revert the effect of the %broken-int-assignments parse option |
| %correct-list-parsing | revert the effect of the %broken-list-parsing parse option |
| %correct-logic-precedence | revert the effect of the %broken-logic-precedence parse option |
| %correct-loop-statement | revert the effect of the %broken-loop-statement parse option |
| %correct-operators | revert the effect of the %broken-operators parse option |
| %correct-range | revert the effect of the %broken-range parse option |
| %correct-references | revert the effect of the %broken-references parse option |
| %correct-sprintf | revert the effect of the %broken-sprintf parse option |
| %define | Creates and optionally sets a value for a parse define Since Qore 0.8.3 |
| %disable-all-warnings | Turns off all warnings |
| %disable-warning warning-code | Disables the named warning until %enable-warning is encountered with the same code or %enable-all-warnings is encountered |
| %else | Allows for parsing an alternate block when used with the %ifdef or %ifndef parse directives (for conditional parsing based on parse defines) Since Qore 0.8.3 |
| %enable-all-warnings | Turns on all warnings |
| %enable-warning warning-code | Enables the named warning |
| %endif | Closes a conditionally-parsed block started by the %ifdef or %ifndef parse directives Since Qore 0.8.3 |
| %endtry | Closes a %try-module or %try-reexport-module block Since Qore 0.8.6 |
| %exec-class class_name | Instantiates the named class as the application class; also turns on %no-top-level. If the program is read from stdin or from the command line, an argument must be given specifying the class name. Any top level statements before this directive are silently ignored |
| %ifdef | Opens a conditionally-parsed block; if the given parse define is defined, then the block after the %ifdef is parsed until either an %else or an %endif Since Qore 0.8.3 |
| %ifndef | Opens a conditionally-parsed block; if the given parse define is not defined, then the block after the %ifdef is parsed until either an %else or an %endif Since Qore 0.8.3 |
| %include file_name | Starts parsing file_name immediately. Parsing resumes with the current input after file_name has been completely parsed |
| %lockdown | Made up of %no-external-access, %no-threads, and %no-io; equivalent to parse option Qore::PO_LOCKDOWN and the –lockdown command line option |
| %lock-options | Prohibits further changes to parse options (equivalent to the --lock-options command line option) |
| %lock-warnings | Prohibits further changes to the warning mask (equivalent to the --lock-warnings command line option) |
| %loose-args | reverts the effect of the %strict-args parse options |
| %loose-types | reverts the effect of the %strict-types parse options |
| %new-style | Sets both %allow-bare-refs and %assume-local. These two options together make programming in Qore superficially more like programming in C++ or Java programs; use this if you dislike programming with the "$" sign, for example; see also %old-style Since Qore 0.8.1 |
| %old-style | Resets default Qore parsing behavior by setting %require-dollar and %assume-global; this option is the opposite of %new-style Since Qore 0.8.4 |
| %no-debugging | Forbids debugging of the current Program object Since Qore 0.8.13 |
| %no-class-defs | Disallows class definitions; equivalent to Qore::PO_NO_CLASS_DEFS and the --no-class-defs command line option |
| %no-child-restrictions | Allows child program objects to have parse option restrictions that are not a strict subset of the parents'; equivalent to parse option Qore::PO_NO_CHILD_PO_RESTRICTIONS and the --no-child-restrictions command line option |
| %no-constant-defs | Disallows constant definitions; equivalent to parse option Qore::PO_NO_CONSTANT_DEFS and the --no-constant-defs command line option |
| %no-database | Disallows access to database functionality (for example the Datasource class; equivalent to parse option Qore::PO_NO_DATABASE and the --no-database command line option |
| %no-external-access | made up of %no-process-control, %no-network, %no-filesystem, %no-database, %no-external-info, and %no-modules; equivalent to parse option Qore::PO_NO_EXTERNAL_ACCESS and the --no-external-access command line option |
| %no-external-info | Disallows any access to functionality that provides external information (see %no-external-info for a list of features not available with this parse option); equivalent to parse option Qore::PO_NO_EXTERNAL_INFO and the --no-external-info command line option |
| %no-external-process | Disallows any access to external processes (see %no-external-process for a list of features not available with this parse option); equivalent to parse option Qore::PO_NO_EXTERNAL_PROCESS and the --no-external-process command line option |
| %no-filesystem | Disallows access to the local filesystem; equivalent to parse option Qore::PO_NO_FILESYSTEM and the --no-filesystem command line option |
| %no-global-vars | Disallows the use of global variables; equivalent to parse option Qore::PO_NO_GLOBAL_VARS and the --no-global-vars command line option |
| %no-gui | Disallows functionality that draws graphics to the display; equivalent to parse option Qore::PO_NO_GUI and the -pno-gui command line option |
| %no-io | Made up of %no-gui | %no-terminal-io | %no-filesystem | %no-network | %no-database; equivalent to parse option Qore::PO_NO_IO and the –no-io command line option |
| %no-locale-control | Disallows access to functionality that changes locale information (see no-locale-control for a list of features not available with this parse option); equivalent to parse option Qore::PO_NO_LOCALE_CONTROL and the --no-locale-control command line option |
| %no-modules | Disallows loading modules with the %requires, %try-module, and %try-reexport-module parse directive or at runtime with load_module(); equivalent to Qore::PO_NO_MODULES and the -pno-modules command line option Since Qore 0.8.4 |
| %no-namespace-defs | Disallows new namespace definitions; equivalent to Qore::PO_NO_NAMESPACE_DEFS and the --no-namespace-defs command line option |
| %no-network | Disallows access to the network; equivalent to parse option Qore::PO_NO_NETWORK and the --no-network command line option |
| %no-new | Disallows use of the new operator; equivalent to parse option Qore::PO_NO_NEW and the --no-new command line option |
| %no-process-control | Disallows access to functions that would affect the current process (see %no-process-control for a list of features not available with this parse option); equivalent to parse option Qore::PO_NO_PROCESS_CONTROL and the --no-process-control command line option |
| %no-reflection | Disallows access to the reflection API provided by the reflection module; equivalent to parse option Qore::PO_NO_REFLECTION Since Qore 0.9 |
| %no-subroutine-defs | Disallows subroutine (function) definitions; equivalent to parse option Qore::PO_NO_SUBROUTINE_DEFS and the --no-subroutine-defs command line option |
| %no-terminal-io | Disallows access to terminal I/O (see %no-terminal-io for a list of features not available with this parse option); equivalent to parse option Qore::PO_NO_TERMINAL_IO and the -pno-terminal-io command line option |
| %no-thread-classes | Disallows access to thread classes (see %no-thread-classes for a list of features not available with this parse option); equivalent to parse option Qore::PO_NO_THREAD_CLASSES and the --no-thread-classes command line option |
| %no-thread-control | Disallows access to thread control operations (see %no-thread-control for a list of features not available with this parse option); equivalent to parse option Qore::PO_NO_THREAD_CONTROL and the --no-thread-control command line option |
| %no-thread-info | Disallows any access to functionality that provides threading information (see %no-thread-info for a list of features not available with this parse option); equivalent to parse option Qore::PO_NO_THREAD_INFO and the --no-thread-info command line option |
| %no-threads | Disallows access to all thread control operations and thread classes (equivalent to --no-thread-control and --no-thread-classes together); equivalent to parse option Qore::PO_NO_THREADS and the --no-threads command line option |
| %no-top-level | Disallows any further top level code; equivalent to parse option Qore::PO_NO_TOP_LEVEL_STATEMENTS and the --no-top-level command line option |
| %no-transient | Removes the Transient Members keyword for backwards-compatibility; equivalent to parse option Qore::PO_NO_TRANSIENT |
| %no-uncontrolled-apis | Disallows access to uncontrolled APIs such as external language bindings or direct generic system call APIs that could bypass Qore's sandboxing controls |
| %perl-bool-eval | Set to mimic perl's boolean evaluation; this is the default with qore >= 0.8.6; prior to this version, by default qore used strict mathematic boolean evaluation, where any value converted to 0 is False and otherwise it's is True. As of Qore 0.8.6+, this parse option is only needed if %strict-bool-eval is set. When this option is set, boolean evaluation follows the same rules as <value>::val(); see also %strict-bool-eval Since Qore 0.8.6 |
| %push-parse-options | Stores parse options so that they will be restored when the current file is done parsing; use in include files to ensure parse options are set appropriately for the file being parsed |
| %require-dollar | Resets the default Qore behavior where the use of the "$" character in variable names, method calls, and object member references is required; use after %allow-bare-refs to reset the default parsing behavior Since Qore 0.8.4 |
| %require-our | Requires global variables to be declared with our prior to use (like perl's use strict vars pragma); equivalent to parse option Qore::PO_REQUIRE_OUR and the --require-our command line option |
| %require-prototypes | Requires type declarations for all function and method parameters and return types. Variables and object members do not need to have type declarations; equivalent to parse option Qore::PO_REQUIRE_PROTOTYPES and the --require-prototypes command line option Since Qore 0.8.0 |
| %require-types | Requires type declarations for all function and method parameters, return types, variables, and object members; equivalent to parse option Qore::PO_REQUIRE_TYPES and the --require-types command line option; also implies %strict-args Since Qore 0.8.0 |
%requires[(reexport)] feature [<|<=|=|>=|> version] | If the named feature is not already present in Qore, then the QORE_MODULE_DIR environment variable is used to provide a list of directories to seach for a module with the same name (feature[-api-x.y].qmod for binary modules or feature.qm for user modules). If the module is not found, then the qore default module directory is checked.This directive must be used to load modules providing parse support (i.e. modules providing classes, constants, functions, etc that are resolved at parse time). If version information is provided, then it is compared with the module's version information, and if it does not match a parse exception is raised. See also Qore::load_module() for a function providing run-time module loading and %try-module and %try-reexport-module for a similar parse directive that allows module loading errors to be handled at runtime |
| %set-time-zone | Sets the time zone for the current program from a UTC offset (with format "+/-[00[:00[:00]]"; ":" characters are optional) or a time zone region name (ex: "Europe/Prague") Since Qore 0.8.3 |
| %strict-args | Prohibits access to builtin functions and methods flagged with RUNTIME_NOOP and also causes errors to be raised if excess arguments are given to functions that do not access excess arguments and if a non-list lvalue is passed to the Push Operator (push), Pop Operator (pop), or Shift Operator (shift) Since Qore 0.8.0 |
| %strict-bool-eval | Sets qore's default strict mathematic boolean evaluation mode, where any value converted to 0 is False and otherwise it's is True; this was how qore behaved by default prior to v0.8.6. Equivalent to parse option Qore::PO_STRICT_BOOLEAN_EVAL and the -pstrict-bool-eval command line option. See also %perl-bool-eval Since Qore 0.8.6 |
| %strict-types | Sets strict type checking and automatically sets default values for lvalues with type restrictions that have default values |
| %strong-encapsulation | Disallows out-of-line class and namespace declarations. Since Qore 0.8.13 |
%try-module [(var_decl)] feature [<|<=|=|>=|> version] | If the named feature is not already present in Qore, then the QORE_MODULE_DIR environment variable is used to provide a list of directories to seach for a module with the same name (feature[-api-x.y].qmod for binary modules or feature.qm for user modules). If the module is not found, then the qore default module directory is checked.If an error occurs loading the module, then the variable declared after %try-module is instantiated with the exception information, and the code up to the %endtry parse declaration is parsed into the program, allowing for the qore script/program to handle module loading errors at parse time for modules that must be loaded at parse time.If version information is provided, then it is compared with the module's version information, and if it does not match a parse exception is raised that is handled like any other load error. See also Qore::load_module() for a function providing run-time module loading and %requires for a similar declaration that does not allow for parse-time module loading error handling. Since Qore 0.8.6 |
%try-reexport-module [(var_decl)] feature [<|<=|=|>=|> version] | The same as %try-module except that if used in a user module, the module is reexported to the importing code<br> Since Qore 0.8.13 |
%allow-bare-refs–allow-bare-refs, -B"$" character in variable names, method calls, and object member references. This makes Qore scripts appear superficially more like C++ or Java programs. This parse option is set by default with %new-style and is the opposite of %require-dollar."$" character even when this parse option is set.%allow-debugger%allow-injection-pallow-injection%allow-returns-pallow-returnsreturns keyword.%allow-weak-references-pallow-weak-references%append-include-path dir1[:dir2...]%append-module-path dir1[:dir2...]%assume-global%assume-local--assume-local%broken-cast-pbroken-cast%broken-int-assignments-pbroken-int-assignments%broken-list-parsing-pbroken-list-parsinglist l = 1, 2, 3; valid.%broken-logic-precedence-pbroken-logic-precedenceAn example of impact of %broken-logic-precedence directive:
%broken-loop-statement--broken-loop-statement%broken-operators-pbroken-operatorsFor example, when this parse directive is not set, the following is a bug:
When this parse directive is set; the above code is accepted.
%broken-range--pbroken-range%broken-references--pbroken-references%broken-sprintf--pbroken-sprintf%correct-loop-statement%correct-operators%correct-range%correct-references%correct-sprintf%define--define, -D%disable-all-warnings%disable-warning%else%enable-all-warnings--enable-all-warnings, -W%enable-warning--enable-warning, -w%endif%endtry%exec-class--exec-class, -x%ifdef%ifdef is parsed until either an %else or an %endif%ifndef%ifndef is parsed until either an %else or an %endif%include""/"), then files are searched first in the directory of the currently-executing script (if known), then in each path in the environment variable QORE_INCLUDE_DIR.'$', then environment variable substitution is performed on the leading environment variable%lockdown--lockdown%lock-options--lock-options, -K%lock-warnings--lock-warnings, -A%loose-args%loose-types%new-style--new-style, -n"$" sign, for example.%old-style%no-debugging%no-child-restrictions--no-child-restrictions, -I%no-class-defs--no-class-defsclass will result in a parse exception.%no-constant-defs--no-constant-defsconst will result in a parse exception.%no-database--no-database%no-external-access--no-external-access%no-external-info--no-external-info%no-external-process--no-external-process, -E%no-filesystem--no-filesystem, -F%no-global-vars--no-global-vars, -G%no-gui--no-gui, –set-parse-option=no-gui, -pno-gui%no-io--no-io, –set-parse-option=no-io, -pno-io%no-locale-control--no-locale-control, -P%no-modules-pno-modules%no-namespace-defs--no-namespace-defs, -M%no-network--no-network, -Y%no-new--no-new, -N%no-process-control--no-process-control, -P%no-reflection--pno-reflection%no-subroutine-defs--no-subroutine-defs, -S%no-terminal-io--no-terminal-io,--set-parse-option=no-terminal-io, -pno-terminal-io%no-thread-classes--no-thread-classes%no-thread-control--no-thread-control, -R%no-thread-info--no-thread-info%no-threads--no-threads, -T%no-top-level--no-top-level, -L%no-transient--pno-transientno-uncontrolled-apis-p=no-uncontrolled-apis%perl-bool-eval%perl-bool-eval is the default behavior and therefore only needs to be set if %strict-bool-eval was set first.string is: "hello"When it's not set (i.e. %strict-bool-eval is set), nothing is printed out as the string expression evaluates to False due to qore's old strict mathematical boolean evaluation.
"0" and empty strings, integer, float, and number 0 (zero), absolute date 1970-01-01Z (ie the start of the epoch with an offset of 0), relative date PT0H (ie any relative date with a 0 duration), NULL, empty binary objects, empty hashes, and empty lists. All other values are True.%push-parse-options%require-dollar"$" character in variable names, method calls, and object member references is required; use after %allow-bare-refs to reset the default parsing behavior%require-our--require-our, -O%require-prototypes--require-prototypes%require-types--require-typesCALL-WITH-TYPE-ERRORS exceptions to be thrown if a function, method, or code call is made with excess arguments not handled by the target. In case calls are made to user code over a Program barrier, the parse options of the target code determine if this exception is raised;%requires[(reexport)] feature [<|<=|=|>=|> version]--load, -l(reexport) option is used in a user module, then any modules loaded with this form of the %requires parse directive will also be imported into the importing Program.<, <=, =, >=, or >) and version information after the module name as well. Version numbers are compared via integer comparisons of each element, where elements are separated by a ".". If one of the versions does not have as many elements as another, the missing elements are assumed to be "0" (i.e. version "1.0" compared with version "1.0.1" will be extended to "1.0.0")."qore". This pseudo-feature can be used to check the minimum Qore version; if this feature is requested with version information, then the Qore library's version information is used for the version number comparison.%set-time-zone--time-zone, -z"+/-00[:00[:00]]"; ":"" characters are optional) or a time zone region name (ex: \c "Europe/Prague").%strict-args--strict-argsCALL-WITH-TYPE-ERRORS exception is thrown. In case calls are made to user code over a Program barrier, the parse options of the target code determine if this exception is raised;%strict-bool-eval-pstrict-bool-eval%strict-bool-eval is set, then Qore's boolean evaluation will evaluate "hello" in a strict mathematical sense and convert it to 0, which is False, so nothing would be printed out, but when %perl-bool-eval is enabled, this will be True (following the rules for <string>::val()).%strict-types-pstrict-types%strong-encapsulation-pstrong-encapsulation%try-module [(var_decl)] feature [<|<=|=|>=|> version]%try-module is instantiated with the exception information, and the code up to the %endtry parse declaration is parsed into the program, allowing for the qore script/program to handle module loading errors at parse time for modules that must be loaded at parse time.<, <=, =, >=, or >) and version information can be optionally given after the module name as well. Version numbers are compared via integer comparisons of each element, where elements are separated by a ".". If one of the versions does not have as many elements as another, the missing elements are assumed to be "0" (i.e. version "1.0" compared with version "1.0.1" will be extended to "1.0.0"). Version errors are handled in the same was as any other module loading error."some_module" module if it is at least version 2.0, and print an error message and exit gracefully if it cannot be loaded. Note that in order for the Qore script to be executable and exit gracefully in case the given module cannot be loaded, a parse define must be set in the %try-module block and any code that accesses definitions provided by that module must be wrapped in %ifndef blocks as in the above example."qore". This pseudo-feature can be used to check the minimum Qore version; if this feature is requested with version information, then the Qore library's version information is used for the version number comparison.%try-module variable declaration; the value assigned to the variable will be a hash.%try-reexport-module [(var_decl)] feature [<|<=|=|>=|> version]%try-module is instantiated with the exception information, and the code up to the %endtry parse declaration is parsed into the program, allowing for the qore script/program to handle module loading errors at parse time for modules that must be loaded at parse time.<, <=, =, >=, or >) and version information can be optionally given after the module name as well. Version numbers are compared via integer comparisons of each element, where elements are separated by a ".". If one of the versions does not have as many elements as another, the missing elements are assumed to be "0" (i.e. version "1.0" compared with version "1.0.1" will be extended to "1.0.0"). Version errors are handled in the same was as any other module loading error."some_module" module if it is at least version 2.0, and print an error message and exit gracefully if it cannot be loaded. Note that in order for the Qore script to be executable and exit gracefully in case the given module cannot be loaded, a parse define must be set in the %try-module block and any code that accesses definitions provided by that module must be wrapped in %ifndef blocks as in the above example."qore". This pseudo-feature can be used to check the minimum Qore version; if this feature is requested with version information, then the Qore library's version information is used for the version number comparison.%try-module variable declaration; the value assigned to the variable will be a hash.