Qore Programming Language Reference Manual
0.8.7
|
Qore modules allow the Qore language to be extended at run-time.
To load a module at parse time (normally required for most modules), use the %requires or %try-module parse directive. If the named feature is not already present in Qore, Qore looks for a module with this name in the directories listed in the QORE_MODULE_DIR
environment variable (see Environment Variables).
Use the load_module() function to load Qore modules at run-time; however, note that any module providing parse support (classes, constants, functions, etc) must be loaded at parse time using the %requires or %try-module parse directive.
From Qore 0.7.1 onwards, you can specify a comparison operator (one of < <=, =, >=, 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"
).
Also note that DBI drivers are loaded on demand by the Qore::SQL::Datasource and Qore::SQL::DatasourcePool classes.
There are two types of modules: Binary Modules and User Modules.
At the time of writing this documentation, the following modules exist for Qore:
Qore Modules
Type | Module | Description |
user | CsvUtil | Provides code to help parse CSV or other structured text files |
user | HttpServer | Provides a multi-threaded HTTP server |
user | Mime | Provides MIME definitions and functions |
user | MailMessage | Provides supporting classes for the Pop3Client and SmtpClient modules |
user | Pop3Client | Provides POP3 client functionality |
user | SmtpClient | Provides SMTP client functionality |
user | TelnetClient | Provides Telnet client functionality |
builtin | asn1 | Provides ASN.1 functionality |
builtin | db2 | Provides an IBM DB2 driver |
builtin | freetds | Provides a FreeTDS-based DBI driver |
builtin | glut | Provides GLUT functionality |
builtin | json | Provides JSON functionality |
builtin | mysql | Provides a MySQL DBI driver |
builtin | ncurses | Provides curses APIs |
builtin | oracle | Provides an Oracle DBI driver |
builtin | opengl | Provides an OpenGL API |
builtin | pgsql | Provides a PostgreSQL DBI driver |
builtin | qt4 | Provides Nokia (formerly Trolltech) QT4 APIs for GUI development |
builtin | sqlite3 | Provides a SQLite3 DBI driver |
builtin | ssh2 | Provides SSH2 and SFTP functionality |
builtin | sybase | Provides a Sybase DBI driver |
builtin | tibae | Provides TIBCO ActiveEnterprise(TM) (TIBCO, Inc) functionality |
builtin | tibrv | Provides TIBCO Rendezvous(R) (TIBCO, Inc) functionality |
builtin | tuxedo | Provides Oracle (ex Bea) Tuxedo functionality |
builtin | uuid | Provices an API for generating UUIDs |
builtin | xml | Provides XML, XPath, etc functionality |
builtin | xmlsec | Provides xmldsig and xmlenc functionality |
builtin | yaml | Provides YAML functionality |
Binary modules are written in C++ and delivered in binary form. They must conform to the Qore Module API and have the file extension "*.qmod"
. Binary modules normally depend on other shared libraries and therefore can only be loaded if the libraries they require are present on the system and can be found in the library path.
Binary modules are merged into Program objects in the same way as the static system namespace objects are imported. It is possible to import a binary module and be able to use only part of its functionality, for example, if the importing Program cannot access the filesystem, and the module has functions that access the filesystem, only the functions that access the filesystem will not be available. In user modules, the functional domain is set on the module level and not on the individual function or method level as with builtin objects, so user modules are either completely imported or not at all.
Please note that as of version 0.7.0 onwards, the source code for binary modules has been split from the main Qore library source code into separate projects; see Qore's home page for more information.
User modules are written in Qore and delivered in source form. They must have the extension "*.qm"
.
User modules will have their own dedicated Program object; the Program object is created automatically when the module is loaded and initialized. The module's Program object is created with locked parse options as follows:
init
closureWhen parsing module code, the default warning mask is set to WARN_MODULES, and any warnings are treated as errors. Furthermore, any restrictions that the importing Program object has will be added to the module's Program object.
Any namespaces, classes, constants, functions, and global variables declared as public will be exported into the importing Program object; all other declarations will be private to the module's Program object. Note that the root namespace of a module Program is always public by default.
Note that global variables exported from a module's Program object are exported as references; each global variable declared in a module is unique, and they reside in the module's Program object.
Furthermore, when using an environment with multiple Program objects, if a user module has already been loaded and initialized, then it's functional domain mask is compared against any importing Program object's restrictions; if the module uses functionality that is not allowed in the importing Program object, then an exception is raised and the module is not imported.
Also note that the Qore::Program::constructor() applies a mask to the parse option mask option when Program objects are created in a user module; in this case the parse options passed to the child Program object are masked with the current parse options in the user module, and they are locked so that they cannot be made less restrictive. This is to prevent user modules from circumventing functional restrictions imposed by parse options.
User modules are declared with a special syntax in Qore:
User Module Declaration Syntax
module
name {
version = "
version string";
desc = "
description string";
author = "
author string";
[url = "
URL string";]
[init =
initialization closure;]
[del =
deletion closure;]
}
Module properties are as follows:
version:
(required) must be assigned to a string giving the version of the moduledesc:
(required) must be assigned to a string giving a text description of the moduleauthor:
(required) must be assigned to a string giving the module's author's nameurl:
(optional) if present, must be a string giving the URL or the moduleinit:
(optional) if present, must be a closure that will be executed when the module is loaded; this can be used to initialize the module, for exampledel:
(optional) if present, must be a closure that will be executed when the module is unloaded; this can be used to stop running services or free resources managed and still allocated by the module, for exampleinit
closure will cause the module to fail to loadinit
and del
closures are displayed on stdoutOnly objects defined with the public
keyword are made available in Program objects importing the user module. All other declarations and definitions are private to the module.
The public
keyword also affects inheritance in child Program objects as well as controlling exported symbols from user modules.
The public
keyword must be used with the following declarations in the module to export them:
public
in order for any of their contents also to be exported (it is an error to try to declare public members of a module-private namespace). ex:public
will not be exported; there is no way to export part of a class; either the entire class is exported or it is not. ex:public
to be exported; ex:public
in order to be exported. ex:public
will be exported. ex:init
closure to initialize the module and any global variables requiring initialization.User modules are only imported into a Program if the importing Program can use all of the capabilities used in the user module. It is not possible to partially import a user module (in contrast with binary modules, which can be imported even if they expose functionality not allowed in the importing Program, however that functionality will not be available in that case). User module Program objects have a functional domain attribute set on the Program level, so either a user module is imported in its entirety or not at all.
Here is an example declaring user module "foo"
version "1.0"
:
When using the %exec-class parse directive, the application object will go out of scope as soon as the constructor terminates (unless there are valid scope-extending references to the application object, such as making an assignment of $self
to a global variable in the contructor).
Therefore when using a module that provides services in its own threads (such as, for example, the HttpServer module), it's important to make sure that the application object does not go out of scope while non-static method call references to the application object are needed by active threads inthe user module (for example, non-static method call references passed as callbacks to the HttpServer module, etc).
This also applies to call references to non-static methods passed to set_signal_handler().
If a module thread tries to use a callback or closure in a Program that has already gone out of scope, an OBJECT-ALREADY-DELETED
exception ("attempt to access member of an already-deleted object"
) is thrown.
Therefore in such cases it's best to wait for all threads in any modules to terminate before allowing the application object's constructor to terminate.
For an example of this, see the example program examples/httpserver.q
where the main Program calls HttpServer::waitStop() before exiting the application object's constructor for this reason.