v. 0.8.0
Revision History | ||
---|---|---|
Revision 3.0 | 18 November 2009 | dn |
Update to 0.8.0 | ||
Revision 2.9 | 6 November 2009 | dn |
Update to 0.7.7 | ||
Revision 2.8 | 13 July 2009 | dn |
Update to 0.7.6 | ||
Revision 2.7 | 22 June 2009 | dn |
Update to 0.7.5 | ||
Revision 2.6 | 4 April 2009 | dn |
Update to 0.7.4 | ||
Revision 2.4 | 3 December 2008 | dn |
Update to 0.7.2 | ||
Revision 2.2 | 6 November 2008 | dn |
Update to 0.7.1 | ||
Revision 2.1 | 17 July 2008 | dn |
Update to 0.7.0 | ||
Revision 2.0 | 2 March 2007 | dn |
Update to 0.6.2 | ||
Revision 1.9 | 8 February 2007 | dn |
Update to 0.6.1 | ||
Revision 1.8 | 19 January 2007 | dn |
Update to 0.6.0 | ||
Revision 1.7 | 10 October 2006 | dn |
Update to 0.5.3 | ||
Revision 1.6 | 15 September 2006 | dn |
Update to 0.5.2 | ||
Revision 1.5 | 8 June 2006 | dn |
Update to 0.5.1 | ||
Revision 1.4 | 7 May 2006 | dn |
Update to 0.5.0, extensive updates, new content | ||
Revision 1.3 | 30 Nov 2005 | dn |
Update to 0.4.2 | ||
Revision 1.2 | 26 Oct 2005 | dn |
Update to 0.4.0 | ||
Revision 1.1 | 14 Oct 2005 | hw |
Converted to docbook.xml | ||
Revision 1.0 | 2 Aug 2005 | hw |
First release |
Table of Contents
The Qore programming language is a powerful, thread-capable, embeddable weakly-typed language with optional strong typing and procedural and object-oriented features designed for anything from quick scripting to complex multithreaded, network-aware application development to embedded application scripting. Qore was initially designed to facilitate the rapid implementation of sophisticated interfaces in embedded code in an enterprise environment, and has since grown into a general-purpose language as well.
Qore exports a C++ API to allow programs or libraries to embed Qore code; this manual documents Qore's user-level features, for more information about Qore's C++ API, see the Qore's home page.
Qore features database, XML, and JSON integration into the syntax, functions, data structures, and operators of the language.
Flexible character encoding support is also built-in to Qore strings, and automatic character encoding conversions are supported, enabling correct behavior when working in an environment with mixed character encoding requirements (see Qore Strings and Character Encoding).
Qore includes the following design points:
Support for Embedded Logic
Qore was designed to support embedding logic in applications; this also applies to applications written in Qore as well as applications using the Qore library's public C++ API. By using the Program class, discrete objects can be created and destroyed at will containing embedded code to extend or modify the behavior of your application in user-defined ways. The Program class allows the capabilities of embedded code to be arbitrarily restricted as well.
Thread Safety and SMP Scalability
All elements of Qore are thread-safe, and the language in general has been designed with SMP scalability in mind. The internal design and implementation of Qore favors multithreaded performance over single-threaded performance, so multithreaded Qore programs can count on an efficient and stable execution platform, and do not have to limit themselves to a subset of Qore's functionality (see Threading). Additionally, Qore includes optimizations designed to reduce the number of SMP cache invalidations that provide a substantial performance boost on SMP machines.
Qore supports deadlock detection in complex locking scenarios and will throw an exception rather than allow an operation to be performed that would cause a deadlock. Furthermore, Qore's threading primitives detect threading errors and throw exceptions in these cases as well.
Database Integration and DBI Layer
Retrieving, comparing, and manipulating data in a consistent manner from heterogenous database types is made possible by Qore's built-in database integration. Qore was designed with a database independent interfacing (DBI) layer, providing a standard interface for Qore programs to access any database supported by a Qore DBI driver (see the Datasource Class).
XML and JSON Integration
Qore uses the libxml2 library to provide fast and efficient XML functionality. Qore's XML integration enables serialization from Qore data structures to XML strings and deserialization from XML strings to Qore data structures, making it trivial to work with data in XML format (see XML Integration). Qore provides JSON and JSON-RPC integration as well. There is also a module providing YAML serialization and deserialization support.
Function and Class Library
Qore's basic functionality covers areas such as: POSIX-compliant command-line parsing (ex: GetOpt Class), XML and JSON serialization/deserialization, strong encryption and digest calculation, thread synchronization (ex: Queue Class, Mutex Class, Condition Class, etc), working with files (File class), socket, HTTP, and higher-level protocol communication (Socket, HTTPClient, XmlRpcClient, JsonRpcClient, FtpClient classes, optionally with TLS/SSL encryption), support for dynamic embedded application logic (Program Class). Additionally, Qore's functionality is extended with modules delivered separately from the Qore library (see Qore's home page for more information.
Logical Syntax
Qore syntax is similar to other programming languages, allowing new programmers to rapidly come up to speed in Qore. Qore borrows features from languages such as: C++ (ex: multiple inheritance, exception handling, static methods), Java (ex: the synchronized keyword, the instanceof operator, object and class implementation), Perl (ex: the foreach statement, splice, push, pop, chomp, splice operators, perl5-compatible regular expressions, and more), the D Programming Language (the on_exit, on_success, and on_error statements provide exception-aware functionality similar to scope(exit), scope(failure)
, allowing exception-aware cleanup code to be placed next to the code requiring cleanup), and others, also with many features unique to Qore. Furthermore, Qore supports closures (including binding local variables in the closure in a way that is safe to use even in multithreaded contexts) and features for advanced list processing (map, foldl, foldr, and select).
Qore's operators are designed to produce the expected results for the programmer even when data types are mixed, a feature meant to further flatten the learning curve for new programmers.
Simple or complex interfaces involving data extraction and manipulation from multiple Oracle, MySQL, PostgreSQL and other databases and/or multiple applications connected with a supported messaging bus or through lightweight web service protocols bus can be developed quickly and easily with Qore, particularly in comparison with Java, Perl, or C/C++. Furthermore, solutions based on Qore are transparent and easily maintainable, bringing advantages for the developer and end-user alike.
Additionally, Qore is thoroughly tested with valgrind on Linux and dbx on Solaris for memory leaks and memory errors. While it is possible that there are bugs in some less tested code paths, every effort is made to eliminate all bugs before each new release, particularly memory bugs and race conditions, in order to ensure that Qore releases are of the highest possible quality.
Examples of Qore code are given in the following font:
#!/usr/bin/qore # # this is an example of Qore code
keywords are given in bold:
# "if" is a key word
if ($a == 1) print("yes\n");
placeholders are given in italics:
if (expression
)statement
where expressions and statements are defined in this document. The text above indicates that any valid expression and any valid statement may be used in the positions indicated.
Optional text is given in square brackets "[" and "]" as follows:
sub name([
$variable1
, $variable2
, ...])
indicating that an arbitrarily long list of variable names separated by commas (or nothing at all) may appear in subroutine (function) declarations.
A Qore program is composed of a series of declarations, statements, subroutine definitions, and/or class definitions. Non-block statements are terminated by a semi-colon ";". Block statements are grouped by using curly brackets ("{" and "}"), as in C, C++, Java, and Perl.
Programmers familiar with C, C++, Java, and/or Perl should find the standard Qore syntax intuitive and should be productive fairly quickly with the language. However Qore has unique features that differentiate it from other languages, and these features must be mastered in order to leverage the full power of Qore.
Qore programs/scripts are free form. Formatting does not affect the execution of the program; formatting is at the discretion of the programmer and should be used to enhance readability and clarity of the source code.
Qore was creaetd as a weakly typed language. That means that variables without type restructions can hold values of any type and subroutines with out type restrictions can return any value type (or none at all, see Variables) and take arguments of any type. Furthermore list elements can be of any type (they do not have to be uniform), and multidimensional lists can have a different number of elements in each list. The same type flexibility holds true of hashes, objects, and all combinations of container types.
Qore can be used a a traditional subroutine-based scripting language or as a pure object-oriented language, where the application is defined as a class. Aside from traditional local and global variables, constants, and subroutines, Qore also supports nested namespaces, classes, multiple inheritance, overriding base class constructor arguments, private members and methods, and static class methods.
All elements of Qore are designed to work together seamlessly: database access, XML transformations, socket communication, embedding logic in subprograms, regular expressions, operators, functions, and all other elements are thread-safe and built on an execution engine that was designed for SMP scalability.
Qore automatically converts data types when necessary when evaluating operators. The goal is to provide the expected result for the programmer without requiring the programmer to explicitly convert data types. Please see Operators for more information.
Qore supports signal handling by dispatching Qore-language signal handlers in a safe manner, asynchronously to the actual receipt of the signal.
UNIX operating systems allow an executable script to specify their interpreter. This is done by setting the first line in the program to a special string indicating the location of the Qore binary. For the purposes of this document, the location for the Qore binary is assumed to be /usr/bin/qore
. The first line of Qore scripts in this case should look as follows:
#!/usr/bin/qore
If another installation directory is used (such as /usr/local/bin
), then the correct path must be reflected in the first line of the Qore script.
Qore convention dictates that Qore script file names end with .q
.
This section will outline the environment variables that are used by Qore.
Table 2.1. Qore Environment Variables
Environment Variable | Description |
---|---|
| This environment variable should contain a colon-separated list of directories which will be searched for Qore modules when Qore starts. If any modules are found, they are loaded automatically before any parsing starts. |
| This environment variable should contain a colon-separated list of directories which will be searched when modules are loaded with the |
| This variable should be a colon-separated list of directories where the Qore binary should look for include files |
| If this variable is set, then the default character encoding name for the process will be the value of this variable. This variable takes precedence over the |
| If this variable is set and includes a character encoding specification, then, if the |
Qore modules allow the Qore language to be extended at run-time. Qore modules must conform to the Qore Module API and have the file extension *.qmod
. Qore 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.
Please note that as of version 0.7.0, modules are no longer delivered with the Qore library. Modules must be downloaded separately; see Qore's home page for more information.
To load a module at parse time (normally required for most modules), use the %requires
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.
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
directive.
From Qore 0.7.1, 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 exteneded to "1.0.0").
Also note that DBI drivers are loaded on demand by the Datasource and DatasourcePool classes.
At the time of writing this documentation, the following modules exist for Qore:
Table 2.2. Qore Modules
Module | Description |
---|---|
| Provides ASN.1 functionality to Qore |
| Provides |
| Provides SSH2 and SFTP functionality to Qore. |
| Provides TIBCO Rendezvous(R) (TIBCO, Inc) functionality to Qore. |
| Provides TIBCO ActiveEnterprise(TM) (TIBCO, Inc) functionality to Qore. |
| Provides Oracle (ex Bea) Tuxedo functionality to Qore. |
| Provides a MySQL DBI driver to Qore. |
| Provides a PostgreSQL DBI driver to Qore. |
| Provides a SQLite3 DBI driver to Qore. |
| Provides a Sybase DBI driver to Qore. |
| Provides a FreeTDS-based DBI driver to Qore. |
| Provides an Oracle DBI driver to Qore. |
| Provides an IBM DB2 driver to Qore. |
| Provides GLUT functionality to Qore. |
| Provides an OpenGL API to Qore. |
| BLACKLISTED: old QT4 modules: please use the much more complete qt4 module. These old modules (never officially released) use a namespace management trick that does not work with qore 0.8.0+, so they will not load with newer versions of qore. |
| Provides Nokia (formerly Trolltech) QT4 APIs for GUI development in Qore. |
| Provides curses APIs to Qore. |
| Provides YAML functionality to Qore. |
A Qore program can include other program code to be used and executed in the current program by using the %include
directive. The %include
directive must be the first text on the line, and the file name to include must follow. All text on the line after the %include
directive will be used for the file name to include. The file name should not be quoted.
Here is an example:
#!/usr/bin/qore %include /usr/qore/lib/functions.lib
After this, any variable, subroutine, namespace, constant, or object declared in the above file can be used by the Qore program.
The QORE_INCLUDE_DIR
environment variable determines the search path for include files.
Qore identifiers must start with an alphabetic character, and then may contain any number of alphabetic, numeric, or "_" characters. There is no length limit on Qore identifiers.
All Qore identifiers are case-sensitive, therefore the identifier hello_there
is not the same as Hello_There
or HELLO_THERE
.
The following are examples of valid Qore identifiers:
Table 2.3. Examples of Valid Qore Identifiers
Identifier | Description |
---|---|
| Simple one-character identifier |
| Identifier with number |
| Long identifier with underline characters |
| Identifier with underline and number |
| Mixed case identifier name |
| Identifier in all capital letters |
The following are invalid identifiers:
Table 2.4. Examples of Invalid Qore Identifiers
Identifier | Description |
---|---|
| Does not start with an alphabetic character |
| Contains "-" characters |
| Contains "#" character |
Comments are allowed in Qore scripts; line comments are preceded by a hash "#", and block comments are made C-style, ex:
# this is a line comment /* this is a block comment */
For line comments, all text following a hash until the end-of-line character "\n" is considered a part of the comment.
For block comments, all text between the /* and */ is ignored by the parser.
Here is an example Qore script containing comments:
#!/usr/bin/qore # # these are line comments # another line comment /* --- this text is in block comments print("hello"); <- this won't get executed --- because it's in the block comment */
Variables are Qore identifiers prefixed by a "$" sign, similar to Perl. The data type of variables does not have to be declared in advance, and variable types are assigned and changed automatically as appropriate in the context of the operations being performed on them or the values being assigned. Any Qore variable can hold any Qore data type including container types (lists, hashes, or objects).
A few variables are set by the Qore language during the execution of Qore programs. These are normal variables that can be reassigned to other values by the user if necessary.
Table 2.5. Special Qore Variables
Variable | Type | Data Type | Explanation |
---|---|---|---|
| Local | List | automatically assigned local variable containing the list of subroutine or method arguments that were not assigned to parameter variables (see Subroutines and Implicit Arguments for supporting related information) |
| Global | List | script command-line arguments (use the GetOpt Class to parse command-line arguments) |
| Global | List | complete qore command-line arguments |
| Global | Hash | UNIX program environment |
As of version 0.5.0, $STDERR
and $STDOUT
have been removed from Qore. Use the I/O constants stderr, stdout, and stdin constants of the File Class instead.
Variables not in a parameter list automatically have global scope unless the first reference is prefixed with my. Variable names in a parameter list are always local to their associated subroutine, method, or catch block. Global variables can be explicitly declared with our. The our keyword is required if the parse option PO_REQUIRE_OUR
(-O
or --require-our
command-line option) is set for the parent program. See the section on Parse Options for more information.
Variables may be assigned any value unless restricted with a type declaration. If no type declaration is given, then the variable is assumed to be type any. Note that type declarations are required for all variables (and for function and method parameters and class members) when the PO_REQUIRE_TYPES
parse option is set.
Note that variable types can only be declared when the my or our keywords are used; it is a syntax error to declare a variable's type without declaring its scope at the same time with one of these keywords.
Local variables are not shared between threads (local variables have a distinct value in each thread), however global variables are. See Threading (and in particular Threading and Variables) for more information.
For example (in the following script, the our keyword is optional):
#!/usr/bin/qore # # variable scoping example our int $a = 1; # this is a global variable our (string $b, any $c, hash $d); # list of global variables if ($a == 1) { my int $a = 2; my (string $b, any $c); # $a, $b, and $c are local variables, # the use of which will not affect the # global variables of the same name print("local a = %d\n", $a); } print("global a = %d\n", $a);
The first print() statement will output:
local a = 2
The second print() statement will output:
global a = 1
The following are the basic data types in Qore (see Container Data Types for container data types):
Table 2.6. Basic data types
Type | Description | Example | Default Value |
---|---|---|---|
True or |
| False | |
A sequence of characters |
| Empty string | |
A 64-bit signed integer |
| 0 | |
A double-precision floating-point number |
| 0.0 | |
A date/time value with an optional time zone component, with resolution to the microsecond. |
| 1970-01-01Z | |
An opaque binary object | n/a | an empty object of size 0 | |
Corresponds to a NULL value in a database query (not equivalent to NOTHING) |
|
| |
Represents the state of a variable having no value or function returning no value (not equivalent to NULL) |
|
|
The Boolean type can have two values, True
and False
. When converting other types to a Boolean, any value that converts to a non-zero integer will be evaluated as True
. Otherwise the result of the conversion will be False
.
String values are specified with text between double or single quotes. Text between double quotes is subject to interpretation of escape characters. Please see String Formatting for more information.
Strings are assumed by default to have the encoding given by the QORE_CHARSET
or the LANG
environment variable. If neither of these variables is set, then all strings will be assumed to have UTF-8 encoding.
For detailed information on Qore character encoding handling, please see Qore Strings and Character Encoding.
It is legal to specify a string literal with newline characters like the following:
$str = "this string is a multiline string";
Internally, strings are stored as a pointer to the string data, an unsigned integer giving the length of the string, and a pointer to an encoding object, giving the string's character encoding.
Qore floats are double precision floating-point numbers (C/C++ type double), normally a 64-bit value.
Qore dates have a time component supporting a resolution to the microsecond and can be either absolute or relative.
See Date and Time Functions for a list of functions related to date/time processing.
Absolute date/time values specify a specific point in time in a certain time zone, such as January 1, 2005 10:35:00 +01:00. They are stored interally as a 64-bit signed offset from the Qore epoch (1970-01-01Z), a positive 4-byte integer for microseconds, and a pointer to a time zone description object that provides the UTC offset and daylight savings time information (see Time Zones for more information). Note that all absolute date/time values in Qore are stored internally in UTC and are converted for display purposes to the representation of wall time in their tagged time zone.
Absolute date/time values can be specified with a syntax based on ISO-8601 date formats as follows:
YYYY-MM-DD[THH:mm:SS[.n*]][Z|[+-]HH[:mm[:SS]]]
Note that if no time zone information is given, the local time zone will be assumed. If a time zone UTC offset is given, it is given in units of time east of UTC (i.e. +05:00 means five hours east of UTC).
Or an alternative format (with a '-' instead ofa 'T' to separate the time component):
YYYY-MM-DD[-HH:mm:SS[.n*]][Z|[+-]HH[:mm[:SS]]]
for example, for just the date in UTC, without a time component:
2010-05-26
or, for just the time, without a date component (note that in this case the date component will be set to Jan 1, 1970, in order for time arithmetic to function properly and will also be tagged with the local time zone):
20:05:10.458342
Some further examples (note that the date/time values without a time zone specification here are tagged with the local time zone):
prompt%
qore -X '2005-03-29-18:12:25' 2005-03-29 18:12:25 Tue +02:00 (CEST)prompt%
qore -X '0512-01-01T01:49:59.002213Z' 0512-01-01 01:49:59.002213 Fri Z (UTC)prompt%
qore -X '2005-03-29' 2005-03-29 00:00:00 Tue +02:00 (CEST)prompt%
qore -X '18:35:26+08:00' 1970-01-01 18:35:26 Thu +08:00 (+08)
The year must be a four-digit number, and all other values except microseconds must be two-digit numbers. If microseconds are present, at least one and up to 6 digits may be given after the decimal point. Pad the numbers with leading zeros if the numbers are smaller than the required number of digits. The hour component must be in 24-hour time format. Except for the month and day values, all other values start with 0 (hour = 00 - 23, minute and second: 00 - 59). Any deviation from this format will cause a parse exception.
When a date/time value is converted to an integer or vice-versa, a 64-bit offset in seconds from the start of the "epoch" is used for the conversion. Qore's "zero date" (the start of Qore's "epoch") is January 1, 1970 UTC. When calculating second offsets from this date, a 64-bit integer is used.
The default local time zone for qore is set when the qore library is initialized; see Time Zones for more information.
Relative dates (durations) are normally used for date addition and subtraction. See Date/Time Arithmetic for more information.
Internally, durations are stored as a set of seven discrete signed integer values, one each for years, months, days, hours, minutes, seconds, and microseconds.
There are 3 different formats understood by the Qore parser for describing literal durations in Qore.
A single relative date/time value (or a duration) may be specified as follows (note that this format is specific to Qore and not based on ISO-8601):
<integer><date component specifier>
Table 2.7. Date Specifiers For Single Values For Relative Dates (non-ISO-8601 syntax)
Component | Meaning | Example | Description |
---|---|---|---|
Y | Years |
| 2 Years |
M | Months |
| 3 Months |
D | Days |
| 10 Days |
h | Hours |
| 15 hours |
m | Minutes |
| 25 minutes |
s | Seconds |
| 19 seconds |
ms | Milliseconds |
| 250 milliseconds |
us | Microseconds |
| 21194 microseconds |
This and the next duration format for composite relative date/time values are both based on ISO-8601.
This first format has the following syntax:
Pn
Yn
Mn
DTn
Hn
Mn
Sn
u
Each element above is optional, but at least one element must be present. Note that "M" means months when before the "T" and minutes when found after the "T". The other elements are years, days, hours, seconds, and, as an extension to ISO-8601, "u" for microseconds. Additionally, the values may be negative.
Here are some examples (using qore's -X command-line option to evaluate and expression and print out the result):
prompt%
qore -X 'P1Y3MT4S' <time: 1 year 3 months 4 seconds>prompt%
qore -X 'PT4M551u' <time: 4 minutes 551 microseconds>prompt%
qore -X 'P3DT21H' <time: 3 days 21 hours>
The second ISO-8601-based format for specifing complex durations with multiple time units has the following syntax:
PYYYY-MM-DDTHH:mm:SS
This format is more limited than the first format, in that all values must be positive, and furthermore, all values must be present (although they may be zero).
Here are some examples of the second format (equivalent to the first examples):
prompt%
qore -X 'P0001-03-00T00:00:04' <time: 1 year 3 months 4 seconds>prompt%
qore -X 'P0000-00-00T00:04:00.000551' <time: 4 minutes 551 microseconds>prompt%
qore -X 'P0000-00-03T21:00:00' <time: 3 days 21 hours>
The binary data type is used to hold binary arbitrary binary data. Internally it is represented by a pointer to a memory location for the data and a size indicator.
Binary data can be concatenated with the + and += operators.
This data can be manipulated by being written and read from File, Socket, and Datasource objects, or converted and parsed to/from base64 encoded strings using the makeBase64String() and parseBase64String() functions, or compressed and decompressed using the compress(), gzip(), bzip2(), etc. functions, and processed by most cryptographic funtions, among others.
Binary objects can be read from a File object using the File::readBinary() method and can be written using the File::write() method. Please see the File Class for more information.
Binary objects can be read from a Socket object using the Socket::recvBinary() method and can be written using the Socket::send() method. Please see the Socket Class for more information.
The Datasource and DatasourcePool classes can also be used to read and write Binary objects as BLOBs.
Note that this is not an exhaustive list; see the function and class library documentation for more examples.
This data type represents an SQL NULL value. Note that NULL is not equivalent to NOTHING.
This special data type represents no value.
The exists operator will return False
when given NOTHING as an argument; for example:
prompt%
qore -X 'exists NOTHING'
False
Boolean, string, integer, date, and floating point data types can be freely converted from one type to the other, although data loss is possible depending on the conversion (particularly when converting to the boolan type as only two possible values are supported).
The special types NULL and NOTHING are not equivalent and cannot be converted to or from any other type.
When date types are converted from strings, any of the following formats can be used: "YYYYMMDDHHmmSS[.us][Z|+-HH[:MM[:SS]]]", "YYYY-MM-DD HH:mm:SS.us", "YYYY-MM-DDTHH:mm:SS", "YYYY-MM-DDTHH:mm:SS[.us][Z|+-HH[:MM[:SS]]]"
, and most reasonable combinations thereof. If the time zone component is missing, then the local time zone will be assumed (see Time Zones).
When dates are converted to and from integer values, the a 64-bit second offset from January 1, 1970 in the local time zone is used for the conversion. For example int(2006-01-01)
gives 1136073600
(regardless of the local time zone the date is in). To get the second offset of a date from 1970-01-01Z (i.e. the true epoch offset), call get_epoch_seconds() instead.
When an expression requires a certain data type and the source data type cannot be converted to the desired data type, the default value for the desired data type will be used. The default values are given here.
Qore supports three types of container types: lists, hashes (associative arrays), and objects (see Objects and Classes for more information). These container types can be combined to make arbitrarily complex data structures.
The data type of any element can be any basic type or another aggregate type. The types do not have to be uniform in one container structure.
Lists (or arrays) are simply ordered containers of values. A list element can be any Qore type (even another list, hash, or object).
Lists are specified by giving expressions separated by commas as follows:
$list = (expression
,expression
[,expression
...]);
Here is a concrete example:
my list $list = (1, 2, "three", 4.0, 5, 6, 2001-01-15Z);
Note that trailing commas can be left on the end of a list (or a hash, for that matter). This makes it easier to comment-out the last element of a multi-line list without having to worry about removing the trailing comma.
List elements are dereferenced using square brackets: "[" and "]". The first element in a list has index zero.
$element3 = $list[2];
The following operators perform special processing on lists: elements, shift, unshift, push, pop, splice, [], +, +=, map, foldl, foldr, and select.
Hashes are containers that associate values to a string key.
Note that Qore hashes preserve the insertion order in order to be able to guarantee the order of keys when hashes are serialized to XML strings (see XML Integration), therefore the keys operator will always return the hash keys in insertion/creation order.
Hashes are specified using the following syntax:
$hash = ( "key1" :expression
, "key2" :expression
, ... );
Here is a concrete example:
my hash $hash = ( "apple" : 1 + 1,
"pear" : "good" );
Hashes are dereferenced in one of two ways, either using curly brackets: "{" and "}", where any valid Qore expression can be used, or using the dot "." hash member dereferencing operator, where literal strings can be used.
$element3 = $hash{"pe" + "ar"};
Is equivalent to:
$element3 = $hash.pear;
and:
$element3 = $hash."pear";
and:
$element3 = $hash.("pe" + "ar");
Hash members can have the names of keywords, but in this case to dereference them, you cannot use the dot operator with a literal string, otherwise a parse error will be raised. Use quotes around the member name when dereferencing hash members with the same name as a qore keyword as follows:
$element3 = $hash."keys";
$element3 = $hash{"keys"};
A literal string after the dot "." hash member dereferencing operator must be a valid Qore identifier; therefore if you want to use a hash key that's not a valid identifier, enclose the string in quotes.
If you want to use the result of an expression to dereference the hash, then the curly bracket syntax must be used.
Note that hash keys can also be given by constants (as long as the constant resolves to a string) when using curly brackets.
Qore objects are instantiations of a class. They have members (like a hash - values associated to string keys), and methods. The class definition specifies the methods that run on objects of that class, private members, and static methods associated with the class (however note that static methods do not run in the scope of an object). Qore classes are declared with a special syntax.
The recommend way to instantiate an object is to declare its type and give constructor arguments after the variable name in parentheses as follows:
myclass_name_or_path $var_name
([argument list
])
For example (for a constructor taking no arguments or having only default values for the aguments, the list is empty):
my Mutex $m();
Objects can also be instantiated using the new operator as follows.
newclass_identifier
([argument list
])
For example:
my $m = new Mutex();
Objects have named data members that are referenced like hash elements, although this behavior can be modified for objects using the memberGate()
method. Object members are accessed by appending a dot '.' and the member name to the object reference as follows:
object_reference.member_name
For more information, see Object Members.
Object methods are called by appending a dot '.' and a method name to the object reference as follows:
object_reference
.method_name
([argument_list
])
Or, from within the class code itself to call another method from inside the same class hierarchy:
$.method_name
([argument_list
])
For more information, see Object Method Calls.
The object references above are normally variable references holding an object, but could be any expression that returns an object, such as a new expression or even a subroutine call.
Objects are treated differently than other Qore data types; they are only explicitly copied (see Object References for more informaion). Any object instantiated with the new operator will remain unique until deleted or explicitly copied. An explicit copy is made with the copy method, and does not always guarantee an exact copy of the source object (it depends on the definition of the copy method for the class in question).
Objects exist until they go out of scope, are explicitly deleted, or their last thread exits. For detailed information, see the section Classes on Qore classes.
Starting in Qore 0.8.0, it is possible to restrict variables, class members, and function and method parameters to certain data types. This allows programmers to write safer code, as many more errors can be caught at parse time that would otherwise be caught at run time. Furthermore, providing type information to the parser allows Qore to implement performance optimizations by performing lookups and resolutions once at parse time rather than every time a variable or class member is accessed at run time.
When types are declared in a parameter list, functions and methods can be overloaded as well.
The types in the following table can be used:
Table 2.8. Data Type Declaration Names
Name | Accepts Qore Type(s) | Returns Qore Type(s) | Description |
---|---|---|---|
| Restricts values to Qore's Integer type. | ||
| Restricts values to Qore's Float type. | ||
| Restricts values to Qore's Boolean type. | ||
| Restricts values to Qore's String type. | ||
| Restricts values to Qore's Date type; values may be either absolute or relative date/time values. | ||
| Restricts values to Qore's Binary type. | ||
| Restricts values to Qore's Hash type. | ||
| Restricts values to Qore's List type. | ||
| Restricts values to Qore's Object type. | ||
| Restricts values to objects of the specific class given; either the class name can be given (ex: | ||
| Restricts values to Qore's NULL type; this type has few (if any) practical applications and has been included for completeness' sake. | ||
| Restricts values to Qore's NOTHING type; this type is mostly useful for declaring that a function or method returns no value. | ||
| Accepts Integer, Float, Boolean, String and converts non-integer values to an integer and returns the integer. | ||
| Accepts Integer, Float, Boolean, String and converts non-float values to a float and returns the new value. | ||
| Accepts Integer, Float, Boolean, String and converts non-boolean values to a boolean and returns the new value. | ||
| Accepts Integer, Float, Boolean, String and converts non-string values to a string and returns the new value. | ||
| any | same as received | Provides no restrictions on the type of value it receives and returns the same value. |
| same as received | Restricts input to String and Binary and returns the same type. | |
| same as received | Restricts values to closures and call references. | |
| reference to an lvalue | same as received | Restricts values to references to lvalues; currently only usable in function or method parameters. |
| same as received | Does not restrict value to just closures, but rather also allows call references. Synonym for | |
| same as received | Does not restrict value to just call references, but rather also allows closures. Synonym for |
Complex types (hash of lists, reference to string, etc) are currently not possible to declare.
Functions and methods can be overloaded if parameter types are declared as in the following example:
sub example(int $i) returns int { printf("i=%d\n", $i); return $i + 1; } sub example(string $str) returns string { printf("str=%s\n", $str); return $str + "foo"; }
In this case, the first version (example(int)
) will be executed if called with an integer argument, and the second (example(string)
) if called with a string argument.
Class methods may also be overloaded, but note that destructor()
, copy()
, methodGate()
, memberGate()
, and memberNotification()
methods may not be overloaded (see Classes for more information).
Qore assumes a default time zone for all programs when it starts up. The rules for determining the default time zone are similar to those for the C library in most UNIX or UNIX-like operating systems.
If the TZ environment variable is defined, then the contents of that variable are used to find a zoneinfo file that contains the time zone definition. If this file cannot be found, then the default time zone will default to UTC.
If the TZ environment variable is not defined or is empty, then the Qore library tries to find the default zoneinfo definition file (normally /etc/localtime). If found, this file is read in and provides the information about the local time zone. If not found, the default time zone will default to UTC.
When a zoneinfo file is found, information about local time zone names and daylight savings time is available for times tagged with that time zone.
See the TimeZone class for information about retrieving, setting, and querying time zone information; see Date and Time Functions for a list of functions related to date/time processing.
Here are some examples using Qore's '-X' option for evaluating an expression and displaying the result immediately:
prompt%
TZ=America/Chicago qore -X 'now_us()' 2010-05-11 06:14:28.845857 Tue -05:00 (CDT)prompt%
TZ=Europe/Rome qore -X 'now_us()' 2010-05-11 13:14:35.070568 Tue +02:00 (CEST)prompt%
TZ=Australia/Sydney qore -X 'now_us()' 2010-05-11 21:14:45.422222 Tue +10:00 (EST)prompt%
TZ=Asia/Tokyo qore -X 'now_us()' 2010-05-11 20:14:59.609249 Tue +09:00 (CJT)
Note that posix-style time zone rules are not understood if assigned to the TZ environment variable, only file names to a zoneinfo file can be processed at the moment. Furthermore if the zoneinfo file contains leap second information, it is currently ignored.
The Qore language is character-encoding aware. All strings are assumed to have the default character encoding, unless the program explicitly specified another encoding for certain objects and operations. Every Qore string has a character encoding ID attached to it, so, when another encoding is required, the Qore language will attempt to do an encoding translation.
Qore uses the operating system's iconv library functions to perform any encoding conversions.
Qore supports character encodings that are backwards compatible with 7-bit ASCII. This includes all ISO-8859-*
character encodings, UTF-8
, KOIR-8
, KOIU-8
, and KOI7
, among others (see the table below: Character Encodings Known to Qore).
However, mutibyte character encodings are currently only properly supported for UTF-8
. For UTF-8
strings, the length(), index(), rindex(), substr(), reverse(), the splice operator, print formatting (regarding field lengths) functions and methods taking format strings, and regular expression operators and functions, all work with character offsets, which may be different than byte offsets. For all character encodings other than UTF-8
, a 1 byte=1 character relationship is assumed.
Qore will accept any encoding name given to it, even if it is not a known encoding name or alias. In this case, Qore will tag the strings with this encoding, and pass this user-defined encoding name to the iconv library when encodings must be converted. This allows programmers to use encodings known by the system's iconv library, but unknown to qore. In this case, Qore will assume that the strings are backwards compatible with ASCII
, meanin that that one character is represented by one byte and that the strings are null-terminated.
Note that when Qore matches an encoding name to a code or alias in the following table, the comparison is not case-sensitive.
Table 2.9. Character Encodings Known to Qore
Code | Aliases | Description |
---|---|---|
| latin-1, Western European character set | |
| latin-2, Central European character set | |
| latin-3, Southern European character set | |
| latin-4, Northern European character set | |
| Cyrillic character set | |
| Arabic character set | |
| Greek character set | |
| Hebrew character set | |
| latin-5, Turkish character set | |
| latin-6, Nordic character set | |
| Thai character set | |
| latin-7, Baltic rim character set | |
| latin-8, Celtic character set | |
| latin-9, Western European with euro symbol | |
| latin-10, Southeast European character set | |
n/a | Russian: Kod Obmena Informatsiey, 7 bit characters | |
| Russian: Kod Obmena Informatsiey, 8 bit | |
| Ukrainian: Kod Obmena Informatsiey, 8 bit | |
| 7-bit ASCII character set | |
| variable-width universal character set |
The default character encoding for Qore is determined by environment variables.
First, the QORE_CHARSET
environment variable is checked. If it is set, then this character encoding will be the default character encoding for the process. If not, then the LANG
environment variable is checked. If a character encoding is specified in the LANG
environment variable, then it will be used as the default character encoding. Otherwise, if no character encoding can be derived from the environment, UTF-8
is assumed.
Character encodings are automatically converted by the Qore language when necessary. Encoding conversion errors will cause a Qore exception to be thrown. The character encoding conversions supported by Qore depend on the Operating System's iconv library function.
The following is a non-exhaustive list of examples in Qore where character encoding processing is performed.
Character encodings can be explicitly performed with the convert_encoding() function, and the encoding attached to a string can be checked with the get_encoding() function. If you have a string with incorrect encoding and want to change the encoding tag of the string (without changing the actual bytes of the string), use the force_encoding() function.
The Datasource and DatasourcePool classes will translate character encodings to the encoding required by the database if necessary as well (this is actually the responsibility of the DBI driver for the database in question).
The File and Socket classes translate character encodings to the encoding specified for the object if necessary, as well as tagging strings received or read with the object's encoding.
The HTTPClient, XmlRpcClient, and JsonRpcClient classes will translate character encodings to the encoding specified for the object if necessary, as well as tag strings received with the object's encoding. Additionally, if an HTTP server response specifies a specific encoding to use, the encoding will be automatically set to this encoding as well.
Additionally you can serialize a Qore hash to an XML string and specify the character encoding to use. If the target encoding is different than the source encoding conversions are automatically performed. See XML Integration for more information about XML handling.
An expression can be any of the following (note that expressions are also recursively defined):
Table 2.10. Expressions
Type | Description |
Examples | |
---|---|---|---|
An immediate value | Qore values that can be expressed directly (see Basic Data Types for more information) |
True 152 1.2 "a string" 2005-10-27 NULL NOTHING ("key" : $val) 1, 2.0, "three" | |
A variable reference | Qore variables (see Variables for more information) | $var | |
A variable declaration | Qore variable declarations (see Variables for more information) | my int $var | |
An in-class object member reference | References to members of an object from within the class (see Object Members for more information) | $.member | |
An lvalue assignment | Assigns a value to a lvalue (see Assignment Operator for more information) |
$var = 1 ($a, $b, $c, $date) = (1, "two", 3.3, 2005-10-28) | |
A subroutine/function call | Qore subroutine calls (see Subroutines for more information) | calculate($var1, $var2, "string", 4) | |
A method call | Qore object method calls (see Object_Method_Calls for more information) | $object.method("argument") | |
An in-class method call | Qore in-class object method calls (see Object_Method_Calls for more information) | $.method("argument") | |
Qore static method calls (see Static Methods for more information) | ClassName::static_method("argument") | ||
Expressions with operators | Use of Qore operators (see Operators for more information) |
1 + 2
$a || $b
background my_function()
| |
An expression in parentheses | Use of parentheses for clarity or to specify evaluation precedence. |
(1 + 2) (2 * (3 + 1)) | |
A list | a list of values (see Lists for more information) | 1, 2, 3, "four", 5.0 | |
A hash | a hash (associative/keyed array) value container (see Hashes for more information) | ( "key1" : 1, "key2" : "two" ) | |
Finds a value or values in a hash of lists, such as returned by the Datasource::select() method (see find expressions for more information) |
find %name, %id in $data where (%name =~ /Smith/); | ||
A context identifier ( | A contextual reference to the value of a key of a complex data structure within the current row being iterated by a context, summarize, subcontext statement, or a find expression. | %name | |
A context row identifier ( | A contextual reference to the current row of complex data structure being iterated by a context, summarize, subcontext statement, or a find expression. This expression will return a hash of the current row. | %% | |
A reference to a function or object method call (similar to a function pointer in C or C++). Function references are resolved in the second phase of parsing (commit phase), and object method references are resolved at run-time. | \function_call() \$object_expression.method_name() | ||
A closure | An anonymous function used a value; technically in computer science a closure must have at least one bound variable, but in qore a closure is any function used as a value, whether or not it encloses local variables from the scope in which it was created or not. | sub (string $a) returns string { return $a + $b; } | |
A call reference call | Calls the code referenced by the call reference expression or closure using any arguments supplied and returns the result. | $result = $call_reference($arg1, $arg2) | |
References an implicit argument. | $1, $2 $$ |
Calls to static class methods are made by giving the class name followed by two colons and then the method name. The method name must be implemented and accessible (i.e. not private and accessed outside the class) somewhere within the class hierarchy and must be static or a parse exception will occur.
class_name
::method_name
([argument_expressions...]
)
class_name
The name of the class implementing the static method.
method_name
The name of the static method to call.
[argument_expressions...]
Expressions passing arguments to the static method.
TimeZone::setRegion("Europe/Prague");
The find expression can be used to quickly find data in a hash of lists (such as a query result set returned by the Datasource::select() method). The find expression will loop through a data structure, and for each element in the structure where the where expression
is True
, it will evaluate and return a result expression. If the where expression
only is true for one element in the list, it will return the result of evaluating the result expression
directly, otherwise if the where expression
is true more than once, then a list of the results of evaluting the result expression
for each element is returned. In each expression in the find expression, column names can be referred to by preceding the name with a '%" character (as with context statements).
findresult_expression
indata_expression
where (where_expression
)
result_expression
This expression will be evaluated and returned when the where_expression
evaluates to True
.
data_expression
This expression must evaluate to a hash of lists, so that the internal context can be set up for the find loop.
where_expression
This expression will be evaluated for each row in the data_expression
. Each time it evaluates to True
, the result_expression
will be evaulated and used for the return value for the find expression.
$rlist = find %name, %id in $data where (%name =~ /Smith/);
References to functions or object methods are called call references. A call reference can be used like a function pointer; a call reference is a Qore data type that can be returned by functions or methods or assigned to variables.
Note that it is currently not legal to assign a call reference to a constant. This restriction may be lifted in a future version of Qore.
Function Call References
Call references to functions are resolved at parse time; if the function does not exist a parse exception will be thrown.
Object Method Call References
Call references to object methods are executed and resolved at run time; if the object expression does not evaluate to an object at run-time, an OBJECT-METHOD-REFERENCE-ERROR
exception will be thrown. If the method does not exist, a METHOD-DOES-NOT-EXIST
run-time exception will be thrown.
When called, a call reference to an object method will be executed in the context of the object originally referenced.
Object method call references do not prolong the lifetime of an object; if the object is deleted (for example, by going out of scope), then if called the call reference will cause a OBJECT-ALREADY-DELETED
exception to be thrown.
\function_name
(); \object_expression.method_name
();
\function_name
()
This form gives a function call references. The function name can be any valid user or builtin function name. Note the backslash at the beginning and the empty pair of parentheses at the end; these are required when specifying a call reference.
\object_expression.method_name
()
This form gives an object method call reference. The object expression can be any valid Qore expression that evaluates to an object. The method_name must be an unquoted string (see examples below) and must represent a valid method name of the object's class.
$call_ref = \func_name(); $call_ref = \$object.method_name();
A closure is an anonymous function used as a value. Closures can be returned from functions or methods, assigned to variables, or passed as arguments to other functions.
Note that it is not legal to assign a closure to a constant.
sub ([[type] variable1, ...
]) [returnstype
] {code...
}
Closures encapsulate the state and value of local variables of the outer code block referenced from within the closure when the closure is created. Whenever local variables are bound within a closure, these variables are subject to concurrent thread access protection (locking) just as with global variables, in order to allow closures to be used in any context without restriction and to preseve thread-safety regarding bound local variables.
Note that returning a closure from within an object method encapsulates the state of the object as well (it's legal to refer to $self and $.<variable> from within closures created from objects) and additionally prolongs the scope of the object for the lifetime of the closure.
Note that parameter and return types are required when the PO_REQUIRE_TYPES
or PO_REQUIRE_PROTOTYPES
parse options are set.
# if $b is a local variable in the function where the closure is created # then $b will be bound to the closure when the closure is created my code $closure = sub (int $a) returns int { return $a + $b; };
Implicit arguments are arguments not captured by parameter variables as well as automatic arguments in list-processing operator expressions. A special syntax to reference these arguments is documented here.
$<integer>
# for a single implicit argument
$$ # for the entire implicit argument list
Implicit arguments can be directly referenced using the dollar sign ($) and either a number from 1 onwards (giving the position in the argument list, where 1 is the first element) or a double dollar sign ($$) giving the entire implicit argument list.
For unassigned arguments to functions or methods, this syntax supplements the automatic $argv
variable holding all function arguments not assigned to parameter variables.
This syntax is particularly useful when writing expressions for the map, map, foldr, and select operators, where implicit argument references are the only way the operator expressions can reference the current list values that are populated as implicit arguments as the operators traverse the list.
# extract a list of even numbers from a list my $l = select $list, !($1 % 2);
The following table lists all Qore operators in order of precedence, starting with the highest precedence. The lower the precedence number, the higher the precedence, therefore the operators with precedence level 1 ("{}", "[]", ".") have the highest precedence of all Qore operators. The precedence levels in Qore are roughly equal to the precedence levels of C language operators. To explicitly specify the precedence for expression evaluation, use parentheses ().
Table 2.11. Operators
Operator | Prec. | Description | Example |
---|---|---|---|
`` | 1 |
| |
{} | 1 | hash element or object member expression dereference operator |
|
. | 1 |
| |
[] | 1 |
| |
++ | 2 |
| |
-- | 2 |
| |
new | 3 |
| |
background | 3 |
| |
delete | 3 |
| |
remove | 3 |
| |
cast<>() | 3 |
| |
! | 4 |
| |
~ | 5 |
| |
- (unary minus) | 6 |
| |
shift | 7 |
| |
pop | 7 |
| |
chomp | 7 |
| |
trim | 7 |
| |
elements | 8 |
| |
keys | 8 |
| |
* | 9 |
| |
/ | 9 |
| |
% | 10 |
| |
+ | 11 | plus operator: string, binary, list, and hash concatenation, integer and float addition |
|
- | 11 |
| |
>> | 12 |
| |
<< | 12 |
| |
exists | 13 |
| |
instanceof | 13 |
| |
< | 14 |
| |
> | 14 |
| |
== | 14 |
| |
!= | 14 |
| |
<= | 14 |
| |
>= | 14 |
| |
<=> | 14 |
| |
=== | 14 |
| |
!== | 14 |
| |
=~ // | 14 |
| |
!~ // | 14 |
| |
=~ s/// | 14 |
| |
=~ x// | 14 |
| |
=~ tr | 14 |
| |
& | 15 |
| |
| | 15 |
| |
^ | 15 |
| |
&& | 16 |
| |
|| | 16 |
| |
? : | 17 |
| |
, | 18 |
| |
unshift | 19 |
| |
push | 19 |
| |
splice | 19 |
| |
extract | 19 |
| |
map | 19 |
| |
foldl | 19 |
| |
foldr | 19 |
| |
select | 19 |
| |
= | 20 |
| |
+= | 21 |
| |
-= | 21 |
| |
&= | 21 |
| |
|= | 21 |
| |
%= | 21 |
| |
*= | 21 |
| |
/= | 21 |
| |
^= | 21 |
| |
<<= | 21 |
| |
>>= | 21 |
|
All Qore operators perform thread-atomic actions with respect to the immediate arguments of the operator. If the operators are used in a complex expression, the entire expression is not thread-atomic unless explicit user-level locking is used. For example: $a += 5
is a thread-atomic action, but $a += $b--
is not atomic, but rather made up of two atomic actions.
When an operator taking more than one argument is used with arguments of different data types, Qore automatically converts one or both data types to a data type supported by the operator in order to evaluate the result, according to the precedence lists in the following section. That is; when an operator operates on mixed types, the types listed first in the following sections have precedence over types listed farther down in the lists. The result type will always be equal to the final operation type after any conversions due to type precedence per operator. If no type of either argument matches a supported data type for the operator, both types will be converted to the highest precedence data type for the operator and then the operator will evaluate the result. For explicit type conversion, please see the boolean(), string(), date(), int(), float(), etc functions.
Executes the shell command in a separate process and returns the stdout as a string. To perform the same action using a Qore expression, see the backquote() function.
`shell_command`
$dirlisting = `ls -l`
Table 2.13. Exceptions Thrown by ``
err | desc |
---|---|
| An error occurred in fork() or creating the output pipe. |
Retrieves the value of hash key or object member by evaulating an expression.
container_expression{expression}
printf("%s\n", $hash{getName()});
Table 2.14. Arguments Processed by {}
Argument | Processing |
---|---|
This expression must evaluate to a hash or an object. If not, then the operator returns no value. | |
list | If the expression evaluates to a list, then a slice of the hash or object is returned as a hash containing keys given in the list that are present in the hash or object. If the key as given in the list (converted to a string if necessary) is not present in the hash or object, then it is also not present in the hash returned. |
| This expression is evaluated and converted to a string if necessary. The value of the hash key corresponding to this string will be returned. If the key or member does not exist, then no value is returned. |
Table 2.15. Exceptions Thrown by {}
err | desc |
---|---|
| Attempt to access a private member outside the class. |
Retrieves the value of a hash key or object member using a literal identifier or an expression.
container_expression.identifier
container_expression.method_identifier([arguments...])
container_expression.expression
printf("%s\n", $hash.name);
$obj.method("argument");
Table 2.16. Arguments Processed by .
Argument | Processing |
---|---|
| This expression must evaluate to a hash or an object. If not, then the operator returns no value. |
| The value of the hash key or object member corresponding to this identifier will be returned. If no such key exists, then no value is returned. In order to use hash keys that are not valid Qore identifiers, please use the {} operator. If the member is a private member and access is made outside the class, a run-time exception will be thrown. |
| The container expression must evaluate to an object, or a run-time exception is thrown. If the method does not exist in the class a run-time exception is thrown. Otherwise the method is called with any optional arguments given. |
| If the expression evaluates to a list, then a slice of the hash or object is returned as a hash containing keys given in the list that are present in the hash or object. If the key as given in the list (converted to a string if necessary) is not present in the hash or object, then it is also not present in the hash returned. |
| This expression is evaluated and converted to a string if necessary. The value of the hash key corresponding to this string will be returned. If the key or member does not exist, then no value is returned. |
Table 2.17. Exceptions Thrown by .
err | desc |
---|---|
| Attempt to access a private member outside the class. |
| Attempt to access a method not defined for this class. |
| Attempt to access a private method from outside the class. |
| Attempt to access a method of a privately-inherited base class from outside the class. |
| Attempt to execute a method on a non-object. |
Retrieves the value of a list element, the given character of a string, or the integer value of a byte for a binary object. If the index value is not valid for the argument, NOTHING is returned. Note that this operator only works as a list dereferencing operator in lvalue expressions; you cannot assign a character or a byte value to strings or binaries using this operator.
list_expression[expression]
string_expression[expression]
binary_expression[expression]
printf("%s\n", $list[2]); printf("%s\n", $str[2]); printf("0x%x\n", $binary[2]);
Table 2.18. Arguments Processed By []
Argument | Processing |
---|---|
| If the expression evaluates to a list, then the offset_expression will be used to return the given element from the list. |
| If the expression evaluates to a string, then the offset_expression will be used to return the given character from the list; note that multi-byte characters with UTF-8 are properly respected with this operator. |
| If the expression evaluates to a binary, then the offset_expression will be used to return the integer value of the byte given from the binary object. |
| The expression is evaluated and converted to an integer if necessary. Then the value of the list element given is returned (elements start at position 0). |
This operator does not throw any exceptions; if the first expression does not evaluate to either a list, string, or binary, then no value is returned.
increments an lvalue and returns the incremented value.
++lvalue
++$i;
Table 2.19. Arguments Processed By Pre-Increment ++
Argument | Processing |
---|---|
Integer | First converts the value of |
This operator does not throw any exceptions.
increments an lvalue and returns the value before the increment.
lvalue++
$i++;
Table 2.20. Arguments Processed By Post-Increment ++
Argument | Processing |
---|---|
Integer | First converts the value of |
This operator does not throw any exceptions.
decrements an lvalue and returns the decremented value.
--lvalue
--$i;
Table 2.21. Arguments Processed By Pre-Decrement --
Argument | Processing |
---|---|
Integer | First converts the value of |
This operator does not throw any exceptions.
decrements an lvalue and returns the value before the decrement.
lvalue--
$i--;
Table 2.22. Arguments Processed By Post-Decrement --
Argument | Processing |
---|---|
Integer | First converts the value of |
This operator does not throw any exceptions.
Creates an instance of a class by running the class' constructor on the new class (if any exists) and returns the new object.
Note that it is normally better to declare an object with its type and use the abbreviated form to construct the object as follows:
my Mutex $m();
This provides type information to the parser which allows more errors to be caught at parse time (instead of at run time), and furthermore allows Qore improve performance by performing more work once at parse time rather than for every time the object is accessed at run time (for example, method and variant resolution).
new class_identifier(constructor_arguments ...)
specific class, an object of the class given
$obj = new Qore::Mutex();
Table 2.23. Arguments Processed By new
Argument | Processing |
---|---|
| The class_identifier must be an existing class name; if so, the operator instantiates an object of this class, executes the constructor for the class (if any exists, along with any base class constructors, if applicable) on the new object, and returns the object (for constructor execution order in an inherited class, see Class Inheritance). If an exception is thrown in the constructor, the object is deleted immediately. |
Table 2.24. Exceptions Thrown by new
err | desc |
---|---|
depends on class/constructor | See class documentation for possible exceptions. |
Start a background thread and return the TID (thread ID).
background expression
background startThread();
Table 2.25. Arguments Processed By background
Argument | Processing |
---|---|
string |
The expression given as an argument will be executed in a new thread. The TID of the new thread will be returned as the return value of the operator. |
Please note the following when using the background operator:
expressions that have no effect cannot be used with the background operator (a parse exception will be thrown)
it is illegal to make changes to a local variable anywhere in a background expression (a parse exception will be thrown)
local variables and find expressions are evaluated before the new thread is started and the result of the evaluation is used in the expression in the new thread.
it is not possible to pass local variables by reference anywhere in a background expression (a parse exception will be thrown)
Table 2.26. Exceptions Thrown by background
err | desc |
---|---|
| If the thread table is full or if the operating system returns an error while starting the thread, this exception is thrown. |
The delete operator deletes the contents of an lvalue. If the delete operator is called on an object, the object will be destroyed unconditionally. The delete operator does not return any value. When called on a hash key, the key is removed from the hash entirely; when called on a list, the element is assigned NOTHING.
In the case the delete operator operates on an object, any exception can be thrown that is thrown by the class' destructor.
For a similar operator that returns the value that is removed from the data structure, and does not delete objects, see the remove operator.
delete lvalue_expression
Does not return any value
delete $value;
This operator does not throw any exceptions, however exceptions could be thrown in an object's destructor method when deleted by this operator.
The remove operator removes a value from a data structure, or, in the case the operand of the remove operator is a simple value, the value itself is removed from the variable and returned. The remove operator returns the value removed from the lvalue. When called on a hash key, the key is removed from the hash entirely; when called on a list, the element is assigned NOTHING.
The remove operator does not call destructors when operating on objects, but if removing an object from an lvalue or from a data structure within the lvalue causes the object to go out of scope, it will be destroyed, and then its destructor could throw an exception.
For a similar operator that deletes the value that is removed from the data structure, see the delete operator.
remove lvalue_expression
my $var = remove $hash.value;
This operator does not throw any exceptions, however exception could be thrown in an object's destructor if it goes out of scope due to the action of this operator.
The cast<>() operator provides a way to tell the parser that the type of object is not actually the declared type but rather a subclass as given between the angle brackets.
cast<class_name_or_path
>(expression
)
specific class, the class given
cast<SubClass>($obj).method();
Table 2.27. Arguments Processed By cast<>()
Argument | Processing |
---|---|
| The object is treated as if it were the class given between the angle brackets; this is mostly useful at parse time to avoid |
Table 2.28. Exceptions Thrown by cast<>()
err | desc |
---|---|
| The expression given does not evaluate to an object that can be cast to the given class. |
Reverses the logical sense of an expression (True
becomes False
and False
becomes True
).
!expression
if (!exists $error_code) do_something();
Table 2.29. Arguments Processed By !
Argument | Processing |
---|---|
| The expression is evaluated and converted to Boolean, if necessary. Then the value is logically reversed ( |
This operator does not throw any exceptions.
The value of each bit in an integer is reversed (0 becomes 1, 1 becomes 0).
~expression
$a = ~$b;
Table 2.30. Arguments Processed By ~
Argument | Processing |
---|---|
| The argument is converted to an integer (if necessary), and bitwise negation is performed on the argument (ex: 666 & ~27 = 640) |
This operator does not throw any exceptions.
Removes the first element from a list and returns that element.
shift lvalue
$a = shift $ARGV;
Table 2.32. Arguments Processed By shift
Argument | Processing |
---|---|
list | Returns the first element of the list, and the list is modified by having the first element removed from the list. |
This operator does not throw any exceptions.
Removes the last element from a list and returns that element.
pop lvalue
$a = pop $list;
Table 2.33. Arguments Processed By pop
Argument | Processing |
---|---|
list | Returns the last element of the list, and the list is modified, having the last element removed from the list. |
This operator does not throw any exceptions.
Removes the end-of-line marker(s) ('\n' or '\r\n') from a string, or each string element in a list, or each hash key value in a hash (if the value is a string) and returns the number of characters removed.
To perform this operation on a non-lvalue expression, see the chomp() function.
chomp lvalue
chomp $str;
Table 2.34. Arguments Processed By chomp
Argument | Processing |
---|---|
string | Removes any EOL characters from a string and returns the number of characters removed. |
list | Removes any EOL characters from each string element of the list passed and returns the number of characters removed. |
hash | Removes any EOL characters from each hash key's value (where the value is a string) and returns the number of characters removed. |
This operator does not throw any exceptions.
Removes whitespace characters from the beginning and end of a string, or each string element in a list, or each hash key value in a hash (if the value is a string) and returns the value processed (string, list, or hash).
To perform this operation on a non-lvalue expression, see the trim() function.
The following whitespace characters are removed from the beginning and end of strings: ' ', '\n', '\r', '\t', '\v' (vertical tab, ASCII 11), and '\0' (null character).
trim lvalue
trim $str;
Table 2.35. Arguments Processed By trim
Argument | Processing |
---|---|
string | Removes whitespace characters from the beginning and end of a string and returns the value processed. |
list | Removes whitespace characters from the beginning and end of each string element of the list passed and returns the list. |
hash | Removes whitespace characters from the beginning and end of each string value of the hash passed and returns the hash. |
This operator does not throw any exceptions.
Executes (or maps) an expression on a list and returns the result. An optional select expression can be given to filter elements out from the result list.
If the second argument is not a list, then map_expression
is executed on the single value and the result is returned, and any select expression is ignored.
map map_expression, list, [select_expression]
# returns (2, 4, 6)
map $1 * 2, (1, 2, 3);
Table 2.36. Arguments Processed By map
Argument | Processing |
---|---|
| The expression to map on the list; the implicit argument $1 represents the current element being processed. |
list | The list to process. |
| An optional expression than can be used to filter out elements of the list before the map expression is applied; if this expression evaluates to |
This operator does not throw any exceptions (however note that exceptions could be thrown by expressions executed by this operator).
Folds an operation on a list from left to right and returns the result. The result of each individual operation is used as the first argument in the foldl expression for the next element in the list. The first operation of the fold is made by executing the fold expression on the first and second elements of the list, from this point onwards, the result of each successive operation is used as the first argument for the next operation, the second argument being the next element in the list.
If the list expression does not evaluate to a list, then the evaluated argument is returned immediately with no processing by the fold expression.
foldl expression, list
# returns 5
foldl $1 - $2, (10, 4, 1);
Table 2.37. Arguments Processed By foldl
Argument | Processing |
---|---|
| The expression to fold on the list; the implicit argument $1 represents the result of the last operation (or the first element in the list when beginning the fold), and $2 represents the next element of the list. |
list | The list to process. |
This operator does not throw any exceptions (however note that exceptions could be thrown by expressions executed by this operator).
Folds an operation on a list from right to left and returns the result. The result of each individual operation is used as the first argument in the foldr expression for the next element in the list in reverse order. The first operation of the right fold is made by executing the fold expression on the last and penultimate elements of the list, from this point onwards, the result of each successive operation is used as the first argument for the next operation, the second argument being the next element in the list in reverse order.
If the list expression does not evaluate to a list, then the evaluated argument is returned immediately with no processing by the fold expression.
foldr expression, list
# returns -13
foldr $1 - $2, (10, 4, 1);
Table 2.38. Arguments Processed By foldr
Argument | Processing |
---|---|
| The expression to fold on the list; the implicit argument $1 represents the result of the last operation (or the last element in the list when beginning the fold), and $2 represents the next element of the list in reverse order. |
list | The list to process. |
This operator does not throw any exceptions (however note that exceptions could be thrown by expressions executed by this operator).
Selects elements from a list that meet the given criteria and returns the new list.
If the list expression does not evaluate to a list, then the select expression is evaluated using the value of the list expression as an argument, if it evalutes to true, then the value is returned, otherwise, no value is returned.
select list, expression
# returns (2, 4, 6)
select (1, 2, 3, 4, 5, 6), !($1 % 2);
Table 2.39. Arguments Processed By select
Argument | Processing |
---|---|
list | The list to process. |
| The expression will be evaluated on each element of the list, the implicit argument $1 represents current element of the list; only if the expression evaluates to |
This operator does not throw any exceptions (however note that exceptions could be thrown by the expression executed by this operator).
Returns the number of elements in a list, the number of keys in a hash, the number of characters (not bytes) in a string, or the number of bytes in a binary object.
elements expression
$size = elements $list;
This operator does not throw any exceptions.
Table 2.41. Arguments Processed By keys
Argument | Processing |
---|---|
| Returns a list of strings giving the keys in |
This operator does not throw any exceptions.
This operator does not throw any exceptions.
This operator does not throw any exceptions.
Gives the integer remainder after division of one number by another.
expression1
%expression2
$mod = $x % $y;
Table 2.44. Arguments Processed By %
Argument | Processing |
---|---|
Gives |
This operator does not throw any exceptions.
Numeric addition, list, string, binary, and hash concatenation operator.
expression1
+expression2
$a = 1 + 2;
$string = "hello" + "-there";
$list = (1, 2) + ("three", "four", "five");
$hash = ( "key1" : 1, "key2" : 2) + ( "key3" : "three", "key4": "four");
$bin = $bin1 + $bin2;
Table 2.45. Argument Processing and Conversion Priorities for +
Argument | Processing |
---|---|
Gives the result of concatenating its arguments, i.e. (1, 2) + (3, 4) = (1, 2, 3, 4) | |
Gives the result of concatenating its arguments. | |
Gives the result of adding date/time values (see Date/Time Arithmetic) | |
Gives the result of adding its arguments. | |
Gives the result of adding its arguments. | |
Gives the result of concatenating/merging its arguments. Any common keys will be overwritten by the values in the second hash ( |
This operator does not throw any exceptions.
With float or integer arguments, subtracts one number from another.
With date arguments, subtracts one date from another; if both date arguments are absolute dates, the result is a relative date (duration) giving the time between them; if the first date argument is an absolute date and the second is a relative date (duration), then the result is an absolute date. If both date arguments are relative dates, then the result is a relative date. If the first argument is a relative date and the second date is an absolute date, the result is an absolute date as if the operands were reversed.
However, if the left-hand side is a hash, and the right-hand side is a string, then the hash key represented by the string will be removed from the hash. If the left-hand side is a hash and the right-hand side is a list, then each element in the list will be converted to a string and any hash key with that name will be deleted from the hash.
expression1
-expression2
$num = $x - $y;
$date = 2010-05-13 - P3MT14H10M;
$hash = $hash - "key";
$hash = $hash - ("key1", "key2", "key3");
Table 2.46. Argument Processing and Conversion Priorities for -
Argument | Processing |
---|---|
date subtraction: | |
arithmetic subtraction: | |
arithmetic subtraction: | |
hash key deletion: | |
hash key deletion: |
This operator does not throw any exceptions.
Shifts bits in an integer towards zero (divides an integer by a power of 2)
expression1
>>expression2
$a = $x >> $y;
Table 2.47. Arguments Processed By >>
Argument | Processing |
---|---|
Gives the result of shifting |
This operator does not throw any exceptions.
Shifts bits in an integer towards infinity (multiplies an integer by a power of 2)
expression1
<<expression2
$a = $x << $y;
Table 2.48. Arguments Processed By <<
Argument | Processing |
---|---|
Gives the result of shifting |
This operator does not throw any exceptions.
Tests if an expression is an instance of a class or not.
expression
instanceofclass_specification
if ($obj instanceof Qore::Mutex) print("object is Mutex\n");
Table 2.49. Arguments Processed By instanceof
Argument | Processing |
---|---|
| If |
This operator does not throw any exceptions.
Tests if an expression represents a value or not.
exists expression
if (exists $a) printf("a = $n\n", $a);
Table 2.50. Arguments Processed By exists
Argument | Processing |
---|---|
| If |
This operator does not throw any exceptions.
Tests if a value is less than another; types are converted if necessary (ex: ("1" < 2) is True
).
expression1
<expression2
if ($x < $y)
printf("%n is less than %n\n", $x, $y);
Table 2.51. Argument Processing and Conversion Priorities for <
Argument | Processing |
---|---|
If | |
If | |
If | |
If |
This operator does not throw any exceptions.
Tests if a value is greater than another; types are converted if necessary (ex: ("2" > 1) is True
).
expression1
>expression2
if ($x > $y)
printf("%n is less than %n\n", $x, $y);
expression1
>expression2
Table 2.52. Argument Processing and Conversion Priorities for >
Argument | Processing |
---|---|
If | |
If | |
If | |
If |
This operator does not throw any exceptions.
Tests if a value is equal to another; types are converted if necessary (ex: ("1" == 1) is True
). For absolute equals, where types must also be equal to return true, see the Absolute Equals Operator (===).
expression1
==expression2
if ($x == $y)
printf("%n is equal to %n\n", $x, $y);
Table 2.53. Argument Processing and Conversion Priorities for ==
Argument | Processing |
---|---|
If | |
If | |
If | |
If | |
If each element in the each list where order is relevant satisfies this operator, the operator returns | |
If each hash has the same keys and the value of each equal key in each hash satisfies this operator, the operator returns | |
If | |
If | |
If both expressions are NULL, returns | |
If neither expression has a value, returns |
This operator does not throw any exceptions.
Tests if a value is not equal to another; types are converted if necessary (ex: ("1" != 1) is False
).
expression1
!=expression2
if ($x != $y)
printf("%n is not equal to %n\n", $x, $y);
Table 2.54. Argument Processing and Conversion Priorities for !=
Argument | Processing |
---|---|
If | |
If | |
If | |
If | |
If any element in the each list compared where order is relevant satisfies this operator, the operator returns | |
If the hashes have different key sets, or the values of any equal key in each hash satisfies this operator, the operator returns | |
If either | |
If | |
If one expression is NULL and the other not, returns | |
If one of the expressions has a value, returns |
This operator does not throw any exceptions.
Tests if a value is less than or equals to another value; types are converted if necessary (ex: ("1" <= 2) is True
).
expression1
<=expression2
if ($x <= $y)
printf("%n is less than or equal to %n\n", $x, $y);
Table 2.55. Argument Processing and Conversion Priorities for <=
Argument | Processing |
---|---|
If | |
If | |
If | |
If |
This operator does not throw any exceptions.
Tests if a value is greater than or equals to another value; types are converted if necessary (ex: ("2" >= 1) is True
).
expression1
>=expression2
if ($x >= $y)
printf("%n is greater than or equal to %n\n", $x, $y);
Table 2.56. Argument Processing and Conversion Priorities for >=
Argument | Processing |
---|---|
If | |
If | |
If | |
If |
This operator does not throw any exceptions.
Tests if the left-hand value is less than, equal, or greater than the right-hand value; types are converted if necessary (ex: ("1" <=> 2) returns -1).
expression1
<=>expression2
switch ($x <=> $y) { case -1: print("$x is less than $y\n"); break; case 0: print("$x is equal to $y\n"); break; case 1: print("$x is greater than $y\n"); break; }
Table 2.57. Argument Processing and Conversion Priorities for <=>
Argument | Processing |
---|---|
If | |
If | |
If | |
If |
This operator does not throw any exceptions.
Checks two values for equality without doing any data type conversions; if the types do not match, then the result is False
.
expression1
===expression2
if ($x === $y)
printf("%n is equal to %n and has the same data type as well\n", $x, $y);
Table 2.58. Arguments Processed By ===
Argument | Processing |
---|---|
All | This operator returns |
This operator does not throw any exceptions.
Checks two values for inequality without doing any data type conversions. If the data types do not match, then returns True
.
expression1
!== expression2
if ($x !== $y)
printf("%n is not equal to %n and may not have the data type as well\n", $x, $y);
Table 2.59. Arguments Processed By !==
Argument | Processing |
---|---|
All | This operator returns |
This operator does not throw any exceptions.
Checks for a regular expression match; returns True
if the expression matches the string, False
if not. See Regular Expression Options for the meaning of the i, s, x, and m options after the regular expression.
See Regular Expressions for more information about regular expression support in Qore.
expression
=~ [m]/regex
/[isxm]
if ($str =~ /hello/)
printf("%s contains 'hello'\n", $str);
Table 2.60. Arguments Processed By =~
Argument | Processing |
---|---|
This operator returns |
This operator does not throw any exceptions.
Checks for a regular expression non match; returns True
if the expression does not match the string, False
if it does. See Regular Expression Options for the meaning of the i, s, x, and m options after the regular expression.
See Regular Expressions for more information about regular expression support in Qore.
expression
!~ [m]/regex
/[isxm]
if ($str !~ /hello/)
printf("%s does not contain 'hello'\n", $str);
Table 2.61. Arguments Processed By !~
Argument | Processing |
---|---|
This operator returns |
This operator does not throw any exceptions.
Looks for a regular expression match in a string, and, if found, substitutes the matched string with a new string. Subpattern backreferences are supported in the target string, $1=first subpattern, $2=second subpattern, etc... See Regular Expression Options for the meaning of the i, s, x, and m options after the regular expression.
See Regular Expressions for more information about regular expression support in Qore.
lvalue
=~ s/regex_pattern
/target_string
/[isxmg]
$str =~ s/hello/goodbye/i;
$str =~ s/(\w+) +(\w+)/$2, $1/;
Table 2.62. Arguments Processed By =~ s///
Argument | Processing |
---|---|
This operator substitutes text in the |
This operator does not throw any exceptions.
Matches regular expression patterns (enclosed in parentheses) in a string and returns a list giving the text matched for each pattern. If the regular expression does not match, then no value (NOTHING) is returned. See Regular Expression Options for the meaning of the i, s, x, and m options after the regular expression.
See Regular Expressions for more information about regular expression support in Qore.
string
=~ x/regex_with_patterns
/[isxm]
$list =~ x/(\w+):(\w+)/;
$list =~ x/(.*)\.(.*)/;
Table 2.63. Arguments Processed By =~ x//
Argument | Processing |
---|---|
This operator extracts strings from the |
This operator does not throw any exceptions.
Table 2.64. Arguments Processed By =~ tr//
Argument | Processing |
---|---|
This operator substitutes characters in the |
This operator does not throw any exceptions.
Performs a bitwise (binary) AND operation on two integers.
expression1
&expression2
$a = $x & $y;
Table 2.65. Arguments Processed By &
Argument | Processing |
---|---|
Gives the result of the binary (bitwise) AND operation between |
This operator does not throw any exceptions.
Performs a bitwise (binary) OR operation on two integers.
expression1
|expression2
$a = $x | $y;
Table 2.66. Arguments Processed By |
Argument | Processing |
---|---|
Gives the result of the binary (bitwise) OR operation between |
This operator does not throw any exceptions.
Performs a bitwise (binary) XOR operation on two integers.
expression1
^expression2
$a = $x ^ $y;
Table 2.67. Arguments Processed By ^
Argument | Processing |
---|---|
Gives the result of the binary (bitwise) EXCLUSIVE OR operation between |
This operator does not throw any exceptions.
Checks to see if two expressions are True
with logical short-circuiting.
expression1
&&expression2
if ($x && $y)
printf("%n and %n are both True
\n", $x, $y);
Table 2.68. Arguments Processed By &&
Argument | Processing |
---|---|
Returns |
This operator does not throw any exceptions.
Returns True
if either of the arguments are True
with logical short-circuiting.
expression1
||expression2
if ($x || $y)
printf("either %n or %n or both are True
\n", $x, $y);
Table 2.69. Arguments Processed By ||
Argument | Processing |
---|---|
Returns |
This operator does not throw any exceptions.
Evaluates and returns the value of one of two expressions depending on the value of a conditional expression.
expression ? if_true_expression : if_false_expression
$a = ($z > 100 ? "Big" : "Small");
Table 2.70. Arguments Processed By ? :
Argument | Processing |
---|---|
All | If |
This operator does not throw any exceptions.
Makes a list from more than one element.
expression1, expression2
$a = 1, 2, "three";
Table 2.71. Arguments Processed By ,
Argument | Processing |
---|---|
All | The comma operator builds lists of arguments. |
This operator does not throw any exceptions.
Inserts an element into the first position of a list and moves all other elements up one position.
unshift lvalue, expression
unshift $list, "one";
Table 2.72. Arguments Processed By unshift
Argument | Processing |
---|---|
All | Inserts the value of |
Table 2.73. Arguments Processed By push
Argument | Processing |
---|---|
All | Appends the value of the expression as the last element in the list given by |
Removes and optionally inserts elements in lists and strings. For a similar operator that returns the values removed, see the extract operator.
splice lvalue, offset_expression, [length_expression, [substitution_expression]]
splice $list, 2, 2;
splice $string, 2, 2, "-text-";
Works on either strings or lists in a similar way; removes elements from a list or characters from a string and optionally inserts new ones. If no length_expression
is given, splice removes all elements/characters from the list or string starting at offset_expression
) (list and string offsets begin at 0). Otherwise, a number of elements/characters equal to length_expression
is removed (or up to the end of the list/string if applicable). If substitution_expression
is present, then the removed elements/characters are substituted with the elements/string given by this expression.
Note that string splice takes character offsets, which may not be the same as byte offsets for multi-byte character encodings, such as UTF-8
Table 2.74. Arguments Processed By splice
Argument | Processing |
---|---|
If the lvalue is a list, list elements are processed, otherwise, if it is a string, characters in the string are processed. For any other data type, no action is taken. | |
| The start element/character position for removing elements/characters from the list or string. |
| The number of elements/characters to remove. If this expression is not present, then all elements/characters from the offset to the end of the list/string are removed. If this expression is present and evaluates to 0, no characters/elements are removed. |
| For list splice, an optional element or list to substitute for the removed elements (to insert a list in a single element's position, make sure that the list to be inserted is the first and only element of another list used as the argument in this position; in other words, pass a list within a single-element list). For string splice, an optional string to substitute for the removed characters. |
Removes and optionally inserts elements in lists and strings. For a similar operator that only removes value and does not return any value, see the splice operator.
extract lvalue, offset_expression, [length_expression, [substitution_expression]]
my list $sublist = extract $list, 2, 2;
my string $substring = extract $string, 2, 2, "-text-";
Works on either strings or lists in a similar way; removes elements from a list or characters from a string and optionally inserts new ones. If no length_expression
is given, extract removes all elements/characters from the list or string starting at offset_expression
) (list and string offsets begin at 0). Otherwise, a number of elements/characters equal to length_expression
is removed (or up to the end of the list/string if applicable). If substitution_expression
is present, then the removed elements/characters are substituted with the elements/string given by this expression.
When operating on lists, a list is returned of any elements extracted (if no elements are extracted, then an empty list is returned); when operating on strings, a string is extracted of all characters extracted from the string (if no characters are extracted, then an empty string is returned).
Note that string extract takes character offsets, which may not be the same as byte offsets for multi-byte character encodings, such as UTF-8
Table 2.75. Arguments Processed By extract
Argument | Processing |
---|---|
If the lvalue is a list, list elements are processed, otherwise, if it is a string, characters in the string are processed. For any other data type, no action is taken. | |
| The start element/character position for removing elements/characters from the list or string. |
| The number of elements/characters to remove. If this expression is not present, then all elements/characters from the offset to the end of the list/string are removed. If this expression is present and evaluates to 0, no characters/elements are removed. |
| For list extract, an optional element or list to substitute for the removed elements (to insert a list in a single element's position, make sure that the list to be inserted is the first and only element of another list used as the argument in this position; in other words, pass a list within a single-element list). For string extract, an optional string to substitute for the removed characters. |
Assigns a value to an lvalue and returns the value assigned.
lvalue
=expression
$a = 1;
Increments and concatentates an lvalue with the value of an expression depending on the data type of the lvalue, unless the lvalue is NOTHING, in which case this operator acts like the assignment operator (simply assigns the value of the right hand side to the lvalue).
lvalue
+=expression
$a += 10;
$date += P1M2DT45M;
$list += $new_element;
$string += ".foo";
$binary += <0c67a374>
$hash += ("new-key" : 1, "other" : "two");
$object += $hash;
Table 2.77. Arguments Processed By +=
Argument | Processing |
---|---|
list | the expression will be evaluated and concatenated to the lvalue. If expression is a list, the lists will be concatenated, to ensure adding a single element to a list, use the push operator (see Push Operator). |
the expression will be evaluated, and, if it is a hash or object, then it's members will be added to the lvalue, any duplicate elements in the lvalue will be overridden by elements in the expression. | |
string | the expression will be evaluated and converted to a string if necessary and concatenated to the lvalue. |
float | the expression will be evaluated and converted to a float if necessary and added to the lvalue. |
binary | the expression will be evaluated and converted to a binary if necessary and added to the lvalue. |
date | the expression will be evaluated and converted to a date if necessary and added to the lvalue. |
nothing | the lvalue will be assigned to the value of |
| the lvalue's type will be converted to an integer, and the expression will be evaluated and converted to an integer if necessary, and then the result will be added to the lvalue. |
For a float or integer argument, decrements the value of an lvalue by the value of an expression. However if the lvalue is a hash and the expression is a string, removes the key represented by the string from the hash.
lvalue
-=expression
$a -= 10;
$date -= PT45H213S;
$hash -= "key";
$hash -= ("key1", "key2");
$object -= "key";
$object -= $list_of_keys;
Table 2.78. Arguments Processed By -=
Argument | Processing |
---|---|
float | the expression will be evaluated and converted to a float if necessary and subtracted from the lvalue |
date | the expression will be evaluated and converted to a date if necessary and subtracted from the lvalue |
the hash key represented by | |
each element in the list will be converted to a string (if necessary) and the key represented by each string will be removed from the hash | |
the lvalue will be assigned to | |
| the lvalue's type will be converted to an integer (if necessary), and the expression will be evaluated and converted to an integer (if necessary), and then the result will be subtracted from the lvalue |
Performs a bitwise (binary) AND operation on an lvalue using the value of an expression and returns the new value.
lvalue
&=expression
$a &= 0xfe;
Table 2.79. Arguments Processed By &=
Argument | Processing |
---|---|
All | the lvalue's type will be converted to an integer if necessary, and the expression will be evaluated and converted to an integer as well if necessary, and then the result will be binary and'ed to the lvalue |
Performs a bitwise (binary) OR operation on an lvalue using the value of an expression and returns the new value.
lvalue
|=expression
$a |= 0xba;
Table 2.80. Arguments Processed By |=
Argument | Processing |
---|---|
All | the lvalue's type will be converted to an integer if necessary, and the expression will be evaluated and converted to an integer as well if necessary, and then the result will be binary or'ed to the lvalue |
Performs a modula calculation on an lvalue using the value of an expression and returns the new value.
lvalue
%=expression
$a %= 100;
Table 2.81. Arguments Processed By %=
Argument | Processing |
---|---|
All | the lvalue's type will be converted to an integer if necessary, and the expression will be evaluated and converted to an integer as well if necessary, and then the result will be used to divide the lvalue's value and the remainder will be saved to the lvalue |
Table 2.82. Arguments Processed By *=
Argument | Processing |
---|---|
All | If either side of the operator is a float, the result will be a float as well. Otherwise the result is an integer value. The expression will be evaluated and multiplied by the lvalue, and the result will be saved to the lvalue. |
Table 2.83. Arguments Processed By *=
Argument | Processing |
---|---|
All | If either side of the operator is a float, the result will be a float as well. Otherwise the result is an integer value. The expression will be evaluated and used to divide the lvalue, and the result will be saved to the lvalue. |
Table 2.84. Exceptions Thrown by /*
err | desc |
---|---|
| If the divisor expression evaluates to zero, this exception is thrown. |
Performs an exclusive-or operation on an lvalue using the value of an expression.
lvalue
^=expression
$a ^= 0xf9034ba7;
Table 2.85. Arguments Processed By ^=
Argument | Processing |
---|---|
All | Values are converted to integers if necessary. The expression will be evaluated and exclusive-or'ed with the lvalue, and the result will be saved to the lvalue. |
Performs a shift-left operation on an lvalue using the value of an expression and returns the value assigned.
lvalue
<<=expression
$a <<= 3;
Table 2.86. Arguments Processed By <<=
Argument | Processing |
---|---|
All | Values are converted to integers if necessary. The expression will be evaluated and this value will determine how many bits the lvalue will be shifted left. The result will be saved to the lvalue. |
Performs a shift-right operation on an lvalue using the value of an expression and returns the value assigned.
lvalue
>>=expression
$a >>= 3;
Table 2.87. Arguments Processed By >>=
Argument | Processing |
---|---|
All | Values are converted to integers if necessary. The expression will be evaluated and this value will determine how many bits the lvalue will be shifted right. The result will be saved to the lvalue. |
Regular expression functionality in Qore is provided by PCRE: Perl-Compatible Regular Expression library.
Using this library, Qore implements regular expression pattern matching using the same syntax and semantics as Perl 5.
The following is a list of operators based on regular expressions (or similar to regular expressions in the case of the transliteration operator).
Table 2.88. Regular Expression Operators
Operator | Description |
---|---|
Returns | |
Returns | |
Substitutes text in a string based on matching a regular expression. | |
Returns a list of substrings in a string based on matching patterns defined by a regular expression. | |
Not a regular expression operator; transliterates one or more characters to other characters in a string. |
See the table below for valid regular expression options.
Table 2.89. Regular Expression Options
Option | Description |
---|---|
i | Ignores case when matching |
m | makes start-of-line (^) or end-of-line ($) match after or before any newline in the subject string |
s | makes a dot (.) match a newline character |
x | ignores whitespace characters and enables comments prefixed by # |
g | makes global substitutions (only applicable with the substitution operator) |
The following is a list of functions providing regular expression functionality where the pattern may be given at run-time:
Table 2.90. Regular Expression Functions
Function | Description |
---|---|
Returns | |
Substitutes a pattern in a string based on regular expressions and returns the new string. | |
Returns a list of substrings in a string based on matching patterns defined by a regular expression. |
Date/time arithmetic is relatively straightforward and should normally produce the expected results. However with leap years, months with different lengths, and daylights savings time the situation can be confusing; this section will clarify how Qore does date arithmetic considering these special cases.
Adding or subtracting years and months (ex: $date += 2Y + 3M) will give you the same day on the desired month in the desired year. If the target month has fewer days than the source month, then you will get the last day of the month in that year. For example:
prompt%
qore -X '2004-02-29Z - 1Y'
2003-02-28 00:00:00 Fri Z (UTC)
Adding or subtracting days means adding or subtracting 24h periods; i.e. you will get the same time in the result of subtracting days, for example:
prompt%
qore -X '2004-02-29T10:15:00Z - 10D'
2004-02-19 10:15:00 Thu Z (UTC)
Subtracting one absolute date from another will result in a relative date, normalized to the hour (that is, microseconds over 999,999 are converted to seconds, seconds over 59 to minutes, and minutes over 59 to hours; days, months, and years will not appear in the result as they do not indicate a fixed period of time but rather can vary in length depending on the absolute date/time starting point. For example:
prompt%
qore -X '2007-02-29T10:15:03.255Z - 2004-02-29T10:14:02.100Z'
<time: 26304 hours 1 minute 1 second 155 milliseconds>
To find the difference in seconds between two dates, convert each date value to an integer and subtract as follows:
prompt%
qore -X 'int(2004-02-29Z) - int(2004-02-28Z)'
86400
Or use the get_duration_seconds() function as follows:
prompt%
qore -X 'get_duration_seconds(2004-02-29Z - 2004-02-28Z)'
86400
Time zones and daylight savings time information is supplied by the system's zoneinfo database (if any exists; see Time Zones for more information).
To find out if the current time zone has daylight savings time, execute the following:
prompt%
qore -X 'TimeZone::get().hasDST()'
True
See the TimeZone class for more information on time zone information.
Qore is capable of representing and performing calculations on dates before the adoption of the Gregorian calendar (proposed in 1582 and adopted at various times in Europe after this point). However all calculations are made as if the Gregorian calendar were always in effect (Qore implements a proleptic Gregorian calendar).
Non-block statements in Qore are always terminated by a semi-colon ";" as in Perl, C, or Java. Statements can be grouped into blocks, which are delimited by curly brackets "{" and "}" containing zero or more semi-colon delimited statements, as in C or Java. Like C, C++, and Java, but unlike perl, any Qore statement taking a statement modifier will accept a single statement or a statement block.
A statement can be any of the following (note that statements are also recursively defined):
Table 2.91. Qore Statements
Type | Examples | Reference |
---|---|---|
An expression that changes an lvalue | $var = 1;
$var += 5;
$var[1].count++;
shift $var.key[$i]; | |
An expression with the new operator | new ObjectClass(1, 2, 3); | |
An expression with the background operator | background function(); | |
A call reference or closure call | $call_reference($arg1, $arg2); | |
A method call | $object.method(1, 2, 3); | |
An if statement | if ($var == 3) | if and else statements |
An "if ... else" statement | if ($var == 3) | if and else statements |
A while statement | while ($var < 10)
| while statements |
A do while statement | do | do while statements |
A for statement | for ( | for statements |
A foreach statement | foreach | foreach statements |
A switch statement | switch ( | switch statements |
A return statement | return | return statements |
A local variable declaration |
my $var; my ($a, $b, $c); | |
A global variable declaration |
our $var; our ($a, $b, $c); | |
A function call | calculate($this, $that, $the_other); | |
A continue statement | continue; | continue statements |
A break statement | break; | break statements |
A statement block | { | one or more statements enclosed in curly brackets. |
A throw statement | throw | throw statements |
try and catch statements | try | try and catch statements |
A rethrow statement | rethrow; | rethrow statements |
A thread_exit statement | thread_exit; | thread_exit statements |
A context statement |
context | context statements |
A summarize statement |
summarize | summarize statements |
A subcontext statement | subcontext
| subcontext statements |
An on_exit statement | on_exit
| on_exit statements |
An on_success statement | on_success
| on_success statements |
An on_error statement | on_error
| on_error statements |
The if statement allows for conditional logic in a Qore program's flow; the syntax is similar to that of C, C++, or Java.
if (expression
)statement
[elsestatement
]
Qore if statements work like if statements in C or Java. If the result of evaluating the expression converted to a Boolean value is True
, then the first statement (which can also be a block) is executed. If the result is False
, and there is an else keyword after the first statement, the following statement is executed.
Any expression that evaluates to a non-zero integer value will be converted to a Boolean True
. Any expression that evaluates to zero value is interpreted as False
. This is more like C and Java's behavior and not like Perl's (where any non-null string except "0" is True
).
The Qore for statement is most similar to the for statement in C and Java, or the non array iterator for statement in Perl. This statement is ideal for loops that should execute a given number of times, then complete. Each of the three expressions in the for statement is optional and may be omitted. To iterate through a list without directly referencing list index values, see the foreach statement.
for ([initial_expression]
;[test_expression]
;[iterator_expression]
)statement
[initial_expression]
The initial_expression
is executed only once at the start of each for loop. It is typically used to initialize a loop variable.
[test_expression]
The test_expression
is executed at the start of each for loop iteration. If this expression evaluates to Boolean False
, the loop will terminate.
[iterator_expression]
The iterator_expression
is executed at the end of each for loop iteration. It is typically used to increment or decrement a loop variable that will be used in the test_expression
.
Here is an example of a for loop using a local variable:
for (my $i = 0; $i < 10; $i++) print("%d\n", $i);
The Qore foreach statement is most similar to the for or foreach array iterator statement in Perl. To iterate an action until a condition is true, use the for statement instead.
foreach [my]$variable
in (expression
)statement
If the expression
does not evaluate to a list, then the variable will be assigned the value of the expression evaluation and the statement will only execute one time. Otherwise the variable will be assigned to each value of the list and the statement will be called once for each value.
Here is an example of a foreach loop using a local variable:
# if $str_list is a list of strings, this will remove all whitespace from the # strings; the reference in the list expression ensures that changes # to the iterator variable are written back to the list foreach my $string in (\$str_list) trim $string;
Note that if a reference (\$lvalue_expression
) is used as the list expression, any changes made to the foreach iterator variable will be written back to the list.
The Qore switch statement is similar to the switch statement in C and C++, except that the case values can be any expression that does not need run-time evaluation and can also be expressions with simple relational operators or regular expressions using the switch value as an implied operand.
switch (expression
) { casecase_expression
:statement(s)
... [ default :statement(s)
] }
switch ($val) { case < -1: printf("less than -1\n"); break; case "string": printf("string\n"); break; case > 2007-01-22T15:00:00: printf("greater than 2007-01-22 15:00:00\n"); break; case /abc/: printf("string with 'abc' somewhere inside\n"); break; default: printf("default\n"); break; }
The first expression is evaluated and then compared to the value of each case expression in declaration order until one of the case expressions matches or is evaluated to True
. In this case all code up to a break statement is executed, at which time execution flow exits the switch statement. Unless relational operators are used, the comparisons are "hard" comparisons; no type conversions are done, so in order for a match to be made, both the value and types of the expressions must match exactly. When relational operators are used, the operators are executed exactly as they are in the rest of qore, so type conversions may be performed if nesessary.
To use soft comparisons, you must explicitly specify the soft equals operator as follows:
switch (1) { case == "1": print("true\n"); break; }
If no match is found and a default label has been given, then any statements after the default label will be executed. If a match is made, then the statements following that case label are executed.
To break out of the switch statement, use the break statement.
Table 2.92. Valid Case Expression Operators
Operator | Description |
---|---|
> | |
>= | |
< | |
<= | |
== | |
~= | regular expression match operator (in this case the regular expression may be optionally given without the operator) |
!~ |
while statements in Qore are similar to while statements in Perl, C and Java. They are used to loop while a given condition is True
.
while (expression
)statement
First the expression
will be evaluated; if it evaluates to True
, then statement
will be executed. If it evaluates to False
, the loop terminates.
$a = 1;
while ($a < 10)
$a++;
do while statements in Qore are similar to do while statements in C. They are used to guarantee at least one iteration and loop until a given expression evaluates to False
.
dostatement
while (expression
);
First, statement
will be executed, then expression
will be evaluated; if it evaluates to True
, then the loop iterates again. If it evaluates to False
, the loop terminates. The difference between do while statements and while statements is that the do while statement evaluates its loop expression at the end of the loop, and therefore guarantees at least one iteration of the loop.
$a = 1; do $a++; while ($a < 10);
Skips the rest of a loop and jumps right to the evaluation of the iteration expression.
continue;
The continue statement affects loop processing; that is; it has an affect on for, foreach, while, do while, context, summarize, and subcontext loop processing. When this statement is encountered while executing a loop, execution control jumps immediately to the evaluation of the iteration expression, skipping any other statements that might otherwise be executed.
Exits immediately from a loop statement or switch block.
break;
The break statement affects loop processing; that is; it has an affect on for, while, do while, context, summarize, and subcontext loop processing. When this statement is encountered while executing a loop, the loop is immediately exited, and execution control passes to the next statement outside the loop.
In order to throw an exception explicitly, the throw statement must be used.
throw expression;
The expression will be passed to the catch block of a try/catch statement, if the throw is executed in a try block. Otherwise the default system exception handler will be run and the currently running thread will terminate.
Qore convention dictates that a direct list is thrown with at least two string elements, the error code and a description. All system exceptions have this format. See try and catch statements for information on how to handle exceptions, and see Exception Handling for information about how throw arguments are mapped to the exception hash.
Some error conditions can only be detected and handled using exception handlers. To catch exceptions, try and catch statements can to be used. When an exception occurs while executing the try block, execution control will immediately be passed to the catch block, which can capture information about the exception.
trystatement
catch ([$exception_hash_variable
])statement
A single variable can be specified in the catch block to be instantiated with the exception hash, giving information about the exception that has occurred. For detailed information about the exception hash, see Exception Handling.
If no variable is given in the catch declaration, it will not be possible to access any information about the exception in the catch block. However, the rethrow statement can be used to rethrow exceptions at any time in a catch block.
A rethrow statement can be used to rethrow an exception in a catch block. In this case a entry tagged as a rethrow entry will be placed on the exception call stack. This statement can be used to maintain coherent call stacks even when exceptions are handled by more than one catch block (for detailed information about the exception hash and the format of call stacks, see Exception Handling).
rethrow;
The rethrown exception will be either passed to the next higher-level catch block, or to the system default exception handler, as with a throw statement. Note that it is an error to call rethrow outside of a catch block.
thread_exit statements cause the current thread to exit immediately. Use this statement instead of the exit() function when only the current thread should exit.
thread_exit;
This statement will cause the current thread to stop executing immediately.
To easily iterate through multiple rows in a hash of arrays (such as a query result set returned by the Datasource::select() method), the context statement can be used. Column names can be referred to directly in expressions in the scope of the context statement by preceding the name with a '%" character.
context [name] (data_expression )
[ where (expression
) ] [ sortBy (expression
) ] [ sortDescendingBy (expression
) ]statement
data_expression
This must evaluate to a hash of arrays in order for the context statement to execute.
[ where (
expression
) ]
An optional where expression may be given, in which case for each row in the hash,
the expression will be executed, and if the where expression evaluates to True
,
the row will be iterated in the context loop. If this expression evaluates
to False
, then the row will not be iterated. This option is given so the
programmer can create multiple views of a single data structure (such as a query
result set) in memory rather than build different data structures by
hand.
[ sortBy (
expression
) ]
An optional sort_by expression may also be given. In this case, the expression will be evaluated for each row of the query given, and then the result set will be sorted in ascending order by the results of the expressions according to the resulting type of the evaluated expression (i.e. if the result of the evaluation of the expression gives a string, then string order is used to sort, if the result of the evaluation is an integer, then integer order is used, etc).
[ sortDescendingBy (
expression
) ]
Another optional modifier to the context statement that behaves the same as above except that the results are sorted in descending order.
# note that "%service_type" and "%effective_start_date" represent values # in the $service_history hash of arrays. context ($service_history) where (%service_type == "voice") sortBy (%effective_start_date) { printf("%s: start date: %s\n", %msisdn, format_date("YYYY-MM-DD HH:mm:SS", %effective_start_date)); }
summarize statements are like context statements with one important difference: results sets are grouped by a by expression, and the statement is executed only once per discrete by expression result. This statement is designed to be used with the subcontext statement.
summarize (expression
) by (expression
) [ where (expression
) ] [ sortBy (expression
) ] [ sortDescendingBy (expression
) ]statement
summarize statements modifiers have the same effect as those for the context statement, except for the following:
by (
expression
)
The by expression is executed for each row in the data structure indicated. The set of unique results defines groups of result rows. For each group of result rows, each row having an identical result of the evaluation of the by expression, the statement is executed only once.
# note that "%service_type" and "%effective_start_date" represent values # in the $services hash of arrays. summarize ($services) by (%effective_start_date) where (%service_type == "voice") sortBy (%effective_start_date) { printf("account has %d service(s) starting on %s\n", context_rows(), format_date("YYYY-MM-DD HH:mm:SS", %effective_start_date)); }
Statement used to loop through values within a summarize statement.
subcontext [ where (expression
) ] [ sortBy (expression
) ] [ sortDescendingBy (expression
) ]statement
The subcontext statement is used in conjunction with summarize statements. When result rows of a query should be grouped, and then each row in the result set should be individually processed, the Qore programmer should first use a summarize statement, and then a subcontext statement. The summarize statement will group rows, and then the nested subcontext statement will iterate through each row in the current summary group.
summarize ($services) by (%effective_start_date) where (%service_type == "voice") sortBy (%effective_start_date) { printf("account has %d service(s) starting on %s\n", context_rows(), format_date("YYYY-MM-DD HH:mm:SS", %effective_start_date)); subcontext sortDescendingBy (%effective_end_date) { printf("\tservice %s: ends: %s\n", %msisdn, format_date("YYYY-MM-DD HH:mm:SS", %effective_end_date)); } }
return statements causes the flow of execution of the subroutine, method or program to stop immediately and return to the caller. This statement can take an optional expression to return a value to the caller as well.
return [expression
];
This statement causes execution of the current subroutine, method, or program to cease and optionalls returns a value to the caller.
sub getName() returns string { return "Barney"; } my string $name = getName();
Queues a statement or statement block for unconditional execution when the block is exited, even in the case of exceptions or return statements. For similar statement that queue code for execution depending on the exception status when the block exits, see on_success statements and on_error statements.
on_exit
statement
The on_exit statement provides a clean way to do exception-safe cleanup within Qore code. Any single statment (or statement block) after the on_exit keyword will be executed when the current block exits (as long as the statement itself is reached when executing - on_exit statements that are never reached when executing will have no effect). The the position of the on_exit statement in the block is important, as the immediate effect of this statement is to queue its code for execution when the block is exited. Even if an exception is raised or a return statement is executed, any on_exit code that is queued will be executed. Therefore it's ideal for putting cleanup code right next to the code that requires the cleanup.
Note that if this statement is reached when executing in a loop, the on_exit code will be executed for each iteration of the loop.
By using this statement, programmers ensure that necessary cleanup will be performed regardless of the exit status of the block (exception, return, etc).
{ $mutex.lock(); # here we queue the unlock of the mutex when the block exits, even if an exception is thrown below on_exit $mutex.unlock(); if ($error) throw "ERROR", "Scary error happened"; print("everything's OK!\n"); return "OK"; } # when the block exits for any reason, the mutex will be unlocked
Queues a statement or statement block for execution when the block is exited in the case that no exception is active. Used often in conjunction with the on_error statement and related to the on_exit statement.
on_success
statement
The on_success statement provides a clean way to do block-level cleanup within Qore code in the case that no exception is thrown in the block. Any single statment (or statement block) after the on_success keyword will be executed when the current block exits as long as no unhandled exception has been thrown (and as long as the statement itself is reached when executing - on_success statements that are never reached when executing will have no effect). The the position of the on_success statement in the block is important, as the immediate effect of this statement is to queue its code for conditional execution when the block is exited. Even if a return statement is executed later in the block, any on_success code that is queued will be executed as long as there is no active (unhandled) exception. Therefore it's ideal for putting cleanup code right next to the code that requires the cleanup, along with on_error statements, which are executed in a manner similar to on_success statements, except on_error statements are only executed when there is an active exception when the block is exited.
Note that if this statement is reached when executing in a loop, the on_success code will be executed for each iteration of the loop (as long as there is no active exception).
{ $db.beginTransaction(); # here we queue the commit in the case there are no errors on_success $db.commit(); # here we queue a rollback in the case of an exception on_error $db.rollback(); $db.select("select * from table where id = %v for update", $id); # .. more code return "OK"; } # when the block exits. the transaction will be either committed or rolled back, # depending on if an exception was raised or not
Queues a statement or statement block for execution when the block is exited in the case that no exception is active. Used often in conjunction with the on_success statement and related to the on_exit statement.
on_error
statement
The on_error statement provides a clean way to do block-level cleanup within Qore code in the case that an exception is thrown in the block. Any single statment (or statement block) after the on_error keyword will be executed when the current block exits as long as an unhandled exception has been thrown (and as long as the statement itself is reached when executing - on_error statements that are never reached when executing will have no effect). The the position of the on_error statement in the block is important, as the immediate effect of this statement is to queue its code for conditional execution when the block is exited. Even if a return statement is executed later in the block, any on_error code that is queued will be executed as long as there is an active (unhandled) exception. Therefore it's ideal for putting cleanup code right next to the code that requires the cleanup, along with on_success statements, which are executed in a manner similar to on_error statements, except on_success statements are only executed when there is no active exception when the block is exited.
Note that the code in this statement can only be executed once in any block, as a block (even a block within a loop) can only exit the loop once with an active exception (in contrast to on_success and on_exit statements, which are executed for every iteration of a loop).
{ $db.beginTransaction(); # here we queue the commit in the case there are no errors on_success $db.commit(); # here we queue a rollback in the case of an exception on_error $db.rollback(); $db.select("select * from table where id = %v for update", $id); # .. more code return "OK"; } # when the block exits. the transaction will be either committed or rolled back, # depending on if an exception was raised or not
A subroutine is declared in Qore by using the key word sub as follows:
subsubroutine_name
([[type] variable1, ...
]) [returnstype
] {statements;
}
Variables listed in parentheses after the subroutine name are the parameters to the subrouting and automatically get local lexical scoping. In order to process a variable number of arguments to a function, the $argv
variable (local variable) is instantiated as a list with the remaining arguments passed to the subroutine. Type declarations optionally precede the parameter variable and will restrict any arguments passed to the type declared. The same subrouting can be declared multiple times if each declaration has different parameter types; this is called overloading the subroutine.
Subroutines can use the return statement to provide a return value. Subroutine names must be valid Qore identifiers.
The return type of the subroutine can be given by listing a type declaration after the returns keyword after the parentheses after the subroutine name.
Note that parameter and return types are required when the PO_REQUIRE_TYPES
or PO_REQUIRE_PROTOTYPES
parse options are set.
Variables passed as function arguments are passed by value by default, unless the caller places a "\" character before an lvalue in the argument list. In this case the subroutine must have a parameter defined to accept the variable passed by reference. Any changes to the local variable will be reflected in the original variable for variables passed by reference. Also note that it is illegal to pass an argument by reference in a background expression.
Subroutines can return values to the calling expression by using the return statement, with the following syntax:
return expression
;
Here is an example subroutine declaration for a function returning a value:
#!/usr/bin/qore # # subroutine declaration example sub print_string(string $string) returns int { print("%s\n", $string); return 1; }
Subroutines may also be recursive. Here is an example of a recursive Qore subroutine definition implementing the Fibonacci function:
#!/usr/bin/qore # # recursive subroutine example sub fibonacci(int $num) returns int { if ($num == 1) return 1; return $num * fibonacci($num - 1); }
Function names are resolved during the second parse pass; therefore functions do not need to be declared before being referenced. This allows an easy definition of 2 or more self-referencing functions.
Namespaces allow constants, classes, and even other namespaces with the same name to co-exist in the same program by defining them in separate namespaces. Constants, classes, and sub-namespaces can be declared to belong to a particular namespace either by defining them in-line within a namespace declaration, or by including the namespace name/path prepended to the constant, class, or namespace declaration separated by two colons "::".
If the user does not specify the parent namespace with a namespace path in constant, class, or namespace declarations, the declaration will be by default in the unnamed default root namespace.
In-line namespace declaration:
namespace [namespace_path
::]namespace_identifier
{ [constant_declarations
] [class_declarations
] [sub-namespace-declarations
] }
Out of line namespace declaration:
namespace [namespace_path
::]namespace_identifier
;
Namespaces can either be resolved by giving a path to the constant, class, or namespace desired, or by leaving out the namespace path and allowing the system to search for the constant, class, or namespace. In either case, a depth-first search of the namespace tree is made for a match. If a namespace path is included, then the tree is searched for the first namespace match. and, if the rest of the declaration cannot be matched, the search continues in the entire namespace tree until a complete match is found.
Namespace paths look like the following:
starting_namespace
::[sub-namespaces
::]constant|class|namespace
All Qore-language constants and classes are defined in the Qore namespace or in a subnamespace of the Qore namespace. The Qore namespace is a direct child of the unnamed default root namespace (::).
For detailed information on all constants and classes defined in system namespaces, see System Namespaces and Class Library.
Constant definitions allow programmers to refer to values with Qore identifiers rather than using the value or the expression that generates the value. Constants are defined with the following syntax:
const [namespace_path
::]constant_identifier
=expr
;
The expression cannot be an expression that has side effects or a parse exception will be raised. Only functions tagged with the CONST
can be used to initialize a constant.
Objects are instantiations of a Qore class. Classes can define private members and methods, which are functions that operate only on the objects of that class.
Classes are declared with the following syntax:
class [namespace_path::
...]class_identifier
[inherits [private|public] [namespace_path::
...]class_identifier
[, ...]] { [private$.var1[, ...]
;] [private { [type
]$.member_name
[ =expr
]; ... }] [public { [type
]$.member_name
[ =expr
]; ... }] [static] [synchronized] [private] [namespace_path
::]method_name_identifier
([[type] $var1, ...]) {statements
; } ... }
Alternatively objects can be defined out of line as follows:
class [namespace_path::
]class_identifier
[inherits [private|public] [namespace_path::
...]class_identifier
[, ...]]; [static] [synchronized] [private] [namespace_path::
]class_identifier
::method_identifier
([[type] $var1, ...]) {statements
; }
Public and private members can only be declared in an in-line class definition (the first example above). If a class has at least one public member declared (or inherits a class with at least one public member declared), then only those members declared as public can be accessed from outside the class, and from within the class only members explicitly declared can be accessed as well (unless the class also defines a memberGate()
method). In this way typographical errors in member names can be caught (at parse time if types are declared).
In a class hierarchy, base class constructor methods can be explicitly specified using a special syntax unique to subclass constructor methods. Please see Class Inheritance for more information.
It's possible to write purely object-oriented scripts/programs in Qore by defining an application class and using the -x
or --exec-class
command-line arguments to tell Qore to instantiate the class instead of doing normal top-level execution (in fact, the --exec-class
arguments disallow the use of top-level statements entirely). For more information, please see Command-Line Parsing and Parse Directives.
Methods declared with the private keyword can only be called by other member functions of the same class. Any attempt to call these methods from outside the class will result in a run-time exception.
Methods declared with the synchronized keyword will only run in one thread at a time.
Methods declared with the static keyword are like regular subroutines that are attached to the class. These methods are not associated with a particular object's state and therefore are not allowed to refer to object members or call non-static methods. Also, no reference to the special $self
variable is allowed within static methods.
Static method calls take a special syntax as documented here.
All class methods are optional, but some methods have a special meaning.
Table 2.93. Special Methods
Name | Description |
---|---|
|
Called when objects are created when instantiated by a variable declaration with a class type and constructor arguments or explicitly with the new operator. User code may not explicitly call
|
|
When a user explicitly calls a copy method, Qore will generate a new object with references to the same members as the source object. Then, if there are any base classes, base class
|
|
Called when objects go out of scope or are explicitly deleted. User code may not explicitly call
|
If this method is implemented in the class, it is called when read access is attempted to private member or members that do not exist in the current object; the return value of this method is returned as the value of the member.
| |
If this method is implemented in the class, it is called when methods are called on the object that do not exist in the current object and the return value of this method is returned as the value of the method call.
| |
|
If this method is implemented in the class, it is called when an object member is updated outside the class with the member name as the argument. Note that this method is called after the member has been updated and without locking; the call is not atomic respective to other threads that also may update the same member simultaneously.
|
When defining a class, members of the current object can be referred to with a special syntax as follows:
$.member_name_identifier
Furthermore, the automatic variable $self
is instantiated which represents the current object (similar to the this
in C++ or Java). Therefore if you need to access hash members which are not valid Qore identifiers, then enclose the member name in double quotes after the dot operator as follows:
$self."&member-name"
The automatic $argv
local variable is instantiated as usual in all class methods where there are more arguments than variables declared in the method declaration.
If the class implements a memberGate()
method, then whenever a non-existant member of the class is accessed (read), this method will be called with the name of the member as the sole argument, so that the class can create the member (or react in some other way) on demand. This method is also called when methods of the same class try to access (read) non-existant methods, but is not called from within the memberGate()
method itself.
To monitor writes to the object, the class can implement a memberNotification()
method, which is called whenever an object member is modified from outside class member code. In this case, the memberNotification()
method is called with the name of the member that was updated so that an object can automatically react to changes to its members (writes to members) from outside the class. This method is not called when members are updated from within class member code.
If a class has at least one public member declared (or inherits a class with at least one public member declared), then only those members declared as public can be accessed from outside the class, and from within the class only members explicitly declared can be accessed as well (unless the class also defines a memberGate()
method). In this way typographical errors in member names can be caught (at parse time if types are declared).
Within a class method definition, calls to methods in the same class hierarchy (of the current class or a base class) can be defined as follows:
[namespace_path::
]$.method_name([arg, ...])
For example:
# to call base class Mutex::lock() Thread::Mutex::$.lock(); # to call lock() in the current (or lower base) class $.lock();
This syntax can only be used to call methods in the current class or in base classes. This is because these calls are resolved at parse time, and only these classes are known and accessible at parse time. To call a derived class method from a base class, you must use the $self
variable to call the method, so that the call will be resolved at run-time, for example:
# this way, "member" can be resolved to a derived class method $self.member();
Calls to object methods can be made outside the class by using the above syntax as well. All such calls are resolved at run-time, therefore if the call is made to a private function outside the defining class, then a run-time METHOD-IS-PRIVATE
(if the method is private) or BASE-CLASS-IS-PRIVATE
(if the method resolves to a privately-inherited base class) exception will be raised.
Class inheritance is a powerful concept for easily extending and resuing object-oriented code, but is also subject to some limitations. This section will explain how class inheritance works in Qore.
Classes inherit the methods of a parent class by using the inherits as specified above. Multiple inheritance is supported; a single Qore class can inherit one or more classes. When a class is inherited by another class, it is called a base class. Private inheritance is speficied by including the keyword private before the inherited class name. When a class is privately inherited, it means that the inherited class' public members are treated as private members in the context of accesses outside the class.
Inheritance is public by default, to inherit a class privately, use the private keyword before the class name or class path to inherit.
It is not legal to directly inherit the same class more than once; that is; it is not legal to list the same class more than once after the inherits keyword. However, it is possible that a base class could appear more than once in the inheritance tree if that class is inherited separately by two or more classes in the tree. In this case, the base class will actually only be inherited once in the subclass, even though it appears in the inheritance tree more than once. This must be taken into consideration when designing class hierarchies, particularly if base class constructor parameters for that class are explicitly provided in a different way by the inheriting classes.
Class members only exist once for each object; therefore if classes in an inheritance tree have different uses for members with the same name, then a class hierarchy built of such classes will probably not function properly.
Subclasses can give explicit arguments to their base class constructors using a special syntax (only available to subclass constructors) similar to the C++ syntax for the same purpose as follows:
class_name
::constructor([[type] $var1, ...) :base_class_identifier
(expression(s)
)[, ...] {statements
; }
Here is a concrete example of giving arguments to an inherited base class:
class XmlRpcClient inherits Qore::HTTPClient { # calls the base class HTTPClient constructor, overrides the "protocols" key to "xmlrpc" constructor(hash $opts = hash()) : Qore::HTTPClient($opts + ( "protocols" : "xmlrpc" )) ... }
Because base class constructors are executed before subclass constructors, the only local variables in the constructor that can be referenced are those declared in the subclass constructor declaration (if any). What this means is that if you declare local variables in the expressions giving base class arguments, these local variables are not accessible from the constructor body.
Base classes that give explicit arguments to their base class constructors can be overridden by subclasses by simply listing the base class in the base class constructor list and providing new arguments.
Like Java, in Qore, objects are treated differently from all other data types in that they are by default passed as arguments to functions and methods by passing a copy of a reference to the object. That means that passing an object to a function that modifies the object will by default modify the original object and not a copy, however reassigning a local parameter variable assigned an object passed as an argument (that is only assigned to a local variable in the calling function) will not result in deleting the object, but rather decrement its scope reference count (note that if the object were created as a part of the call and reassigning the variable would cause the object's scope reference count to reach zero, then the object would be deleted in this case).
Assigning an object to a variable has the same effect; a copy of a reference to the object is assigned to the variable. This results in prolonging the object's scope (by owning a new copy of a reference to the object).
An example:
sub test2(any $x) { # we can modify the original object like so: $x.member = "tree"; # here we re-assign $x, but since the object is also assigned # to $o in the calling function, the object's scope is still # valid, and therefore nothing happens so the object $x = 1; } sub test() { my TestObject $o(); # here we pass a copy of a reference to the object in $o test2($o); # this will print out "ok\n", because the object is still # valid and the member has been set by test2() if ($o.member == "tree") print("ok\n"); } # when test() exits, the object in $o will go out of scope # and be deleted
If, however, an object is passed by reference, then the local variable of the called function that accepts the object owns the scope reference of the calling functions's variable.
An example:
sub test2(any $x) { # we can modify the original object like so: $x.member = "tree"; # here we re-assign $x, and since we own the only scope # reference to the object, the object will go out of # scope here and be deleted $x = 1; } sub test() { my TestObject $o(); # here we pass a reference to the object in $o test2(\$o); # the object has already been deleted in test2() and # therefore nothing will be printed out if ($o.member == "tree") print("ok\n"); }
Objects are automatically deleted when their scope-relevant reference count reaches zero (note that objects can be deleted manually at any time by using the delete operator). Whenever an object is deleted, the object's class' destructor method is run on the object.
The following affect objects' scope:
Variable Assignments
An object's automatic scope is prolonged as long as the object is assigned to a local variable.
Existence of a Closure Created Within the Object
Any closures created from within the object encapsulate the object's state (along with any local variables referenced within the closure) and also prolong the object's automatic scope as long as the closure exists.
Object Method Thread Launched Within the Object
If a member function thread was launched from within the object using the background operator, the object's automatic scope is prolonged to the life of the new thread. Object threads started externally to the object (i.e. not directly from an expression with the background operator within a method) will not prolong the scope of the object.
If an object with running threads is explicitly deleted, and this case is not handled in the object's destructor()
method (by ensuring that all other running threads terminate gracefully), exceptions will be thrown in other threads at any attempt to access the already-deleted object.
For more information about threading, please see the following section Threading
The fact that object threads and closures can prolong object scope means, for example, that objects assigned to local variables can exist for longer than the scope of their host variable if they have one or more methods running in other threads or if closures created from within the object still exist at the time the local variable goes out of scope.
To explicitly generate a copy of an object, the copy()
constructor must be called. This is a special method that exists implicitly for every class even if it is not explicitly defined (like constructor()
and destructor()
methods). The implicit behavior of the copy()
constructor is to create a new object with new members that are copies of the original members (except objects are once again referenced). Then, if any copy()
method exists, it will be executed in the new object, passing a reference to the old object as the first paramter.
In a class hierarchy copy()
methods are called in the same order as constructor()
methods.
Not all built-in classes can be copied. Classes not supporting copying will throw an exception when the copy()
methods are called. See the documentation for each class for more information.
A thread is an independent sequence of execution of Qore code within a Qore program or script. Each thread has a thread ID or TID.
The first thread of execution in a Qore program has TID 1. TID 0 is always reserved for the special signal handler thread.
The Qore language is designed to be thread-safe and Qore programs should not crash the Qore executable due to threading errors. Threading errors should only cause exceptions to be thrown or application errors to occur.
Threading functionality in Qore is provided by the operating system's POSIX threads library.
New threads are created with the background operator. This operator executes the expression given as an argument in a new thread and returns the TID of the new thread to the calling thread. This is most useful for calling user subroutines or object methods designed to run in a separate thread.
To terminate a thread, the thread_exit statement should be called, as calling the exit() function will terminate the entire UNIX process (and therefore all threads) immediately.
All global variables are shared in Qore programs, while local variables (declared with my) are generally local to each thread (and thus accessed without any mutual-exclusion locking), regardless of location. This means that if a variable is declared with my at the top level, it will actually have global scope, but also each thread will have its own copy of the variable. In effect, declaring a top-level local variable with my actually creates a global thread-local variable.
The following code gives an example of declaring a global thread-local variable by using my at the top-level:
%require-our sub t() { printf("x=%n\n", $x); } my $x = 2; t(); background t();
This will print out:
x=2 x=<NOTHING>
Note that the second time the local variable is accessed in the background thread, it has no value.
Due to the way Qore's local variables work, it is illegal to declare a top-level local variable after first block is parsed in the program; that is; if any call to parse() or Program::parse() is made in an existing program (where a top-level block already exists), and an attempt to declare a new top-level local variable is made, then a ILLEGAL-TOP-LEVEL-LOCAL-VARIABLE
parse exception will be raised.
Access to global variables in qore is wrapped in mutual-exclusion locks to guarantee safe access to global variable data in a multithreaded context. Local variables are thread-local and therefore not locked, except when referenced in a closure expression, in which case the local variable's scope is extended to that of the closure's, and all accesses to the bound local variable are made within mutual-exclusion locks as these variables may be used in multithreaded contexts.
An alternative to global thread-local variables is offered by the save_thread_data() and get_thread_data() functions (documented in Threading Functions).
The synchronized keyword can be used before subroutine or class method definitions in order to guarantee that the function or method call will only be executed in one thread at a time. As in Java, this keyword can also be used safely with recursive functions and methods (internally a Gate-like object is used to guarantee thread-exclusivity and allow recursion).
The following classes are useful when developing multi-threaded Qore programs:
Table 2.94. Classes Useful With Threading
Class | Description |
---|---|
A mutual-exclusion thread lock. | |
A recursive thread lock. | |
A read-write thread lock. | |
Allows Qore programs to block until a certain condition becomes true. | |
A blocking counter class. | |
A thread-safe, blocking queue class (useful for message passing). | |
DEPRECATED in favor of the Gate class: A recursive mutual-exclusion thread lock. | |
A simple, thread-atomic sequence object (increment-only). | |
A helper class to automatically release Mutex locks when the AutoLock object is deleted. | |
A helper class to automatically exit Gate locks when the AutoGate object is deleted. | |
A helper class to automatically release read locks when the AutoReadLock object is deleted. | |
A helper class to automatically release read locks when the AutoWriteLock object is deleted. |
The following functions assist writing safe and efficient multi-threaded Qore programs:
Table 2.95. Thread Functions
Function | Description |
---|---|
Saves a thread-local value against a key. | |
Retrieves the entire thread-local hash. | |
Retrieves a thread-local value based on a key. | |
Deletes the entire thread-local data hash. | |
Delete the value of a key in the thread-local data hash. | |
Gets the thread's TID (thread identifier) | |
Returns a list of TIDs of running threads | |
Returns the number of running threads |
Qore supports deadlock detection in complex locking scenarios and will throw a THREAD-DEADLOCK
exception rather than allow an operation to be performed that would cause a deadlock. Deadlock detection is implemented for internal locking (global variable and object access), synchronized methods and subroutinges, etc, as well as for all Qore threading classes.
Qore can only detect deadlocks when a lock resource acquired by one thread is required by another who holds a lock that the first thread also needs. Other errors such as forgetting to unlock a global lock and trying to acquire that lock in another thread cannot be differentiated from valid use of threading primitives and will result in a process that never terminates. However, common threading errors such as trying to lock the same Mutex twice in the same thread without unlocking it between the two Mutex::lock() calls are caught in Qore and exceptions are thrown. Additionally, locks are tracked as thread resources, so if a thread terminates while holding a lock, an exception will be thrown and the lock will be automatically released.
Exceptions are errors that can only be handled using a try catch block. Any exception that is thrown in a try block will immediately cause execution of that thread to begin with the first statement of the catch block, regardless of the position of the program pointer of the running thread, even if nested subroutines or object method calls have been made.
Exceptions can be thrown by the Qore system for a number of reasons, see the documentation for each function and object method for details.
Programmers can also throw exceptions explicitly by using the throw and rethrow statements.
Information about the exception, including the context in which the exception occurred, is saved in the exception hash, which can be retrieved by using a parameter variable in the catch block (for more information about try catch blocks, see try and catch statements).
The exception hash contains the following members:
Table 2.96. Exception Hash Keys
Name | Type | Description |
---|---|---|
| string | "System" or "User" depending on exception type |
| string | File name of file where exception occurred |
| integer | Line number where exception occurred |
| list of hashes | Backtrace information |
| any | This key is populated with the value of the first expression of the throw statement. For system exceptions, this is a string giving the exception code. |
| any | This key is populated with the value of the second expression of the throw statement (if a list was thrown). For system exceptions, this is a string giving a text description of the error. |
| any | This key is populated with the value of the third expression of the throw statement (if a list was thrown). For system exceptions, this is populated for some exceptions where additional information is provided. |
Table 2.97. Call Stack Description
Name | Type | Description |
---|---|---|
| string | function name |
| integer | line number |
| string | file name |
| string | Exception Type (ET_*) constants; see Exception Constants for values. |
| integer | Call Type (CT_*) constants; see Exception Constants for values. |
System exceptions always throw 2 values, populating the "err" and "desc" keys of the exception hash, giving the exception string code and the exception description string, respectively, and occassionally, depending on the function, the "arg" key may be populated with supporting information. User exceptions have no restrictions, any values given in the throw statement will be mapped to exception keys as per the table above.
See the on_exit, on_success statement, and on_error statement for statements that allow for exception-safe and exception-dependent cleanup in Qore code.
Classes that assist in exception-safe lock handling are the AutoLock class, the AutoGate class, the AutoReadLock class, and the AutoWriteLock class.
XML functionality in Qore is provided by the libxml2 library, which provides a powerful, stable, clean, and thread-safe basis for XML integration in Qore.
XML provides an excellent way to describe hierarchical data, and thanks to libxml2, Qore can allow for easy serialization and deserialization between XML strings and Qore data structures.
XML serialization (conversion from Qore data structures to XML strings) in Qore relies on the fact that Qore hashes retain insertion order, which means that conversion to and from Qore data structures and XML strings can be done without data loss and without reordering the XML elements. In general, XML serialization is relatively straighforward, but there are a few issues to be aware of, particularly regarding element attributes and lists. These issues are described in the following paragraphs.
First, a straightforward example:
$h = ( "record" : ( "name" : ( "first" : "Fred", "last" : "Smith" ) ) ); printf("%s\n", makeFormattedXMLString($h));
This produces the following result
<?xml version="1.0" encoding="UTF-8"?> <record> <name> <first>Fred</first> <last>Smith</last> </name> </record>
To set XML attributes, the Qore value must be a hash and the attributes are stored in another hash in the key ^attributes^
. That is; the value of the ^attributes^
key must be a hash, and each member of this hash will represent an attribute-value pair.
For example:
$h = ( "record" : ( "^attributes^" : ( "type" : "customer" ) , "name" : ( "first" : "Fred", "last" : "Smith" ) ) ); printf("%s\n", makeFormattedXMLString($h));
This produces the following results:
<?xml version="1.0" encoding="UTF-8"?> <record type="customer"> <name> <first>Fred</first> <last>Smith</last> </name> </record>
If instead we wanted to have text instead of child data under the "record" node, we must set the ^value^
key of the hash along with the ^attributes^
key as follows:
$h = ( "record" : ( "^attributes^" : ( "type" : "customer" ) , "^value^" : "NO-RECORD" ) ); printf("%s\n", makeFormattedXMLString($h));
Giving the following results:
<?xml version="1.0" encoding="UTF-8"?> <record type="customer">NO-RECORD</record>
Arrays are serialized with repeating node names as follows:
$h = ( "record" : ( "part" : ( "part-02-05", "part-99-23", "part-34-28" ) ) ); printf("%s\n", makeFormattedXMLString($h));
Producing the following results:
<?xml version="1.0" encoding="UTF-8"?> <record type="customer"> <part>part-02-05</part> <part>part-99-23</part> <part>part-34-28</part> </record>
It gets a little trickier when a key should repeated at the same level in an XML string, but other keys come between, for example, take the following XML string:
<?xml version="1.0" encoding="UTF-8"?> <para>Keywords: <code>this</code>, <code>that</code>, and <code>the_other</code>.</para>
It's not possible to use a list, because text is required in between. As described earlier, the ^value^
hash key can be used to serialize text in an XML string. In this case, we need to have several text nodes and several code
nodes in a mixed-up order to give us the XML string we want. Because qore hases have unique keys (we can't use the same key twice in the same hash), we resort to a key naming trick that allows us to virtually duplicate our key names and therefore arrive at the XML string we want. We do this by appending a '^' character to the end of the key name and then some unique text. When serializing hash keys, any text after (and including) the '^' character is ignored. For the special key name ^value^
, we do not need to duplicate the final '^' character. Instead we just add unique text to ensure that our hash can contain all the data we want and that it will be serialized in the right order to the XML string as follows:
$h = ( "para" : ( "^value^" : "Keywords: ", "code" : "this", "^value^1" : ", ", "code^1" : "that", "^value^2" : ", and ", "code^2" : "the_other", "^value^3" : "." ) ); printf("%s\n", makeFormattedXMLString($h));
By ignoring the text after the '^' character, the above code will serialize to the XML string we want. In general, by using this convention, we can properly serialize multiple out-of-order keys without losing data and still have unique names for our hash keys.
Note than when deserializing XML strings to Qore data structures, the above rules are applied in reverse. If any out-of-order duplicate keys are detected, Qore will automatically generate unique hash key names based on the above rules.
Also note that CDATA text will be generated if a hash key starts with '^cdata'; such text will not be processed for escape code substitution. When deserializing XML strings to qore data structures, CDATA text will be placed unmodified under such a hash key as well.
Table 2.98. Functions For XML Serialization and Deserialization
Function Name | Description |
---|---|
Serializes a hash into an XML string with formatting without an XML header. | |
Serializes a hash into an XML string with formatting and an XML header. | |
Serializes a hash into an XML string without an XML header or formatting. | |
Serializes a hash into a complete XML string with an XML header and without formatting. | |
parses an XML string as data (duplicate, out-of-order XML elements are collapsed into lists) and returns a Qore hash structure. | |
parses an XML string as data (duplicate, out-of-order XML elements are collapsed into lists) and validates against an XSD schema string and returns a Qore hash structure. | |
parses an XML string (XML element order is preserved by appending numeric suffixes to Qore hash key names when necessary) and returns a Qore hash structure. | |
parses an XML string (XML element order is preserved by appending numeric suffixes to Qore hash key names when necessary) and validates against an XSD schema string and returns a Qore hash structure. |
XML-RPC is a lightweight but powerful XML over HTTP web service protocol. Qore includes builtin support for this protocol. You can find more information about XML-RPC, including specifications and examples at http://xmlrpc.org.
Information about Qore's XML-RPC serialization can be found below.
Table 2.100. XML-RPC Serialization in Qore
Qore Type | XML-RPC Type | Description | |
---|---|---|---|
| direct conversion to UTF-8 string | ||
| If the integer requires more than 32 bits to represent, then it is sent as a string | ||
| direct conversion | ||
| direct conversion | ||
| Absolute date/time values will convert to the default time zone for the calling context for the output string if necessary. Note that relative date/time values (durations) will be serialized with the same format as absolute date/time values. | ||
| direct conversion | ||
| direct conversion | ||
| direct conversion | ||
all others | n/a | All other types will cause an |
Table 2.101. Functions Providing XML-RPC Functionality
Function Name | Description |
---|---|
Serializes a hash into an XML string formatted for an XML-RPC call with formatting. | |
Serializes a hash into an XML string formatted for an XML-RPC call with formatting, taking a single list argument for the argument list. | |
Serializes a hash into an XML string formatted for an XML-RPC fault response with formatting. | |
Serializes a hash into an XML string formatted for an XML-RPC response with formatting. | |
Serializes a hash into an XML string in XML-RPC value format with formatting. | |
Serializes a hash into an XML string formatted for an XML-RPC call without formatting. | |
Serializes a hash into an XML string formatted for an XML-RPC call without formatting, taking a single list argument for the argument list. | |
Serializes a hash into an XML string formatted for an XML-RPC fault response without formatting. | |
Serializes a hash into an XML string formatted for an XML-RPC response without formatting. | |
Serializes a hash into an XML string in XML-RPC value format without formatting. | |
deserializies an XML-RPC call string, returning a Qore hash respresenting the call information. | |
deserializies an XML-RPC response string, returning a Qore hash respresenting the response information. | |
deserializies an XML-RPC value tree, returning a Qore hash respresenting the information. |
Qore implements safe signal handling. Signals do not interrupt Qore threads, rather Qore uses a special signal handling thread with TID 0, dedicated to handling signals. The signal handling thread uses very few resources; it stays blocked (using no processor time and very little memory) until a signal with a Qore signal handler is raised; it then executes the handler and resumes waiting for signals.
Because the signal Qore's signal handling thread is not a normal thread, it does not affect num_threads() and does not appear in the list returned by thread_list().
Internally, Qore masks (blocks) all signals in every thread except the signal handling thread. In the signal handling thread, all signals are unmasked, except those with Qore-language handlers, then an internal call to sigwait()
is made to receive and process signals raised one at a time.
Qore-language signal handlers are installed by passing a signal constant and a closure or call reference to the code to execute when the signal is raised to the set_signal_handler() function. Signal handlers are removed by passing a signal constant to the remove_signal_handler() function.
When a signal has been raised and the signal handler is called, the signal number is passed as the sole argument to the signal handler code.
Table 2.102. Signal Handling Functions
Function Name | Description |
---|---|
Sets up a Qore signal handler using a signal number and a call reference. | |
Removes a Qore signal handler using a signal number. |
See Signal Constants for a list of signal constants and Signal Mapping Hash Constants for two hash constants that can be used to map signal names to numbers and vice-versa. Note that signal constants are system-dependent; not all signals will be available in all systems; in case of doubt, see your system documentation for information on which signals are available.
The above functions are atomic, meaning that when they return to the caller, the signal handling thread has already acknowledged the changes.
It is not possible to set signal masks per thread; all signals are delivered to the signal handling thread. Signals not handled with a Qore signal handler are handled with their default action. It is not possible to catch SIGPIPE
. SIGPIPE
is always ignored in Qore.
Some issues to be aware of in signal handlers:
Thread-local storage is not persistent in signal handlers; it is deleted after every signal handler is run.
A signal handler that does not terminate will block the execution of further signal handlers and will block signal handling changes (such as updating the signal mask), resulting in a Qore process that must be killed manually. Because all Qore signal handling code is executed serially in a single thread, Qore signal handlers should execute and return quickly to give time to execute other handlers.
Signal handlers may install or remove signal handlers using set_signal_handler() or remove_signal_handler(), however in this case, changes to signal handling are made after the signal handler returns.
Signal handlers cannot call fork(); any attempt to call fork() in a signal handler will result in an an exception.
fork() (called externally to a signal handler) is handled as follows: the signal handling thread is terminated, fork()
is executed, all signals are masked in the primary thread in the new process, then the signal handling thread is resumed in both processes. No signals can be received or handled while the signal handling thread is terminated. After the fork()
, the new process will have exactly the same signal handlers and signal masks as the parent process.
Unhandled exceptions in signal handlers will simply be displayed on stderr as an unhandled exception and will have no other effect on Qore or Qore code (in particular, unhandled exceptions will not cause the signal handling thread to terminate).
If a signal handler executes the thread_exit statement, execution of the signal handler will terminate immediately, but the signal handling thread will not be stopped. Execution of further signal handlers (including that for the same signal being handled when thread_exit is executed) will not be affected.
Qore supports a simple event-handling mechanism to provide notification and details of socket and network events in higher-level classes. Classes currently supporting events are the Socket, HTTPClient, and FtpClient classes.
See Event Constants for a list of all event constants; details about each event are documented in the following sections.
Event information is placed on the event queue (which must be a Queue object) in the form of a hash. Each event has at least the following keys:
Table 2.103. Event Hash Common Keys
Key | Value |
---|---|
| This key holds the event code; see information for individual events in the following sections |
| This key holds the event source code |
| The value of this key is a unique integer that can be used to uniquely identify the object generating the event. |
EVENT_PACKET_READ
SOURCE_SOCKET
This event is raised immediately after a network packet is received. The event hash contains the following keys:
Table 2.104. EVENT_PACKET_READ
Event Hash
Key | Value |
---|---|
|
|
|
|
| A unique integer ID for the socket object. |
| The number of bytes read in the packet. |
| The total number of bytes read in the read loop. |
[ | The total number of bytes to read in the read loop (this key is only present if the total number of bytes to read is known). |
EVENT_PACKET_SENT
SOURCE_SOCKET
This event is raised immediately after a network packet is sent. The event hash contains the following keys:
Table 2.105. EVENT_PACKET_SENT
Event Hash
Key | Value |
---|---|
|
|
|
|
| A unique integer ID for the socket object. |
| The file descriptor number of the socket. |
| The number of bytes sent in the packet. |
| The total number of bytes sent in the send loop. |
| The total number of bytes to send in the send loop. |
EVENT_HTTP_CONTENT_LENGTH
SOURCE_HTTPCLIENT
This event is raised immediately after an HTTP header is received containing a content length header line, but before the message body is received. The event hash contains the following keys:
Table 2.106. EVENT_HTTP_CONTENT_LENGTH
Event Hash
Key | Value |
---|---|
|
|
|
|
| A unique integer ID for the socket object. |
| The number of bytes given for the content length. |
EVENT_HTTP_CHUNKED_START
SOURCE_HTTPCLIENT
This event is raised after receiving an HTTP header with Transfer-Encoding
set to chunked
and before the chunked data is read. The event hash contains the following keys:
Table 2.107. EVENT_HTTP_CHUNKED_START
Event Hash
Key | Value |
---|---|
|
|
|
|
| A unique integer ID for the socket object. |
EVENT_HTTP_CHUNKED_END
SOURCE_HTTPCLIENT
This event is raised after all chunked data is read from the socket. The event hash contains the following keys:
Table 2.108. EVENT_HTTP_CHUNKED_END
Event Hash
Key | Value |
---|---|
|
|
|
|
| A unique integer ID for the socket object. |
EVENT_HTTP_REDIRECT
SOURCE_HTTPCLIENT
This event is raised after a redirect response is received from an HTTP server. The event hash contains the following keys:
Table 2.109. EVENT_HTTP_REDIRECT
Event Hash
Key | Value |
---|---|
|
|
|
|
| A unique integer ID for the socket object. |
| The redirect location given by the HTTP server |
[ | Any status message sent by the HTTP server; if no message was sent, then this key will not be present in the event hash. |
EVENT_CHANNEL_CLOSED
SOURCE_SOCKET
This event is raised immediately after the socket is closed. The event hash contains the following keys:
Table 2.110. EVENT_CHANNEL_CLOSED
Event Hash
Key | Value |
---|---|
|
|
|
|
| A unique integer ID for the socket object. |
EVENT_DELETED
SOURCE_SOCKET
This event is raised when the socket object is deleted. The event hash contains the following keys:
Table 2.111. EVENT_DELETED
Event Hash
Key | Value |
---|---|
|
|
|
|
| A unique integer ID for the socket object. |
EVENT_FTP_SEND_MESSAGE
SOURCE_FTPCLIENT
This event is raised immediately before a message is sent on the FTP control channel. The event hash contains the following keys:
Table 2.112. EVENT_FTP_SEND_MESSAGE
Event Hash
Key | Value |
---|---|
|
|
|
|
| A unique integer ID for the socket object. |
| A string giving the FTP command sent (ex: |
[ | The argument to the command; if no argument is sent, then this key will not be present. |
EVENT_FTP_MESSAGE_RECEIVED
SOURCE_FTPCLIENT
This event is raised immediately after a message is received on the FTP control channel. The event hash contains the following keys:
Table 2.113. EVENT_FTP_MESSAGE_RECEIVED
Event Hash
Key | Value |
---|---|
|
|
|
|
| A unique integer ID for the socket object. |
| A string giving the FTP command sent (ex: |
[ | The argument to the command; if no argument is sent, then this key will not be present. |
EVENT_HOSTNAME_LOOKUP
SOURCE_SOCKET
This event is raised immediately before a hostname lookup is made. The event hash contains the following keys:
Table 2.114. EVENT_HOSTNAME_LOOKUP
Event Hash
Key | Value |
---|---|
|
|
|
|
| A unique integer ID for the socket object. |
| A string giving the name to be looked up. |
EVENT_HOSTNAME_RESOLVED
SOURCE_SOCKET
This event is raised immediately after a successful hostname resolution. The event hash contains the following keys:
Table 2.115. EVENT_HOSTNAME_RESOLVED
Event Hash
Key | Value |
---|---|
|
|
|
|
| A unique integer ID for the socket object. |
| A string giving the network address the name was resolved to. |
EVENT_HTTP_SEND_MESSAGE
SOURCE_HTTPCLIENT
or SOURCE_SOCKET
This event is raised immediately before an HTTP message is sent. The event hash contains the following keys:
Table 2.116. EVENT_HTTP_SEND_MESSAGE
Event Hash
Key | Value |
---|---|
|
|
|
|
| The first string in the HTTP message (ex: |
| A hash of all headers to send in the message. |
EVENT_HTTP_MESSAGE_RECEIVED
SOURCE_HTTPCLIENT
or SOURCE_SOCKET
This event is raised immediately after an HTTP message is received. The event hash contains the following keys:
Table 2.117. EVENT_HTTP_MESSAGE_RECEIVED
Event Hash
Key | Value |
---|---|
|
|
|
|
| A hash of all headers received in the message, plus the following headers giving additional information about the message: |
EVENT_HTTP_FOOTERS_RECEIVED
SOURCE_HTTPCLIENT
This event is raised immediately after HTTP footers are received after receiving chunked data. The event hash contains the following keys:
Table 2.118. EVENT_HTTP_FOOTERS_RECEIVED
Event Hash
Key | Value |
---|---|
|
|
|
|
| A hash of all footers received in the message. |
EVENT_HTTP_CHUNKED_DATA_RECEIVED
SOURCE_HTTPCLIENT
This event is raised immediately after chunked data is received. The event hash contains the following keys:
Table 2.119. EVENT_HTTP_CHUNKED_DATA_RECEIVED
Event Hash
Key | Value |
---|---|
|
|
|
|
| An integer giving the number of bytes read in the chunk. |
| An integer giving the total number of bytes of chunked data read in the current message. |
EVENT_HTTP_CHUNK_SIZE
SOURCE_HTTPCLIENT
This event is raised immediately after chunk information is received providing the size of the next chunk. The event hash contains the following keys:
Table 2.120. EVENT_HTTP_CHUNK_SIZE_RECEIVED
Event Hash
Key | Value |
---|---|
|
|
|
|
| An integer giving the number of bytes in the next chunk. |
| An integer giving the total number of bytes of chunked data read in the current message. |
EVENT_CONNECTING
SOURCE_SOCKET
This event is raised immediately before a socket connection is attempted. The event hash contains the following keys:
Table 2.121. EVENT_CONNECTING
Event Hash
Key | Value |
---|---|
|
|
|
|
| A unique integer ID for the socket object. |
| The type of address for the socket; one of the Network Address Constants. |
| The target address for the connection. |
[ | The target port for the connection; if not applicable for the address family then this hash key is not included. |
EVENT_CONNECTED
SOURCE_SOCKET
This event is raised immediately after a socket connection is established. The event hash contains the following keys:
Table 2.122. EVENT_CONNECTED
Event Hash
Key | Value |
---|---|
|
|
|
|
| A unique integer ID for the socket object. |
EVENT_START_SSL
SOURCE_SOCKET
This event is raised immediately before SSL negotiation is attempted. The event hash contains the following keys:
Table 2.123. EVENT_START_SSL
Event Hash
Key | Value |
---|---|
|
|
|
|
| A unique integer ID for the socket object. |
EVENT_SSL_ESTABLISHED
SOURCE_SOCKET
This event is raised immediately after SSL negotiation has been successfully established. The event hash contains the following keys:
Table 2.124. EVENT_SSL_ESTABLISHED
Event Hash
Key | Value |
---|---|
|
|
|
|
| A unique integer ID for the socket object. |
| A string giving the name of the cipher algorithm used for the connection. |
| A string giving the version of the cipher algorithm used for the connection. |
EVENT_OPEN_FILE
SOURCE_FILE
This event is raised immediately before a file is opened. The event hash contains the following keys:
Table 2.125. EVENT_OPEN_FILE
Event Hash
Key | Value |
---|---|
|
|
|
|
| A unique integer ID for the file object. |
| The file's name. |
| The flags used to open the file. |
| The mode to open the file with. |
| The character encoding given used for reading from or writing to the file. |
EVENT_FILE_OPENED
SOURCE_FILE
This event is raised immediately after a file has been successfully opened. The event hash contains the following keys:
Table 2.126. EVENT_FILE_OPENED
Event Hash
Key | Value |
---|---|
|
|
|
|
| A unique integer ID for the file object. |
| The file's name. |
| The flags used to open the file. |
| The mode to open the file with. |
| The character encoding given used for reading from or writing to the file. |
EVENT_DATA_READ
SOURCE_FILE
This event is raised immediately after data is read from a file. The event hash contains the following keys:
Table 2.127. EVENT_DATA_READ
Event Hash
Key | Value |
---|---|
|
|
|
|
| A unique integer ID for the file object. |
| The number of bytes read from the file. |
| The total number of bytes read in the read loop. |
| The total number of bytes to read in the read loop. |
EVENT_DATA_WRITTEN
SOURCE_FILE
This event is raised immediately after data is written from a file. The event hash contains the following keys:
Table 2.128. EVENT_DATA_WRITTEN
Event Hash
Key | Value |
---|---|
|
|
|
|
| A unique integer ID for the file object. |
| The number of bytes written to the file. |
| The total number of bytes written in the write loop. |
| The total number of bytes to write in the write loop. |
This section describes the built-in subroutines in the Qore language making up the system function library. Following is a list of function categories, and below there is an alphabetically-ordered list of all Qore built-in functions.
Each builtin function or method has flags that describe its properties. The following table provides the key to the flags as given in the function and method lists.
Table 3.2. Code Flags
Abbr | Description |
---|---|
| Code with this flag makes no calculations, but rather returns a constant value. This flag is given to function and method variants that return a default value depending on the type of argument(s). When variants with this flag are resolved at parse time, a |
| Code with this flag makes no calculations, but rather returns a constant value. This flag is given to function and method variants that return a default value depending on the type of argument(s). When variants with this flag are resolved at parse time, a |
| Code with this flag is safe to be used when assigning a constant, because it has no side effects and normally does not throw an exception (at least in the context of assigning a constant). |
| Code with this flag is deprecated and will be removed in a future version of Qore; if a variant with this flag is resolved at parse time, a |
Table 3.3. System Function Library
Function Name |
Ex? |
Brief Description |
---|---|---|
N |
aborts the process | |
N |
Returns the absolute value of the argument passed | |
N |
Returns the arc cosine of the number passed in radians | |
N |
Returns the arc sine of the number passed in radians. | |
N |
Returns the arc tangent of the number passed in radians. | |
Y |
Executes a process and returns a string of the output (stdout only) | |
N | Returns a string giving the last element of a file path. | |
| N | Returns a binary data type of the data passed. |
| Y | Returns a string created from the binary data passed. |
|
N |
Returns the byte position of a substring within a string and takes an optional starting offset |
|
Y |
Encrypts data using the Cipher Block Chaining function for the blowfish algorithm. |
|
Y |
Decrypts data using the Cipher Block Chaining function for the blowfish algorithm. |
|
Y |
Decrypts data to a string using the Cipher Block Chaining function for the blowfish algorithm. |
|
N |
Converts the argument to a boolean value. |
| N | Returns the byte position of a substring within a string as searched from the end of the string and takes an optional starting offset |
| Y | Uncompresses the given data with the bzip2 algorithm and returns the uncompressed data as a binary. |
| Y | Uncompresses the given data with the bzip2 algorithm and returns the uncompressed data as a string. |
Y | Compresses the given data with the bzip2 algorithm and returns the uncompressed data as a binary. | |
| Y | Calls a builtin function identified by the first string argument and returns the return value, passing the remaining arguments after the function name to the function |
| Y | Calls a builtin function identified by the first string argument and returns the return value, using the argument after the function name as a list of arguments to pass to the function. |
| Y | Calls a function, closure, or call reference and returns the return value, passing the remaining arguments after the function name to the function (or call reference). |
| Y | Calls a function, closure, or call reference and returns the return value, using the argument after the function name as a list of arguments to pass to the function, closure, or call reference. |
|
Y |
calls a method given by a string of the object passed, passing the remaining arguments to the method as arguments |
|
Y |
calls a method given by a string of the object passed, using the argument after the method name as the list of arguments to pass to the method |
|
Y |
Encrypts data using the Cipher Block Chaining function for the CAST5 algorithm. |
|
Y |
Decrypts data using the Cipher Block Chaining function for the CAST5 algorithm. |
|
Y |
Decrypts data to a string using the Cipher Block Chaining function for the CAST5 algorithm. |
N |
Returns the cube root of the number passed. | |
N | Returns a value rounded up to the next highest integer | |
Y | Changes the current working directory. | |
Y | Changes the mode of a file. | |
N | Removes the trailing end-of-line indicator from a string and returns the new string (also see the chomp operator); also accepts variable references to do modifications in-place. | |
N | Changes the user and group owners of a file (if the current user has permission to do so), follows symbolic links. | |
N | Returns a string containing a single ASCII character represented by the numeric value passed. | |
|
N |
Returns the system time in microseconds (1/1000000 second intervals) since Jan 1, 1970 00:00:00Z. |
|
N |
Returns the system time in milliseconds (1/1000 second intervals) since Jan 1, 1970 00:00:00Z. |
|
N |
Returns the system time in nanoseconds (1/1000000000 second intervals) since Jan 1, 1970 00:00:00. |
Y | Performs zlib-based "deflate" data compression (RFC 1951) and returns a binary object of the compressed data. | |
| Y | Performs explicit string character encoding conversions. |
N |
Returns the cosine of the number in radians passed. | |
N |
Returns the hyperbolic cosine of the number passed. | |
| N | Converts the argument passed to a date. |
N | Converts an integer argument as a millisecond offset from January 1, 1970Z to a date. | |
N | Converts an integer argument as a microsecond offset from January 1, 1970Z to a date. | |
N |
Returns a relative date in days for date arithmetic. | |
| N | Decodes percent numeric codes in a URL string and returns the decoded string. |
N |
Deletes all keys in the thread-local data hash. | |
| N | Deletes the data associated to one or more keys in the thread-local data hash (destroys any objects as well). |
|
Y |
Encrypts data using the Cipher Block Chaining function for the DES algorithm. |
|
Y |
Decrypts data using the Cipher Block Chaining function for the DES algorithm. |
|
Y |
Decrypts data using the Cipher Block Chaining function for the DES algorithm. |
|
Y |
Encrypts data using the Cipher Block Chaining function for the two-key triple DES algorithm. |
|
Y |
Decrypts data using the Cipher Block Chaining function for the two-key triple DES algorithm. |
|
Y |
Decrypts data to a string using the Cipher Block Chaining function for the two-key triple DES algorithm. |
|
Y |
Encrypts data using the Cipher Block Chaining function for the three-key triple DES algorithm. |
|
Y |
Decrypts data using the Cipher Block Chaining function for the three-key triple DES algorithm. |
|
Y |
Decrypts data to a string using the Cipher Block Chaining function for the three-key triple DES algorithm. |
|
Y |
Encrypts data using the Cipher Block Chaining function for RSA's DESX algorithm. |
|
Y |
Encrypts data using the Cipher Block Chaining function for RSA's DESX algorithm. |
|
Y |
Encrypts data to a string using the Cipher Block Chaining function for RSA's DESX algorithm. |
Y | Returns the DSS message digest of the supplied argument as a hex string (for strings, the trailing null character is not included in the digest) | |
Y | Returns the DSS message digest of the supplied argument as a binary object (for strings, the trailing null character is not included in the digest) | |
Y | Returns the DSS1 message digest of the supplied argument as a hex string (for strings, the trailing null character is not included in the digest) | |
Y | Returns the DSS1 message digest of the supplied argument as a binary object (for strings, the trailing null character is not included in the digest) | |
N | Returns the value of the system "errno" variable, holding the last error code generated by a system call | |
N | Replaces the current process image with another. | |
|
N |
Returns |
N |
Exits the program | |
N |
Returns the value of e raised to the power of the argument passed | |
N |
Returns the value of 2 raised to the power of the argument passed | |
N |
Returns an equivalent of exp(x) - 1 | |
Y |
"field" printf, field width specifiers are respected. Returns string printed. | |
Y |
"field" sprintf(), field width specifiers are respected | |
|
N |
Returns the argument converted to a floating-point number |
N |
Returns a value rounded down to the nearest integer | |
N | Flushes output to the console output with print(), printf(), etc | |
| N | Returns a string tagged with the given character encoding; does not actually change the string data; use only in the case that a string is tagged with the wrong encoding. |
N |
Creates a duplicate of the current process | |
| N |
Allows dates to be formatted |
| N |
Allows numbers to be formatted with more options than sprintf() |
|
N |
Returns "builtin", "user", or NOTHING according to the function name passed |
|
N |
Returns the entire thread data hash. |
N | Returns the byte value at the given byte offset or NOTHING if the offset is not legal for the given data. | |
N | Returns an integer value representing the days value of the date passed (can be either a relative or absolute date). | |
| N | Returns the name of the default character encoding for the Qore library. |
| N | Returns an integer giving the duration in microseconds as described by the argument; if the argument is a relative date, then it is converted to microseconds, if it is absolute, then a number of microseconds between the current time and the time given is returned. |
| N | Returns an integer giving the duration in milliseconds as described by the argument; if the argument is a relative date, then it is converted to milliseconds, if it is absolute, then a number of milliseconds between the current time and the time given is returned. |
| N | Returns an integer giving the duration in seconds as described by the argument; if the argument is a relative date, then it is converted to seconds, if it is absolute, then a number of seconds between the current time and the time given is returned. |
|
N |
Returns a string describing the character encoding of the string passed. |
| N |
Returns the number of seconds after Jan 1, 1970, 00:00:00Z for the date/time value passed. |
N |
Returns an integer value representing the hours value of the date passed (can be either a relative or absolute date). | |
|
N |
Returns an integer value representing the microseconds value of the date passed (can be either a relative or absolute date). |
|
N |
Returns a date/time value representing midnight on the date passed (strips the time from the date passed and returns the new value) |
|
N |
Returns an integer value representing the milliseconds value of the date passed (can be either a relative or absolute date). |
|
N |
Returns an integer value representing the minutes value of the date passed (can be either a relative or absolute date). |
|
N |
Returns an integer value representing the months value of the date passed (can be either a relative or absolute date). |
| N | Returns a hash of build and version information for the qore library. |
| N | Returns a list of hashes giving information about qore library options. |
| N | Returns an integer value representing the seconds value of the date passed (can be either a relative or absolute date). |
| N | Returns a string giving the path (directory and filename) from which the current script was executed (if known). |
| N | Returns a string giving the directory from which the current script was executed (if known). |
| N | Returns a string giving the filename of the current script (if known). |
|
N |
Returns the value of the thread-local data attached to the key passed |
| N | Returns the 16-bit value at the given 2-byte offset or NOTHING if the offset is not legal for the given data; assumes MSB byte order. |
| N | Returns the 16-bit value at the given 2-byte offset or NOTHING if the offset is not legal for the given data; assumes LSB byte order. |
| N | Returns the 32-bit value at the given 4-byte offset or NOTHING if the offset is not legal for the given data; assumes LSB byte order.. |
| N | Returns the 64-bit value at the given 8-byte offset or NOTHING if the offset is not legal for the given data; assumes LSB byte order.. |
N |
Returns an integer value representing the years value of the date passed (can be either a relative or absolute date). | |
|
N | Returns a hash of call stacks keyed by each TID (thread ID). |
N | Returns the byte value withing the string or binary object passed, or if the offset is out of range, returns NOTHING. | |
| N | Returns the class name of the object passed. |
N | Returns the name of the current working directory or NOTHING if an error occurs. | |
Y | Returns the name of the current working directory and throws an exception if an error occurs. | |
|
Y |
Retuns an absolute date value in the local time zone for the ISO-8601 calendar week information passed (year, week number, optional: day); throws an exception if the arguments are invalid. |
|
N |
Returns an integer representing the day of the week for the absolute date passed (0=Sunday, 6=Saturday) |
|
N |
Returns an integer representing the ordinal day number in the year for the absolute date passed |
| N | Returns an integer representing the capabilities of a DBI driver or NOTHING if the driver cannot be loaded. |
| N | Returns a list of codes representing the capabilities of a DBI driver of NOTHING if the driver cannot be loaded. |
| N | Returns a list of strings of DBI drivers currently loaded or NOTHING if no drivers have been loaded. |
N |
Returns the effective group ID of the current process. | |
N |
Returns the effective user ID of the current process. | |
|
N |
Returns a list of strings of the builtin and module-supplied features of Qore. |
N |
Retrieves the value of an environment variable or NOTHING if the variable is not set | |
N |
Returns the real group ID of the current process. | |
N |
Returns a hash representing the group information of the group name passed or NOTHING if the group name is not found. | |
N |
Returns a hash representing the group information of the group name passed; throws an exception if the group name is not found. | |
N |
Returns a hash representing the group information of the group ID passed or NOTHING if the group ID is not found. | |
N |
Returns a hash representing the group information of the group ID passed; throws an exception if the group ID is not found. | |
| N | Returns the official hostname corresponding to the network addressed passed or NOTHING if the address cannot be resolved. |
| N | Returns all host information corresponding to the network address as a hash or NOTHING if the address cannot be resolved. |
| N | Returns the first network address corresponding to the hostname as a string or NOTHING if the name cannot be resolved. |
| N | Returns all host information corresponding to the hostname as a hash or NOTHING if the name cannot be resolved. |
| Y | Returns the hostname of the system; throws an exception if an error occurs. |
|
N |
Returns an integer representing the ISO-8601 day of the week for the absolute date passed (1=Monday, 7=Sunday) |
|
N |
Returns a hash representing the ISO-8601 calendar week information for the absolute date passed (hash keys: year, week, day) |
|
N |
Returns a string representing the ISO-8601 calendar week information for the absolute date passed (ex: 2006-01-01 = "2005-W52-7") |
|
N |
Returns a list of strings of the names of the public and private methods of the class of the object passed as a parameter (does not return base class method names). |
|
N |
Returns a list of hashes describing the currently-loaded Qore modules. |
N |
Returns the PID (process ID) of the current process. | |
N | Returns the parent PID of the current process. | |
N |
Returns a hash representing the user information of the username passed or NOTHING if the username is not found. | |
N |
Returns a hash representing the user information of the username passed; throws an exception if the username is not found. | |
N |
Returns a hash representing the user information of the user ID passed or NOTHING if the user ID is not found. | |
N |
Returns a hash representing the user information of the user ID passed; throws an exception if the user ID is not found. | |
N |
Returns the Qore thread ID (TID) of the current thread. | |
N |
Returns the real user ID of the current process. | |
| N | Returns the 32-bit value at the given 4-byte offset or NOTHING if the offset is not legal for the given data. |
N |
Returns a list of files matching the string argument or NOTHING if the call to | |
| N |
Returns a date/time value in UTC (GMT). |
| Y | Uncompresses data compressed with the "gzip" algorithm (RFC 1952) using zlib functions and returns a binary object. |
| Y | Uncompresses data compressed with the "gzip" algorithm (RFC 1952) using zlib functions and returns a string. |
| Y | Performs zlib-based "gzip" data compression (RFC 1952) and returns a binary object of the compressed data. |
|
N |
Converts an object or a list to a hash; otherwise returns an empty hash. |
|
N |
Returns a list of all the values in the hash argument passed. |
Y | Returns an integer for a hexadecimal string value; throws an exception if non-hex digits are found. | |
N | Returns a hash of information about the file corresponding to the pathname argument; does not follow symbolic links (returns information about symbolic links). Returns NOTHING if the | |
N |
Returns a relative date in hours to be used in date arithmetic. | |
N | Returns a hash of information about the file corresponding to the pathname argument; follows symbolic links. Returns NOTHING if the | |
|
N |
Returns a string with any HTML escape codes translated to the original characters |
| N |
Returns a string with any characters that can be escaped translated to HTML escape codes. |
|
N |
Returns the length of the hypotenuse of a right-angle triangle with sides given as the two arguments. |
| N | Returns the character position of a substring within a string and takes an optional starting offset |
N | Returns | |
| N | Returns |
N |
Returns the argument converted to an integer | |
N |
Returns | |
N |
Returns | |
|
N |
Returns |
|
N |
Returns |
N |
Returns | |
N |
Returns | |
|
N |
Returns |
N |
Returns | |
N |
Returns | |
N |
Returns | |
|
N |
Returns |
N |
Returns | |
|
N |
Returns |
|
N |
Creates a string from a list and separator character |
N |
Sends a signal to a process (default: SIGHUP) | |
N | Changes the user and group owners of a file (if the current user has permission to do so), does not follow symbolic links. | |
|
N |
Returns the length in characters for the string passed. |
N |
Returns a list with the argument passed as the first element (or an empty list if no argument is passed) | |
| Y | Loads a Qore module at run-time if the feature name is not already present in the current Program object. |
|
N |
Returns a date value in localtime; if an argument is passed, then the date is created based on the value of the argument passed, for an integer, it is the number of seconds after Jan 1, 1970, 00:00:00Z (UTC). |
N |
Returns the base 10 logarithm of the value passed | |
N |
Returns the natural logarithm of the value passed plus 1 | |
N |
Returns the exponent of a number. | |
N |
Returns a list of filesystem values for the file or symbolic link passed or NOTHING if the call to | |
| N | Returns a base64-encoded representation of a binary object or a string. |
|
Y |
Creates a JSON-RPC 1.1 error response string from the parameters passed, formatted with line breaks for easier readability. |
|
Y |
Creates a generic JSON-RPC error response string from the parameters passed, formatted with line breaks for easier readability. |
|
Y |
Creates a JSON-RPC request string from the parameters passed, formatted with line breaks for easier readability. |
|
Y |
Creates a JSON-RPC response string from the parameters passed, formatted with line breaks for easier readability. |
|
Y |
Serializes qore data into a JSON string, formatted with line breaks for easier readability. |
|
Y |
Serializes a hash into an XML string with formatting and without an XML header. |
| Y | Serializes the arguments into an XML string for an XML-RPC call with formatting. |
| Y | Serializes the arguments into an XML string for an XML-RPC call with formatting, taking an initial string argument to give the encoding for the created XML. |
| Y | Serializes the arguments into an XML string formatted for an XML-RPC call with formatting, taking a single list argument for the argument list. |
| Y | Serializes the arguments into an XML string formatted for an XML-RPC call with formatting, taking an initial string argument to give the encoding for the created XML, followed by the method name and a single list argument for the argument list. |
| Y | Serializes the arguments into an XML string formatted for an XML-RPC fault response with whitespace formatting. |
| Y | Serializes the arguments into an XML string formatted for an XML-RPC fault response with whitespace formatting, taking an initial string argument to give the encoding for the created XML. |
| Y | Serializes the arguments into an XML string formatted for an XML-RPC response with whitespace formatting; if no arguments are passed, then NOTHING is returned. |
| Y | Serializes the arguments into an XML string formatted for an XML-RPC response with whitespace formatting, taking an initial string argument to give the encoding for the created XML. If no arguments after the encoding string are passed, then NOTHING is returned. |
|
Y |
Serializes the arguments into an XML string in XML-RPC Value format with whitespace formatting. |
|
Y |
Serializes a hash into an XML string with formatting and an XML header. |
| N | Returns a hex-encoded representation of a binary object or a string. |
|
Y |
Creates a JSON-RPC 1.1 error response string from the parameters passed, without any line breaks. |
|
Y |
Creates a generic JSON-RPC error response string from the parameters passed, without any line breaks. |
|
Y |
Creates a JSON-RPC request string from the parameters passed, without any line breaks. |
|
Y |
Creates a JSON-RPC response string from the parameters passed, without any line breaks. |
|
Y |
Serializes qore data into a JSON string, without any line breaks. |
|
Y |
Serializes a hash into an XML string without an XML header or formatting. |
| Y | Serializes the arguments into an XML string formatted for an XML-RPC call without formatting. |
| Y | Serializes the arguments into an XML string formatted for an XML-RPC call without formatting, taking an initial string argument to give the target character encoding for the XML string. |
| Y | Serializes the arguments into an XML string formatted for an XML-RPC call without formatting, taking a single list argument for the argument list. |
| Y | Serializes the arguments into an XML string formatted for an XML-RPC call without formatting, taking an initial string argument to give the target character encoding for the XML string followed by a list argument for the argument list. |
| Y | Serializes the arguments into an XML string formatted for an XML-RPC fault response without formatting. |
| Y | Serializes the arguments into an XML string formatted for an XML-RPC fault response without formatting, taking an initial string argument to give the target character encoding for the XML string. |
| Y | Serializes the arguments into an XML string formatted for an XML-RPC response without formatting; if no arguments are passed then NOTHING is returned. |
| Y | Serializes the arguments into an XML string formatted for an XML-RPC response without formatting, taking an initial string argument to give the target character encoding for the XML string. If no arguments after the encoding string are passed, then NOTHING is returned. |
|
Y |
Serializes the arguments into an XML string in XML-RPC Value format without formatting. |
| Y | Serializes a hash into a complete XML string with an XML header and without formatting. |
N | Returns the maximum value in a list (see also min()); one variant takes an optional callback reference to process lists of complex data types. | |
Y |
Returns the MD2 message digest of the supplied argument as a hex string (for string arguments, the trailing null character is not included in the digest) | |
Y |
Returns the MD2 message digest of the supplied argument as a binary object (for strings, the trailing null character is not included in the digest) | |
Y |
Returns the MD4 message digest of the supplied argument as a hex string (for strings, the trailing null character is not included in the digest) | |
Y |
Returns the MD4 message digest of the supplied argument as a binary object (for strings, the trailing null character is not included in the digest) | |
Y |
Returns the MD5 message digest of the supplied argument as a hex string (for strings, the trailing null character is not included in the digest) | |
Y |
Returns the MD5 message digest of the supplied argument as a binary object (for strings, the trailing null character is not included in the digest) | |
Y |
Returns the MDC2 message digest of the supplied argument as a hex string (for strings, the trailing null character is not included in the digest) | |
Y |
Returns the MDC2 message digest of the supplied argument as a binary object (for strings, the trailing null character is not included in the digest) | |
| N | Returns a relative date in microseconds to be used in date arithmetic. |
| N | Returns a relative date in milliseconds to be used in date arithmetic. |
N | Returns the minumum value in a list (see also max()); one variant takes an optional closure or call reference to process lists of complex data types. | |
N |
Returns a relative date in minutes to be used in date arithmetic. | |
Y |
Creates a directory with the given mode/permissions. | |
N |
Creates a named pipe with the given mode/permissions. | |
N |
Returns the number of seconds after Jan 1, 1970, 00:00:00Z for the date/time value passed. | |
N | Returns a relative date in months to be used in date arithmetic. | |
N | Returns the natural logarithm of the value passed | |
N | Returns current date and time with resolution to the second | |
N | Returns current date and time with resolution to the millisecond | |
N | Returns current date and time with resolution to the microsecond | |
N | Returns current UTC date and time with resolution to the microsecond. | |
|
N |
Returns the current number of threads in the process |
|
N |
Gives the numeric value of the character passed |
Y |
Adds the text passed to the current program's code | |
Y | Parses a URL string and returns a hash of the components; throws an exception if the string cannot be parsed as URL. | |
| Y | Parses a base64 encoded string and returns the binary object |
| N | Returns a hash of the components of a datasource string (ex: "user/pass@db(encoding)%host:port{min=2,max=4}"). |
| Y | Parses a hex-encoded string and returns the binary object; if invalid hex digits are found an exception is thrown. |
Y |
Parses a JSON string and returns the corresponding qore data structure. | |
N | Parses a URL string and returns a hash of the components, unless the string cannot be parsed as URL in which case NOTHING is returned. | |
Y | parses an XML string and returns a Qore hash structure. | |
| Y | parses an XML string as data (does not preserve hash order with out-of-order duplicate keys: collapses all to the same list) and returns a Qore hash structure. |
| Y | parses an XML string as data (does not preserve hash order with out-of-order duplicate keys: collapses all to the same list), validates the generated XML against a RelaxNG schema string, and returns a Qore hash structure. |
| Y | parses an XML string as data (does not preserve hash order with out-of-order duplicate keys: collapses all to the same list), validates the generated XML against an XSD schema string, and returns a Qore hash structure. |
|
Y | deserializies an XML-RPC call string, returning a Qore data structure representing the call information. |
|
Y | deserializies an XML-RPC response string, returning a Qore data structure representing the response information. |
|
Y | deserializies an XML-RPC value tree, returning Qore data representing the information. |
| Y | parses an XML string, validates the generated XML against a RelaxNG schema string, and returns a Qore hash structure. |
| Y | parses an XML string, validates the generated XML against an XSD schema string, and returns a Qore hash structure. |
Y |
Returns the value of the first argument raised to the power of the second | |
N |
Prints the string passed without any formatting. | |
Y |
Prints a formatted string and returns string printed. | |
N | Returns a random integer number. | |
|
Y |
Encrypts data using the Cipher Block Chaining function for RSA's RC2(tm) algorithm. |
|
Y |
Decrypts data using the Cipher Block Chaining function for RSA's RC2(tm) algorithm. |
|
Y |
Decrypts data to a string using the Cipher Block Chaining function for RSA's RC2(tm) algorithm. |
|
Y |
Encrypts data using the Alleged RC4 cipher algorithm, which should be compatible with RSA's RC4(tm) algorithm. |
|
Y |
Decrypts data using the Alleged RC4 cipher algorithm, which should be compatible with RSA's RC4(tm) algorithm. |
|
Y |
Decrypts data to a string using the Alleged RC4 cipher algorithm, which should be compatible with RSA's RC4(tm) algorithm. |
|
Y |
Encrypts data using the Cipher Block Chaining function for RSA's RC5(tm) algorithm. |
|
Y |
Decrypts data using the Cipher Block Chaining function for RSA's RC5(tm) algorithm. |
|
Y |
Decrypts data to a string using the Cipher Block Chaining function for RSA's RC5(tm) algorithm. |
N | Returns the target of a symbolic link; throws an exception if an error occurs. | |
Y | Returns true if the regular expression matches the string passed | |
| Y | Returns a list of substrings in a string based on matching patterns defined by a regular expression. |
| Y | Returns a string with patterns substituted according to the arguments passed. |
| N | Removes an installed signal handler and returns the signal handling state to the default. |
| N | Removes the listed keys from the thread-local data hash. |
Y | Renames (or moves) a file or directory. | |
N |
Replaces all occurrances of a substring in a string with another string and returns the new string. | |
| N | Reverses the order of a string or a list and returns the new string or list. |
Y |
Returns the RIPEMD160 message digest of the supplied argument as a hex string (for strings, the trailing null character is not included in the digest) | |
|
Y |
Returns the RIPEMD160 message digest of the supplied argument as a binary object (for strings, the trailing null character is not included in the digest) |
|
N |
Returns the starting character position of a string in another string as searched from the end of the string. |
N |
Removes a directory. | |
N | Returns a value rounded up to the nearest integer. | |
|
Y |
Saves the data passed against the key passed in thread-local storage. |
N | Returns a relative date/time value in seconds to be used in date arithmetic. | |
| N | Installs or replaces a signal handler. |
N |
Changes the process effective group ID according to the argument passed. Returns 0 for success, non-zero for errors (the error code can be retrieved with errno()) | |
N |
Changes the process effective user ID according to the argument passed. Returns 0 for success, non-zero for errors (the error code can be retrieved with errno()) | |
| N |
Sets the value of an environment variable |
N |
Changes the process group ID according to the argument passed. Returns 0 for success, non-zero for errors (the error code can be retrieved with errno()) | |
N |
Creates a new session lead by the current process. | |
N |
Changes the process user ID according to the argument passed. Returns 0 for success, non-zero for errors (the error code can be retrieved with errno()) | |
Y |
Returns the SHA message digest of the supplied argument as a hex string (for strings, the trailing null character is not included in the digest) | |
Y |
Returns the SHA message digest of the supplied argument as a binary object(for strings, the trailing null character is not included in the digest) | |
Y | Returns the SHA1 message digest of the supplied argument as a hex string (for strings, the trailing null character is not included in the digest) | |
Y | Returns the SHA1 message digest of the supplied argument as a binary object (for strings, the trailing null character is not included in the digest) | |
Y | Returns the SHA224 message digest of the supplied argument as a hex string (for strings, the trailing null character is not included in the digest) | |
| Y | Returns the SHA224 message digest of the supplied argument as a binary object (for strings, the trailing null character is not included in the digest) |
Y | Returns the SHA256 message digest of the supplied argument as a hex string (for strings, the trailing null character is not included in the digest) | |
| Y | Returns the SHA256 message digest of the supplied argument as a binary object (for strings, the trailing null character is not included in the digest) |
Y | Returns the SHA384 message digest of the supplied argument as a hex string (for strings, the trailing null character is not included in the digest) | |
| Y | Returns the SHA384 message digest of the supplied argument as a binary object (for strings, the trailing null character is not included in the digest) |
Y | Returns the SHA512 message digest of the supplied argument as a hex string (for strings, the trailing null character is not included in the digest) | |
| Y | Returns the SHA512 message digest of the supplied argument as a binary object (for strings, the trailing null character is not included in the digest) |
N |
Causes the current thread to sleep for a certain number of seconds. | |
| Y | Sorts a list in ascending order (unstable); optionally takes a closure or a call reference (function or object method reference) to sort non-trivial data types. |
| Y | Sorts a list in descending order (unstable); optionally takes a closure or call reference (function or object method reference) to sort non-trivial data types. |
| Y | Performs a descending stable sort on a list and returns the new list; optionally takes a closure or call reference (function or object method reference) to sort non-trivial data types. |
| Y | Performs an ascending stable sort on a list and returns the new list; optionally takes a closure or call reference (function or object method reference) to sort non-trivial data types. |
|
N |
Splits a string into a list of components based on a separator string |
Y |
Creates a string from the format argument passed and the other arguments. | |
N |
Returns the sine of the number in radians passed. | |
N |
Returns the hyperbolic sine of the number passed. | |
N |
Returns the square root of the number passed. | |
N |
Seeds the random number generator with the integer passed. | |
N |
Returns a list of filesystem information for the filename passed or NOTHING if the | |
N |
Returns the description of the error number passed | |
|
N |
Returns the argument converted to a string |
|
N |
Returns the number of characters in a string. |
| N | Returns an integer corresponding to the string passed with the possibility to specify the base (default base 10). |
|
N |
Returns a substring of a string |
Y |
Executes a process and returns the return code | |
N |
Returns the tangent of the number in radians passed. | |
N |
Returns the hyperbolic tangent of the number passed. | |
| N | Returns a list of all current thread IDs |
| Y | Immediately runs all thread resource cleanup routines for the current thread and throws all associated exceptions. |
N |
Returns the number of seconds since January 1, 1970 00:00:00 in the local time zone for a given date. | |
N |
Converts a string to all lowercase | |
N |
Converts a string to all uppercase | |
| N | Removes the characters from a string (whiltespace by default, can be overridden) and returns the new string (also see the trim operator); also accepts an lvalue reference to do modifications in-place. |
N |
Returns the data type of the argument passed (see Type_Constants) | |
|
N |
deprecated: use type() instead |
N |
Sets the file creation mask for the process | |
| Y | Uncompresses (inflates) data compressed with the "deflate" algorithm (RFC 1951) using zlib functions and returns a binary object. |
| Y | Uncompresses (inflates) data compressed with the "deflate" algorithm (RFC 1951) using zlib functions and returns a string. |
N |
Deletes a file and returns 0 for success. | |
N | Unsets an environment variable | |
N | Causes the current thread to sleep for a certain number of microseconds | |
Y |
Outputs a formatted string based on a variable number of arguments given in a list after the format string. Returns the string printed. | |
Y |
Formats a string based on a variable number of arguments given in a list after the format string and returns this formatted string. | |
N |
Returns a relative date/time value in years to be used in date arithmetic. |
Returns a string of a formatted number according to the arguments passed.
format_number(string, any) returns string (CONST)
format_number() returns nothing (RT_NOOP)
The format_string
has the following format: <thousands_separator
>[<decimal_separator
><decimals
>], where thousands_separator
and decimal_separator
are single ASCII characters defining the thousands and decimal separator characters respectively, and decimals
is a single digit defining how may decimals should appear after the decimal point.
format_number(".,3", -48392093894.2349); # returns "-48.392.093.894,235"
This function does not throw any exceptions.
Table 3.23. Exceptions Thrown by pow()
err | desc |
---|---|
| pow(x, y): y must be a non-negative value. |
| pow(x, y): x cannot be negative when y is not an integer value. |
Returns a floating-point number equal to the closest integer to the argument passed. Numers halfway between two integers are arounded away from zero. The availability of this function depends on the presence of the C-library's round() function; for maximum portability check the constant HAVE_ROUND
before running this function. See Library Option Constants for a list of all option constants.
$x = round(3.2); # returns 3.0
Table 3.25. Exceptions Thrown by round()
err | desc |
---|---|
| This exception is thrown when the function is not available; for maximum portability, check the constant |
The functions in this section operate only on stdout. For generic file I/O please see the File class.
Outputs a formatted string to standard output, respecting field widths in the formatting string. See String Formatting for information on the formatting string, and see printf() for a similar function that does not enforce field widths.
f_printf("%5s\n", "long string"); # will print "long \n", respecting the 5-character field width
Not available with PO_NO_TERMINAL_IO
Table 3.31. Arguments and Return Values for f_printf()
Arguments | Return Type | Description |
---|---|---|
| Returns the string output (see String Formatting for information on the format string) |
This function does not throw any exceptions.
Returns a formatted string without doing any output, respecting field widths. See String Formatting for information on the formatting string, and see sprintf() for a similar function that does not enforce field widths.
$str = f_sprintf("%5s", "a long string"); # will return "a lon"
Table 3.32. Arguments and Return Values for f_sprintf()
Argument Type | Return Type | Description |
---|---|---|
| Returns a formatted string without doing any output, enforcing any field widths. See String Formatting for information on the format string. |
This function does not throw any exceptions.
Flushes output to the console output with print(), printf(), etc.
flush();
Not available with PO_NO_TERMINAL_IO
Table 3.33. Arguments and Return Values for flush()
Arguments | Return Type | Description |
---|---|---|
n/a | n/a | Thie function takes no arguments. |
This function does not throw any exceptions.
Outputs a string to standard output with no formatting. See printf() for a function that allows for formatted output.
print("hello\n"); # do not use formatting with this function
Not available with PO_NO_TERMINAL_IO
Table 3.34. Arguments and Return Values for print()
Argument Type |
Return Type |
Description |
---|---|---|
n/a |
Outputs the string to stdout with no formatting. |
This function does not throw any exceptions.
Outputs the string passed to standard output, using the first argument as a formatting string. See f_printf() for a similar function that enforces field widths, and print for an simple output function that does not accept a formatting string. See String Formatting for information on the formatting string.
printf("%5s\n", "a long string"); # will output "a long string", exceeding the field width
Not available with PO_NO_TERMINAL_IO
Table 3.35. Arguments and Return Values for printf()
Arguments | Return Type | Description |
---|---|---|
|
See String Formatting for information on the format string. This is the "normal" (non-field) printf() version, so any field widths are considered as soft limits, and arguments are allowed to exceed their field widths. Only when an argument is less than the field width will it be padded to the field width specified. Returns the string output. |
This function does not throw any exceptions.
Returns a formatted string without enforcing hard field limits. See f_sprintf() for a similar function that enforces field widths, and see String Formatting for information on the formatting string.
$str = sprintf("%5s", "a long string"); # returns "a long string", exceeding the field width
Table 3.36. Arguments and Return Values for sprintf()
Argument Type | Return Type | Description |
---|---|---|
| See String Formatting for information on the format string. Field widths are considered soft limits (arguments are allowed to exceed their field widths). Only when an argument is less than the field width will it be padded to the field width specified. |
This function does not throw any exceptions.
Outputs a formatted string based on a variable number of arguments given in a list after the format string and returns the string printed. See String Formatting for information on the formatting string.
vprintf("%5s %3d\n", ("a long string", 5000)); # outputs "a long string 5000", exceeding field width of 5
Not available with PO_NO_TERMINAL_IO
Table 3.37. Arguments and Return Values for vprintf()
Argument Type |
Return Type |
Description |
---|---|---|
See String Formatting for information on the format string. Arguments to the formatting string are supplied in the optional second argument as a list. Field widths are considered as soft limits; arguments are allowed to exceed their field widths. Only when an argument is less than the field width will it be padded to the field width specified. Returns the string output. |
This function does not throw any exceptions.
Formats a string based on two arguments: a format string and a list. Does not enforce hard field widths. Returns this formatted string. See String Formatting for information on the formatting string.
$str = vsprintf("%5s %3d\n", ("a long string", 5000)); # returns "a long string 5000", exceeding field width of 5
Table 3.38. Arguments and Return Values for vsprintf()
Argument Type |
Return Type |
Description |
---|---|---|
See String Formatting for information on the format string. Arguments to the formatting string are supplied in the optional second argument as a list. Field widths are considered soft limits (arguments are allowed to exceed their field widths). Only when an argument is less than the field width will it be padded to the field width specified. Returns the formatted string. |
This function does not throw any exceptions.
Returns an integer representing the system time in microseconds (1/1000000 second intervals) since Jan 1, 1970 00:00:00Z.
clock_getmicros() returns int (CONST)
$time = clock_getmicros();
Table 3.39. Arguments and Return Values for clock_getmicros()
Argument Type |
Return Type |
Description |
---|---|---|
n/a |
Returns the number of microseconds (1/1000000 second) since Jan 1, 1970 00:00. |
This function does not throw any exceptions.
Returns an integer representing the system time in milliseconds (1/1000 second intervals since Jan 1, 1970 00:00).
clock_getmillis() returns int (CONST)
$time = clock_getmillis();
Table 3.40. Arguments and Return Values for clock_getmillis()
Argument Type |
Return Type |
Description |
---|---|---|
n/a |
Returns the number of milliseconds (1/1000 second) since Jan 1, 1970 00:00. |
This function does not throw any exceptions.
Returns the system time in nanoseconds (1/1000000000 second intervals) since Jan 1, 1970 00:00:00Z.
clock_getnanos() returns int (CONST)
$time = clock_getnanos();
Table 3.41. Arguments and Return Values for clock_getnanos()
Argument Type |
Return Type |
Description |
---|---|---|
n/a |
Returns the number of nanoseconds (1/1000000000 second) since Jan 1, 1970 00:00:00Z. |
This function does not throw any exceptions.
Converts an integer argument representing the offset in milliseconds from January 1, 1970 in the local time zone to a date in the local time zone.
See also date(), date_us(), and localtime().
my date $date = date_ms(1); # returns 1970-01-01T00:00:00.001
This function does not throw any exceptions.
Converts an integer argument representing the offset in microseconds from January 1, 1970 in the local time zone to a date in the local time zone.
See also date(), date_ms(), and localtime().
my date $date = date_us(1); # returns 1970-01-01T00:00:00.000001
This function does not throw any exceptions.
Table 3.44. Arguments and Return Values for days()
Argument Type |
Return Type |
Description |
---|---|---|
Returns a relative date/time value corresponding to the number of days passed as an argument, to be used in date arithmetic. |
This function does not throw any exceptions.
Returns a formatting string for a date argument passed. See Date Formatting for information about the formatting string.
format_date(string, date) returns string (CONST)
format_date() returns nothing (RT_NOOP)
my string $str = format_date("Day, Mon D, YYYY-MM-DD HH:mm:SS", 2004-02-01T12:30:00);
# returns "Sunday, Feb 1, 2004-02-01 12:30:00"
Table 3.45. Arguments and Return Values for format_date()
Argument Type | Return Type | Description |
---|---|---|
| Formats the date value using the string as a formatting specification. |
This function does not throw any exceptions.
Table 3.46. Date Format Arguments
Format Code | Description |
---|---|
| last two digits of year |
| four-digit year |
| non zero-padded month number (1-12) |
| zero-padded two-digit month number (01-12) |
| long month string (ex: January) |
| long month string capitalized (ex: JANUARY) |
| abbreviated month (ex: Jan) |
| abbreviated month, capitalized (ex: JAN) |
| non zero-padded day number (1 - 31) |
| zero-padded day number (01 - 31) |
| long day of week string (ex: Monday) |
| long day of week string, capitalized (ex: MONDAY) |
| abbreviated day of week string (ex: Mon) |
| abbreviated day of week string capitalised (ex: MON) |
| non zero-padded hour number (0 - 23) |
| zero-padded hour number (00 - 23) |
| non zero-padded hour number, 12-hour clock (1 - 12) |
| zero-padded hour number, 12-hour clock (01 - 12) |
| non zero-padded minute number (0 - 59) |
| zero-padded minute number (00 - 59) |
| non zero-padded second number (0 - 59) |
| zero-padded second number (00 - 59) |
| AM or PM (upper-case) |
| am or pm (lower-case) |
| non zero-padded millisecond number (0 - 999) |
| zero-padded millisecond number (000 - 999) |
| non zero-padded microsecond number (0 - 999999) |
| zero-padded microsecond number (000000 - 999999) |
| microseconds, with trailing zeros removed (suitable for use after the '.') |
| local time zone name (ex: 'EST') if available, otherwise the UTC offset (see 'Z') |
| time zone UTC offset like +HH:mm[:SS], seconds are included if non-zero |
All other text is output directly in the output text unchanged.
Returns an integer value representing the the number of microseconds in the value of the date passed (can be either a relative or absolute date).
If the argument is an absolute date/time value, then the resulting number is calculated from the present time. Fixed-time arguments in the past will result in a return value of 0; this function can only return a negative value if passed a relative date/time value.
get_duration_microseconds(date) returns int (CONST)
my int $us = get_duration_microseconds(PT2M15S3u); # returns 135000003
Table 3.48. Arguments and Return Values for get_duration_microseconds()
Argument Type |
Return Type |
Description |
---|---|---|
Returns an integer value representing the the number of microseconds in the value of the date passed; note that the return value will be calculated from the present time if an absolute date/time value argument is passed, but in this case will never be negative; fixed-time arguments in the past will result in a value of 0 being returned. |
Returns an integer value representing the the number of milliseconds in the value of the date passed (can be either a relative or absolute date).
If the argument is an absolute date/time value, then the resulting number is calculated from the present time. Fixed-time arguments in the past will result in a return value of 0; this function can only return a negative value if passed a relative date/time value.
get_duration_milliseconds(date) returns int (CONST)
my int $us = get_duration_milliseconds(PT2M15S3u); # returns 135000
Table 3.49. Arguments and Return Values for get_duration_milliseconds()
Argument Type |
Return Type |
Description |
---|---|---|
Returns an integer value representing the the number of milliseconds in the value of the date passed; note that the return value will be calculated from the present time if an absolute date/time value argument is passed, but in this case will never be negative; fixed-time arguments in the past will result in a value of 0 being returned. |
Returns an integer value representing the the number of seconds in the value of the date passed (can be either a relative or absolute date).
If the argument is an absolute date/time value, then the resulting number is calculated from the present time. Fixed-time arguments in the past will result in a return value of 0; this function can only return a negative value if passed a relative date/time value.
get_duration_seconds(date) returns int (CONST)
my int $us = get_duration_seconds(PT2M15S3u); # returns 135
Table 3.50. Arguments and Return Values for get_duration_seconds()
Argument Type |
Return Type |
Description |
---|---|---|
Returns an integer value representing the the number of seconds in the value of the date passed; note that the return value will be calculated from the present time if an absolute date/time value argument is passed, but in this case will never be negative; fixed-time arguments in the past will result in a value of 0 being returned. |
Returns the number of seconds of the date and time in local time passed since Jan 1, 1970, 00:00:00 Z (UTC). Negative values are returned for dates before the epoch.
This function is equivalent to mktime().
get_epoch_seconds(date) returns int (CONST)
get_epoch_seconds() returns nothing (RT_NOOP)
$secs = get_epoch_seconds(2007-09-23T00:00:01);
This function does not throw any exceptions.
Returns an integer value representing the microseconds value of the date passed (can be either a relative or absolute date).
get_microseconds(date) returns int (CONST)
get_microseconds() returns nothing (RT_NOOP)
$ms = get_microseconds(2007-01-23T11:24:03.250); # returns 250
Returns a date/time value representing midnight on the date passed (strips the time from the date passed and returns the new value)
get_midnight(date) returns date (CONST)
get_midnight() returns nothing (RT_NOOP)
$date = get_midnight(2007-01-23T11:24:03.250); # returns 2007-01-23T00:00:00.000
Returns an integer value representing the milliseconds value of the date passed (can be either a relative or absolute date).
get_milliseconds(date) returns int (CONST)
get_milliseconds() returns nothing (RT_NOOP)
$ms = get_milliseconds(2007-01-23T11:24:03.250); # returns 250
Returns an integer value representing the minutes value of the date passed (can be either a relative or absolute date).
get_minutes(date) returns int (CONST)
get_minutes() returns nothing (RT_NOOP)
$minutes = get_minutes(2007-01-23T11:24:03); # returns 24
Returns an integer value representing the months value of the date passed (can be either a relative or absolute date).
get_months(date) returns int (CONST)
get_months() returns nothing (RT_NOOP)
$months = get_months(2007-01-23); # returns 1
Returns an integer value representing the seconds value of the date passed (can be either a relative or absolute date).
get_seconds(date) returns int (CONST)
get_seconds() returns nothing (RT_NOOP)
$secs = get_seconds(2007-01-23T11:24:03); # returns 3
Retuns an absolute date value for the ISO-8601 calendar week information passed (year, week number, optional: weekday, where 1=Monday, 7=Sunday) in the current time zone. If the weekday is omitted, Monday (1) is assumed; throws an exception if the arguments are invalid.
getDateFromISOWeek(softint
$year
, softint $month
, softint $wday
= 1) returns date
$date = getDateFromISOWeek(2007, 3); # returns 2007-01-15T00:00:00
Table 3.60. Arguments and Return Values for getDateFromISOWeek()
Argument Type |
Return Type |
Description |
---|---|---|
Retuns an absolute date value in the local time zone for the ISO-8601 calendar week information passed (year, week number, optional: week day). If the week day is passed, it must be in the range 1 (Monday) - 7 (Sunday) inclusive. |
Table 3.61. Exceptions Thrown by getDateFromISOWeek()
err | desc |
---|---|
| The week number is not valid for the given year. |
| The day number is not between 1 (Monday) and 7 (Sunday) inclusive. |
Returns an integer representing the day of the week for the absolute date passed (0=Sunday, 6=Saturday)
getDayOfWeek(date) returns int (CONST)
getDayOfWeek() returns nothing (RT_NOOP)
$dow = getDayOfWeek(2007-05-15); # returns 2
Table 3.62. Arguments and Return Values for getDayOfWeek()
Argument Type |
Return Type |
Description |
---|---|---|
Returns an integer representing the day of the week for the absolute date passed (0=Sunday, 6=Saturday) |
Returns an integer representing the ordinal day number in the year for the absolute date passed
getDayNumber(date) returns int (CONST)
getDayNumber() returns nothing (RT_NOOP)
$dn = getDayNumber(2007-05-15); # returns 135
Table 3.63. Arguments and Return Values for getDayNumber()
Argument Type |
Return Type |
Description |
---|---|---|
Returns an integer representing the ordinal day number in the year for the absolute date passed |
Returns an integer representing the ISO-8601 day of the week for the absolute date passed (1=Monday, 7=Sunday)
getISODayOfWeek(date) returns int (CONST)
getISODayOfWeek() returns nothing (RT_NOOP)
$dow = getISODayOfWeek(2007-05-15); # returns 2 for Tuesday
Table 3.64. Arguments and Return Values for getISODayOfWeek()
Argument Type |
Return Type |
Description |
---|---|---|
Returns an integer representing the ISO-8601 day of the week for the absolute date passed (1=Monday, 7=Sunday) |
Returns a hash representing the ISO-8601 calendar week information for the absolute date passed (hash keys: year, week, day). Note that the ISO-8601 year does not always correspond with the calendar year at the end and the begin ning of every year (for example 2006-01-01 is ISO-8601 calendar week format is: year=2005, week=52, day=7)
getISOWeekHash(date) returns hash (CONST)
getISOWeekHash() returns nothing (RT_NOOP)
$h = getISOWeekHash(2007-05-15); # returns year=2007, week=20, day=2
Table 3.65. Arguments and Return Values for getISOWeekHash()
Argument Type |
Return Type |
Description |
---|---|---|
Returns a |
Returns a string representing the ISO-8601 calendar week information for the absolute date passed (ex: 2006-01-01 = "2005-W52-7"). Note that the ISO-8601 year does not always correspond with the calendar year at the end and the beginning of every year (for example 2006-01-01 is ISO-8601 calendar week format is: year=2005, week=52, day=7)
getISOWeekString(date) returns string (CONST)
getISOWeekString() returns nothing (RT_NOOP)
$str = getISOWeekString(2007-05-15); # returns "2007-W20-2"
Table 3.66. Arguments and Return Values for getISOWeekString()
Argument Type |
Return Type |
Description |
---|---|---|
Returns a string representing the ISO-8601 calendar week information for the absolute date passed (ex: 2006-01-01 = "2005-W52-7") |
Returns the date and time in GMT; if no argument is passed, then the current UTC time with a resolution of a second is returned. Otherwise the single argument must be an integer giving the number of seconds since Jan 1, 1970, 00:00:00, or an absolute date/time value that will be returned as the sme time in UTC (GMT).
See also now_utc().
gmtime(date
$date
) returns date (CONST)
gmtime(softint
$epoch_seconds
, softint $microseconds
= 0) returns date (CONST)
$date = gmtime(now_us()); # equivalent to now_utc()
$date = gmtime(); # also returns current UTC (GMT)
Table 3.67. Arguments and Return Values for gmtime()
Argument Type |
Return Type |
Description |
---|---|---|
|
The date argument is converted to UTC and returned. | |
| ||
n/a |
If no argument is passed, then the current date and time with resolution to the second in GMT is returned. See now_utc() for a similar function that returns the current UTC time with resolution to the microsecond. |
This function does not throw any exceptions.
Table 3.68. Arguments and Return Values for hours()
Argument Type |
Return Type |
Description |
---|---|---|
Returns a relative date/time value corresponding to the number of hours passed as an argument, to be used in date arithmetic. |
This function does not throw any exceptions.
Returns True
if the argument is an absolute date/time value, False
if not.
is_date_absolute(date) returns bool (CONST)
is_date_absolute(any) returns bool (RT_NOOP)
my bool $b = is_date_absolute($date);
Table 3.69. Arguments and Return Values for is_date_absolute()
Argument Type |
Return Type |
Description |
---|---|---|
Returns |
This function does not throw any exceptions.
Returns True
if the argument is an relative date/time value, False
if not.
is_date_relative(date) returns bool (CONST)
is_date_relative(any) returns bool (RT_NOOP)
my bool $b = is_date_relative($date);
Table 3.70. Arguments and Return Values for is_date_relative()
Argument Type |
Return Type |
Description |
---|---|---|
Returns |
This function does not throw any exceptions.
Returns the date and time in local time corresponding to the integer argument passed, which must be the number of seconds since Jan 1, 1970, 00:00:00 Z (UTC). If no argument is passed, then the current local date and time are returned.
localtime(date
$date
) returns date (CONST)
localtime(softint
$epoch_seconds
, softint $microseconds
= 0) returns date (CONST)
$time = localtime(10);
Table 3.71. Arguments and Return Values for localtime()
Argument Type |
Return Type |
Description |
---|---|---|
|
The date argument is converted to the local time zone and returned. | |
| ||
n/a |
If no argument is passed, then the current date and time with resolution to the second in the local time zone is returned. See now_us() for a similar function that returns the current local time with resolution to the microsecond. |
This function does not throw any exceptions.
Returns a relative date/time value in microseconds to be used in date arithmetic.
microseconds(softint) returns date (CONST)
microseconds() returns date (RT_NOOP)
$ms = millseconds(5 * 5); # returns 25ms
Table 3.72. Arguments and Return Values for microseconds()
Argument Type |
Return Type |
Description |
---|---|---|
Returns a relative date/time value corresponding to the number of microseconds passed as an argument, to be used in date arithmetic. |
This function does not throw any exceptions.
Returns a relative date/time value in milliseconds to be used in date arithmetic.
milliseconds(softint) returns date (CONST)
milliseconds() returns date (RT_NOOP)
$ms = millseconds(5 * 5); # returns 25ms
Table 3.73. Arguments and Return Values for milliseconds()
Argument Type |
Return Type |
Description |
---|---|---|
Returns a relative date/time value corresponding to the number of milliseconds passed as an argument, to be used in date arithmetic. |
This function does not throw any exceptions.
Table 3.74. Arguments and Return Values for minutes()
Argument Type |
Return Type |
Description |
---|---|---|
Returns a relative date/time value corresponding to the number of minutes passed as an argument, to be used in date arithmetic. |
This function does not throw any exceptions.
This function does not throw any exceptions.
Table 3.76. Arguments and Return Values for months()
Argument Type |
Return Type |
Description |
---|---|---|
Returns a relative date/time value corresponding to the number of months passed as an argument, to be used in date arithmetic. |
This function does not throw any exceptions.
Returns the current date and time in the local time zone with resolution to the second.
For similar functions returning the current date and time in the local time zone with millisecond and microsecond resolution, see now_ms() and now_us(). Note that there is no performance penalty for using now_ms() and now_us() versus this function, this function and now_ms() are kept for backwards-compatibility.
See also now_utc().
$now = now();
Table 3.77. Arguments and Return Values for now()
Argument Type |
Return Type |
Description |
---|---|---|
n/a |
Returns the current date and time in the local time zone with resolution to the second. |
This function does not throw any exceptions.
Returns the current date and time in the local time zone with resolution to the millisecond.
For a similar function returning the current date and time in the local time zone with coarser granularity, when resolution only to the second is needed, see now(); for a similar function returning the current date and time with a resolution to the microsecond, see now_us(). Note that there is no performance penalty for using now_ms() and now_us() versus now(), now() and now_ms() are kept for backwards-compatibility.
See also now_utc().
now_ms()
$now_ms = now_ms();
Table 3.78. Arguments and Return Values for now_ms()
Argument Type |
Return Type |
Description |
---|---|---|
n/a |
Returns the current date and time in the local time zone with resolution to the millisecond. |
This function does not throw any exceptions.
Returns the current date and time in the local time zone with resolution to the microsecond.
For similar functions returning the current date and time with coarser granularity, see now() and now_ms(). Note that there is no performance impact for using now_us() versus now() and now_ms(); now() and now_ms() are kept for backwards-compatibility.
See also now_utc().
now_us()
$now_us = now_us();
Table 3.79. Arguments and Return Values for now_us()
Argument Type |
Return Type |
Description |
---|---|---|
n/a |
Returns the current date and time with resolution to the microsecond. |
This function does not throw any exceptions.
Returns the current UTC date and time with resolution to the microsecond.
See also now_us() for a similar function that returns the current date and time in the local time zone.
now_utc()
$now_utc = now_utc();
Table 3.80. Arguments and Return Values for now_utc()
Argument Type |
Return Type |
Description |
---|---|---|
n/a |
Returns the current UTC date and time with resolution to the microsecond. |
This function does not throw any exceptions.
Table 3.81. Arguments and Return Values for seconds()
Argument Type |
Return Type |
Description |
---|---|---|
Returns a relative date/time value corresponding to the number of seconds passed as an argument, to be used in date arithmetic. |
This function does not throw any exceptions.
Table 3.83. Arguments and Return Values for years()
Argument Type |
Return Type |
Description |
---|---|---|
Returns a relative date/time value corresponding to the number of years passed as an argument, to be used in date arithmetic. |
This function does not throw any exceptions.
Returns a binary data type of the string passed; data types other than string will first be converted to a string and then returned as binary data.
This function is useful if, for some reason, a string type actually contains binary data; using this function will ensure that all data in the string (even if it contains embedded nulls) is maintained in the binary object (Qore strings must normally be terminated by a single null, so some Qore string operations do not work on binary data with embedded nulls).
binary(string) returns binary (CONST)
binary(binary) returns binary (CONST)
$bin = binary("hello");
Table 3.84. Arguments and Return Values for binary()
Argument Type |
Return Type |
Description |
---|---|---|
A binary data type holding the string data passed. |
This function does not throw any exceptions.
Returns a string created from the binary data passed, taking an optional second argument giving the string encoding. If no second argument is passed then the default encoding is assumed.
No checking is performed for embedded null characters or for character encoding violations; the data is simply copied from the binary value to the string (with any embedded nulls, if present), and the string is tagged with the given encoding or with the default encoding if no second argument is passed. See also string() and binary().
binary_to_string(binary
$bin
) returns string
binary_to_string(binary
$bin
, string $encoding
) returns string
$str = binary_to_string($bin, "utf8");
Table 3.85. Arguments and Return Values for binary_to_string()
Argument Type | Return Type | Description |
---|---|---|
Returns a string corresponding to the binary data passed, taking an optional second argument giving the string encoding. If no second argument is passed then the default encoding is assumed. |
Converts the argument to a date and returns the date. When converting from an integer, the integer value represents the offset in seconds from 1970-01-01 in the local time zone.
See also date_ms(), date_us(), and localtime().
As of Qore 0.8.0, converting a date from a string is much more flexible; formats such as the following are now accepted (note that in the following examples, if the time zone/UTC offset is not explicitly specified, the local time zone is assumed):
Table 3.87. Examples Converting Date From String
String | Date |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
date(string) returns date (CONST)
date(softint) returns date (CONST)
$date = date(1); # return 1970-01-01T00:00:01
This function does not throw any exceptions.
Converts an object or a list to a hash; for any other argument, returns an empty hash (ignores any other arguments passed).
For an object argument, the hash returned is equal to the object members (excluding private members if called outside the class); a list is converted to a hash by taking even numbered list elements (starting with 0) and converting them to strings for the hash keys, and the odd numbered elements following the keys as the key value.
hash(list
$keys
, list $values
) returns hash
hash(hash
$hash
) returns hash (CONST)
$h = hash($object); # creates a hash of the object's members
Table 3.90. Arguments and Return Values for hash()
Argument Type | Return Type | Description |
---|---|---|
Returns a hash by taking the first list as a list of keys, and the second list as a list of values. If the two lists are of unequal sizes, then the keys list takes precedence (if the values list is longer, excess values are ignored). | ||
| Returns a hash by taking even numbered list elements (starting with 0) and converting them to strings for the hash keys, and the odd numbered elements following the keys as the key value. | |
| Returns the hash argument unmodified. | |
| Returns a hash of the object's members (public members only if called outside the class). | |
Returns an empty hash. |
This function does not throw any exceptions.
Converts the argument passed to a string value.
This function will not convert a binary value to a string; in order to do this, use the binary_to_string() function.
string(softstring) returns string (CONST)
$str = string(200); # returns "200"
Table 3.93. Arguments and Return Values for string()
Argument Type | Return Type | Description |
---|---|---|
Converts the argument passed to a string value. |
This function does not throw any exceptions.
Returns the data type of the argument passed. See Type Constants for the values returned by this function..
$type = type("hello"); # returns Type::String ("string")
Table 3.94. Arguments and Return Values for type()
Argument Type | Return Type | Description |
---|---|---|
Returns the data type of the argument passed. See Type_Constants for the values that can be returned by this function. |
This function does not throw any exceptions.
deprecated: use type() instead.
typename(expression
)
This function does not throw any exceptions.
This function will be removed in a future version of Qore.
Sets an environment variable to a value.
To unset or clear an environment variable, see unsetenv().
setenv(string
$var
, softstring $value
) returns int
setenv("PATH", "/bin:/usr/bin");
Table 3.97. Arguments and Return Values for setenv()
Argument Type | Return Type | Description |
---|---|---|
| Sets the environment variable to a string value (the value is converted to a string if necessary). |
This function does not throw any exceptions.
Retrieves the byte position of a substring within a string.
bindex(softstring
$string
, softstring $substring
, softint $offset
= 0) returns int
$i = bindex("hello there", "the");
Table 3.99. Arguments and Return Values for bindex()
Argument Type | Return Type | Description |
---|---|---|
| If the substring is found, returns the byte position of the substring within the string (starting at 0). If not found, returns -1. If an offset position is given, the search starts at the offset position. All values are byte positions, not character positions, which may differ for multi-byte character encodings. |
This function does not throw any exceptions.
Returns the starting byte position of a string in another, starting from the end of the string (-1 if not found) and takes an optional starting position.
brindex(softstring
$string
, softstring $substring
, softint $offset
= -1) returns int
$i = brindex("hello there", "the");
Table 3.100. Arguments and Return Values for brindex()
Argument Type | Return Type | Description |
---|---|---|
| Returns the starting byte position of a string in another, starting from the end of the string, or from |
This function does not throw any exceptions.
Removes the trailing end-of-line indicator ('\n' or '\r\n') from a string and returns the new string (also see the chomp operator). If no EOL indicator is present in the string, this function simply returns the original string unmodified. This function accepts variable references, in which case it will modify the string in place and also return the modified string.
$line = chomp("hello\n"); # returns "hello"
Table 3.101. Arguments and Return Values for chomp()
Argument Type | Return Type | Description |
---|---|---|
Returns the new string with any end-of-line character(s) removed. | ||
If the first argument is a variable reference and points to a string, then the string is modified in place and the new string is also returned. Otherwise if the reference is any other type, no action is taken and no value is returned. |
This function does not throw any exceptions.
Performs explicit string character encoding conversions.
convert_encoding(string, string) returns string (CONST)
convert_encoding() returns nothing (RT_NOOP)
$utf8_str = convert_encoding($iso_8859_1_str, "utf-8");
Table 3.104. Exceptions Thrown by convert_encoding()
err | desc |
---|---|
| There was an error converting to the target encoding (ex: conversion not supported, illegal character sequence, etc). |
Decodes percent numeric codes in a URL string and returns the decoded string.
decode_url(string) returns string (CONST)
decode_url() returns nothing (RT_NOOP)
$decoded_url = decode_url($encoded_url);
This function does not throw any exceptions.
Returns the first string argument tagged with the character encoding given as the second argument; does not actually change the string data; use only in the case that a string is tagged with the wrong encoding, for example, if a string from a File object has a different encoding than the File object.
force_encoding(string, string) returns string (CONST)
force_encoding() returns nothing (RT_NOOP)
$utf8_str = force_encoding($bad_str, "utf-8");
This function does not throw any exceptions.
Returns a string describing the character encoding of the string passed.
get_encoding(string) returns string (CONST)
get_encoding() returns nothing (RT_NOOP)
$enc = get_encoding($string);
This function does not throw any exceptions.
Retrieves the character position of a substring within a string.
index(softstring
$string
, softstring $substring
, softint $offset
= 0) returns int (CONST)
$i = index("hello there", "the");
Table 3.108. Arguments and Return Values for index()
Argument Type | Return Type | Description |
---|---|---|
| If the substring is found, returns the position of the substring within the string (starting at 0). If not found, returns -1. If an offset position is given, the search starts at the offset position. All values are character positions, not byte positions, which may differ for multi-byte character encodings. |
This function does not throw any exceptions.
Returns the length in characters for the string passed. Note that the byte length may differ from the character length with multi-byte character encodings. For byte length of a string, see strlen().
length(softstring) returns int (CONST)
length(binary) returns int (CONST)
$len = length("hello"); # returns 5
Table 3.110. Arguments and Return Values for length()
Argument Type | Return Type | Description |
---|---|---|
Returns the length in characters for the string passed. | ||
Returns the number of bytes in the binary data passed. |
This function does not throw any exceptions.
Gives the numeric value of the given byte in the string passed (the first byte if no offset is passed); if no string is passed or the offset is after the end of the string, -1 is returned.
ord(softstring
$string
, softint $offset
= 0) returns int (CONST)
$i = ord("A"); # returns 65
Table 3.111. Arguments and Return Values for ord()
Argument Type | Return Type | Description |
---|---|---|
| Gives the numeric value of the given byte in the string passed (the first byte if no offset is passed); if no string is passed or the offset is after the end of the string, -1 is returned. |
This function does not throw any exceptions.
Table 3.112. Arguments and Return Values for regex()
Argument Type | Return Type | Description |
---|---|---|
Returns |
Table 3.113. Exceptions Thrown by regex()
err | desc |
---|---|
| There was an error compiling the regular expression. |
For more information on regular expression processing, see Regular Expressions.
Returns a list of substrings in a string based on matching patterns defined by a regular expression.
regex_extract(string
$string
, string $pattern
, int $options
= 0) returns any
regex_extract() returns nothing (RT_NOOP)
my any $rv = regex_extract("hello:there", "(\\w+):(\\w+)");
Table 3.114. Arguments and Return Values for regex_extract()
Argument Type | Return Type | Description |
---|---|---|
Returns any patterns in parentheses in the second argument when applied tot he first argument as a |
Table 3.115. Exceptions Thrown by regex_extract()
err | desc |
---|---|
| Invalid options were passed to the function. |
| There was an error compiling the regular expression. |
For more information on regular expression processing, see Regular Expressions.
Returns a string with patterns substituted according to the arguments passed.
regex_subst(string
$string
, string $pattern
, string $new_string
, int $options
= 0) returns string
regex_subst() returns nothing (RT_NOOP)
$str = regex_subst("hello there", "^there$", "you"); # returns "hello you"
Table 3.116. Arguments and Return Values for regex_subst()
Argument Type | Return Type | Description |
---|---|---|
| Returns the result of applying the second argument as a pattern to the first argument, with the 3rd argument as the replacement string. The fourth argument can be used to set regex options; for valid options, see Regex Constants |
Table 3.117. Exceptions Thrown by regex_subst()
err | desc |
---|---|
| Invalid options were passed to the function. |
| There was an error compiling the regular expression. |
For more information on regular expression processing, see Regular Expressions.
Returns the starting character position of a string in another, starting from the end of the string (-1 if not found) and takes an optional starting position.
rindex(softstring
$string
, softstring $substring
, softint $offset
= -1) returns int (CONST)
$i = rindex("hello there", "the");
Table 3.119. Arguments and Return Values for rindex()
Argument Type | Return Type | Description |
---|---|---|
| Returns the starting character position of a string in another, starting from the end of the string, or from the third argument giving the character (not byte) position if given (negative values are offsets from the end of the string, -1 gives the last character of the string). If the thirs argument is given, then the reverse search starts at that character position (searches always go from the end of the string toward the beginning). Returns -1 if the substring cannot be found. All values are character positions, not byte positions, which may differ for multi-byte character encodings. |
This function does not throw any exceptions.
Table 3.120. Arguments and Return Values for split()
Argument Type | Return Type | Description |
---|---|---|
Returns a list of each component of a string separated by a separator string, with the separator removed. | ||
Returns a list of each component of thebinary object separated by the bytes identified by |
This function does not throw any exceptions.
Returns the length in bytes of the string argument. Note that the byte length may differ from the character length with multi-byte character encodings. For the character length of a string, see length().
strlen(softstring) returns int (CONST)
$len = strlen("hello"); # returns 5
Table 3.121. Arguments and Return Values for strlen()
Argument Type | Return Type | Description |
---|---|---|
Returns the length of the string passed. If the argument is not a string, then it is converted to a string. |
This function does not throw any exceptions.
Returns a portion of a string starting from an integer offset, with an optional length. Arguments can be negative, giving offsets from the end of the string. All offsets are character positions, not byte positions.
substr(softstring
$string
, softint $offset
, softint $len
) returns string (CONST)
substr(softstring
$string
, softint $offset
) returns string (CONST)
$str = substr("hello there", 6); # returns "there"
Table 3.122. Arguments and Return Values for substr()
Argument Type | Return Type | Description |
---|---|---|
| Returns the substring according to the arguments. If |
This function does not throw any exceptions.
Removes characters from the start and end of a string and returns the new string (also see the trim operator). This function accepts variable references, in which case it will modify the string in place and also return the modified string.
By default (if the second argument is omitted or passed as an empty string) the following whitespace characters are removed: ' ', '\n', '\r', '\t', '\v' (vertical tab, ASCII 11), and '\0' (null character). To trim other characters, pass a string as the second argument specifying the characters to be removed.
trim(string
$string
, string $chars
= "") returns string (CONST)
$line = trim(" hello \n"); # returns "hello"
Table 3.125. Arguments and Return Values for trim()
Argument Type | Return Type | Description |
---|---|---|
Returns the new string with characters removed from the beginning and end of the string; if the second argument is given then it defines the characters to be removed, otherwise whitespace is removed. | ||
If the reference points to a string, the string is trimmed in place and the result is also returned; if the second argument is given then it defines the characters to be removed, otherwise whitespace is removed. If the reference is not a string then no value is returned. |
This function does not throw any exceptions.
Aborts the current program (this function does not return).
abort();
Not available with PO_NO_PROCESS_CONTROL
This function does not throw any exceptions.
Returns the error code of the last error that occurred in the current thread. See strerror() for a function that gives the string description for the error number returned by this function.
$str = strerror(errno());
Table 3.127. Arguments and Return Values for errno()
Argument Type | Return Type | Description |
---|---|---|
n/a | The error code of the most recent error in the current thread is returned. |
This function does not throw any exceptions.
Replaces the current process image with another. This function does not return.
exec("/bin/ls -l");
Not available with PO_NO_PROCESS_CONTROL
or PO_NO_EXTERNAL_PROCESS
Table 3.128. Arguments and Return Values for exec()
Argument Type | Return Type | Description |
---|---|---|
n/a | The process and any arguments to the process to execute. This function does not return. |
This function does not throw any exceptions.
Exits the program with the return code passed (this function does not return).
exit(2);
Not available with PO_NO_PROCESS_CONTROL
Table 3.129. Arguments and Return Values for exit()
Argument Type | Return Type | Description |
---|---|---|
n/a | Exits the program with the return code set to the value of the argument passed converted to an integer if necessary. |
This function does not throw any exceptions.
Creates a copy of the current process with a new PID. Returns 0 in the child process, the child's PID in the parent process. This function will throw an exception if more than one thread is running.
$pid = fork();
Not available with PO_NO_PROCESS_CONTROL
Table 3.130. Arguments and Return Values for fork()
Argument Type | Return Type | Description |
---|---|---|
n/a | The child's PID is returned in the parent process, 0 is returned in the child's process. If -1 is returned, then no child was started and the error number can be retrieved with the errno() function. |
Table 3.131. Exceptions Thrown by fork()
err | desc |
---|---|
| Cannot fork if more than one thread is running. |
Returns the effective group ID of the current process.
$egid = getegid();
Not available with PO_NO_EXTERNAL_INFO
Table 3.132. Arguments and Return Values for getegid()
Argument Type | Return Type | Description |
---|---|---|
n/a | Returns the effective group ID of the current process. |
This function does not throw any exceptions.
Returns the effective user ID of the current process.
Not available with PO_NO_EXTERNAL_INFO
Table 3.133. Arguments and Return Values for geteuid()
Argument Type | Return Type | Description |
---|---|---|
n/a | Returns the effective user ID of the current process. |
This function does not throw any exceptions.
Returns the real group ID of the current process.
$gid = getgid();
Not available with PO_NO_EXTERNAL_INFO
Table 3.134. Arguments and Return Values for getgid()
Argument Type | Return Type | Description |
---|---|---|
n/a | Returns the real group ID of the current process. |
This function does not throw any exceptions.
Returns the official hostname corresponding to the network addressed passed as an argument. If the second argument giving the address type is not passed, then AF_INET (IPv4) is assumed. See Network Address Type Constants for valid values for the second argument. If the address family is invalid or the address string is not a valid address for the given family an exception will be thrown.
For a version of this function that returns all host information, including all hostname aliases and all addresses, see gethostbyaddr_long().
gethostbyaddr(string
$addr
, softint $type
= AF_INET) returns any (CONST)
gethostbyaddr() returns nothing (RT_NOOP)
$hostname = gethostbyaddr("192.168.0.33");
Not available with PO_NO_EXTERNAL_INFO
Table 3.136. Exceptions thrown by gethostbyaddr()
err | desc |
---|---|
| invalid address or invalid address family passed as arguments |
Returns a hash representing all host and address information corresponding to the network addressed passed as an argument. See Host Information Hash for a description of the return value.
If the second argument giving the address type is not passed, then AF_INET (IPv4) is assumed. See Network Address Type Constants for valid values for the second argument. If the address family is invalid or the address string is not a valid address for the given family an exception will be thrown.
For a version of this function that returns just the official hostname corresponding to the address, see gethostbyaddr().
gethostbyaddr_long(string
$addr
, softint $type
= AF_INET) returns any (CONST)
gethostbyaddr_long() returns nothing (RT_NOOP)
$hash = gethostbyaddr_long("192.168.0.33");
Not available with PO_NO_EXTERNAL_INFO
Table 3.138. Host Information Hash
Key | Type | Value |
---|---|---|
| The official fully-qualified name of the host | |
| Any hostname aliases for the host | |
| The type of network address (either "ipv4" or "ipv6") | |
| One of the Network Address Type Constants (either | |
| The length of the addresses in bytes when represented in binary form. | |
| All addresses corresponding to the host; the list should have at least 1 element |
Table 3.139. Exceptions thrown by gethostbyaddr_long()
err | desc |
---|---|
| invalid address or invalid address family passed as arguments |
Returns the first address corresponding to the hostname passed as an argument.
For a version of this function that returns all host information, including all hostname aliases and all addresses, see gethostbyname_long().
gethostbyname(string
$name
) returns any (CONST)
gethostbyname() returns nothing (RT_NOOP)
$addr = gethostbyname("host1");
Not available with PO_NO_EXTERNAL_INFO
This function does not throw any exceptions.
Returns a hash representing all host and address information corresponding to the hostname passed as an argument. See Host Information Hash for a description of the return value.
For a version of this function that returns just the first network address corresponding to the hostname, see gethostbyname().
gethostbyname_long(string
$name
) returns any (CONST)
$hash = gethostbyname_long("host1");
Not available with PO_NO_EXTERNAL_INFO
This function does not throw any exceptions.
Returns the hostname of the system.
gethostname() returns string
$host = gethostname();
Not available with PO_NO_EXTERNAL_INFO
Table 3.142. Arguments and Return Values for gethostname()
Argument Type | Return Type | Description |
---|---|---|
n/a | Returns the hostname of the system. |
This function does not throw any exceptions.
Returns the PID (process ID) of the current process.
$pid = getpid();
Not available with PO_NO_EXTERNAL_INFO
Table 3.143. Arguments and Return Values for getpid()
Argument Type | Return Type | Description |
---|---|---|
n/a | Returns the PID (process ID) of the current process. |
This function does not throw any exceptions.
Returns the PID (process ID) of the parent process of the current process.
$ppid = getppid();
Not available with PO_NO_EXTERNAL_INFO
Table 3.144. Arguments and Return Values for getppid()
Argument Type | Return Type | Description |
---|---|---|
n/a | Returns the PID (process ID) of the parent of the current process. |
This function does not throw any exceptions.
Returns the real user ID of the current process.
$uid = getuid();
Not available with PO_NO_EXTERNAL_INFO
Table 3.145. Arguments and Return Values for getuid()
Argument Type | Return Type | Description |
---|---|---|
n/a | Returns the real user ID of the current process. |
This function does not throw any exceptions.
Changes the process effective group ID according to the argument passed. Returns 0 for success, non-zero for errors (the error code can be retrieved with errno()). The availabilty of this function depends on the system's underlying C-library; the Qore function is only available if the constant HAVE_SETEGID
is True
. See Library Option Constants for a list of all option constants.
setegid($egid);
Not available with PO_NO_PROCESS_CONTROL
Table 3.149. Exceptions thrown by setegid()
err | desc |
---|---|
| missing EGID argument to function |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Changes the process effective user ID according to the argument passed. Returns 0 for success, non-zero for errors (the error code can be retrieved with errno()). The availabilty of this function depends on the system's underlying C-library; the Qore function is only available if the constant HAVE_SETEUID
is True
. See Library Option Constants for a list of all option constants.
seteuid($euid);
Not available with PO_NO_PROCESS_CONTROL
Table 3.151. Exceptions thrown by seteuid()
err |
desc |
---|---|
|
missing EUID argument to function |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Changes the process group ID according to the argument passed. Returns 0 for success, non-zero for errors (the error code can be retrieved with errno())
setgid($gid);
Not available with PO_NO_PROCESS_CONTROL
Creates a new session lead by the calling process.
The calling process is the session leader of the new session, is the process group leader of a new process group and has no controlling terminal. The calling process is the only process in either the session or the process group.
Upon successful completion, the setsid()
function returns the value of the process group ID of the new process group, which is the same as the process ID of the calling process.
my int $rc = setsid();
Not available with PO_NO_PROCESS_CONTROL
Changes the process user ID according to the argument passed. Returns 0 for success, non-zero for errors (the error code can be retrieved with errno())
setuid($uid);
Not available with PO_NO_PROCESS_CONTROL
Causes the current thread to sleep for a certain number of seconds. Note that as with all Qore functions and methods accepting a timeout value, relative date/time values can be given instead of integers to make the source more readable (ie 5s
), however as this function only supports a resolution of 1 second, milliseconds are ignored if passed to this function. See usleep() for a similar function supporting microsecond resolution.
sleep(5s); # sleeps for 5 seconds
Not available with PO_NO_PROCESS_CONTROL
Table 3.157. Arguments and Return Values for sleep()
Argument Type | Return Type | Description |
---|---|---|
Causes the current thread to sleep for a number of seconds equal to the argument passed. Returns 0 for success. An integer argument is interpreted as a number of seconds to sleep, relative date/time values are interpreted literally. |
This function does not throw any exceptions.
Returns a list of filesystem values for the file passed, following any symbolic links. See also lstat() for a version of this function that does not follow symbolic links, and see hstat() for a version of this function that returns a user-friendly hash instead of a list.
$mode = stat($filepath)[2];
Not available with PO_NO_FILESYSTEM
This function does not throw any exceptions.
Table 3.159. Stat List Description
Position | Data Type | Description |
---|---|---|
0 | device inode number the file is on | |
1 | inode of the file | |
2 | inode protection mode | |
3 | number of hard links to this file | |
4 | user ID of the owner | |
5 | group ID of the owner | |
6 | device type number | |
7 | file size in bytes | |
8 | last access time of the file | |
9 | last modified time of the file | |
10 | last change time of the file's inode | |
11 | block size | |
12 | blocks allocated for the file |
Causes the current thread to sleep for a certain number of microseconds (1/1000000 second). Note that as with all Qore functions and methods accepting a timeout value, relative date/time values can be given instead of integers to make the source more readable (ie 1250us
). See sleep() for a similar function supporting second resolution.
usleep(date
$time
) returns int
usleep(1250us); # sleeps for 1250 microseconds (1.25 milliseconds)
usleep(500); # sleeps for 500 microseconds (0.5 milliseconds)
Not available with PO_NO_PROCESS_CONTROL
Table 3.162. Arguments and Return Values for usleep()
Argument Type | Return Type | Description |
---|---|---|
| Causes the current thread to sleep for the given number of microseconds (1/1000000 second). Returns 0 for success. | |
| Causes the current thread to sleep for the given period of time with a resolution of microseconds (1/1000000 second). Returns 0 for success. |
This function does not throw any exceptions.
Qore's cryptography support is provided by the OpenSSL library. Most of the encryption and decryption functions in this section accept an optional initialization vector, which is data used as initial input for the first block in chained encryption algorithms. Subsequent blocks take input from the last block encrypted/decrypted. If a function accepts an initialization vector and one is not supplied, then a default value of 8 zero bytes will be used.
Some functions require fixed-length keys, and some allow the use of variable-length keys. For functions requiring fixed-length keys any excess bytes are ignored. The same applies to initialization vector arguments.
The following is an example of a function that uses /dev/random to read in a random key for use with encryption functions:
# read a key from /dev/random and return the key sub get_key($size) { # throw an exception if an invalid key size was passed if (!$size || $size < 0) throw "GET-KEY-ERROR", sprintf("invalid size = %n", $size); my $f = new File(); # File::open2() will throw an exception if /dev/random cannot be opened for reading $f.open2("/dev/random"); return $f.readBinary($size); }
Encrypts data using the Cipher Block Chaining function for the blowfish algorithm using a variable-length key and an optional initialization vector. Returns a binary object of the encrypted data.
blowfish_encrypt_cbc(data
$data
, data $key
, data $iv
= defaultIV) returns binary
$bin = blowfish_encrypt_cbc("hello there", $key);
Table 3.164. Exceptions thrown by blowfish_encrypt_cbc()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Decrypts data using the Cipher Block Chaining function for the blowfish algorithm using a variable-length key. This function returns a binary object, for an equivalent function that decrypts to a string, see blowfish_decrypt_cbc_to_string().
blowfish_decrypt_cbc(binary
$encrypted_data
, data $key
, data $iv
= defaultIV) returns binary
$bin = blowfish_decrypt_cbc($encrypted_binary_data, $key);
Table 3.166. Exceptions thrown by blowfish_decrypt_cbc()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Decrypts data to a string using the Cipher Block Chaining function for the blowfish algorithm using a variable-length key. This function returns a string, for an equivalent function that decrypts to a binary object, see blowfish_decrypt_cbc().
blowfish_decrypt_cbc_to_string(binary
$encrypted_data
, data $key
, data $iv
= defaultIV) returns string
$str = blowfish_decrypt_cbc_to_string($bin, $key);
Table 3.168. Exceptions thrown by blowfish_decrypt_cbc_to_string()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Table 3.169. Arguments and Return Values for des_encrypt_cbc()
Argument Type |
Return Type |
Description |
---|---|---|
Encrypts data using the Cipher Block Chaining function for the DES algorithm. The key must be at least 8-bytes long (only the first 8 bytes will be used). If the init_vector is present it must also be at least 8 bytes long. |
Table 3.170. Exceptions thrown by des_encrypt_cbc()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Decrypts data using the Cipher Block Chaining function for the DES algorithm using an 8 byte key. This function returns a binary object, for an equivalent function that decrypts to a string, see des_decrypt_cbc_to_string().
des_decrypt_cbc(binary
$encrypted_data
, data $key
, data $iv
= defaultIV) returns binary
Table 3.172. Exceptions thrown by des_decrypt_cbc()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Decrypts data using the Cipher Block Chaining function for the DES algorithm using an 8-byte key. This function returns a string, for an equivalent function that decrypts to a binary object, see des_decrypt_cbc().
des_decrypt_cbc_to_string(binary
$encrypted_data
, data $key
, data $iv
= defaultIV) returns string
Table 3.174. Exceptions thrown by des_decrypt_cbc_to_string()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Encrypts data using the Cipher Block Chaining function for the two-key triple DES algorithm using two eight-byte keys (set by a single 16-byte key argument). Returns a binary object of the encrypted data.
des_ede_encrypt_cbc(data
$data
, data $key
, data $iv
= defaultIV) returns binary
$bin = des_ede_encrypt_cbc($text, $key);
Table 3.175. Arguments and Return Values for des_ede_encrypt_cbc()
Argument Type | Return Type | Description |
---|---|---|
Encrypts data using the Cipher Block Chaining function for the two-key triple DES algorithm. The key argument must be at least 16 bytes long; only the first 16 bytes of the key argument will be used for the two 8-byte keys. If the init_vector argument is present, it must be at least 8 bytes long. |
Table 3.176. Exceptions thrown by des_ede_encrypt_cbc()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Decrypts data using the Cipher Block Chaining function for the two-key triple DES algorithm using two eight-byte keys (set by a single 16-byte key argument). This function returns a binary object, for an equivalent function that decrypts to a string, see des_ede_decrypt_cbc_to_string().
des_ede_decrypt_cbc(binary
$encrypted_data
, data $key
, data $iv
= defaultIV) returns binary
$bin = des_ede_decrypt_cbc($data, $key);
Table 3.177. Arguments and Return Values for des_ede_decrypt_cbc()
Argument Type |
Return Type |
Description |
---|---|---|
Decrypts data using the Cipher Block Chaining function for the two-key triple DES algorithm. The key argument must be at least 16 bytes long; only the first 16 bytes of the key argument will be used for the two 8-byte keys. If the init_vector argument is present, it must be at least 8 bytes long. |
Table 3.178. Exceptions thrown by des_ede_decrypt_cbc()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Decrypts data to a string using the Cipher Block Chaining function for the two-key triple DES algorithm using two eight-byte keys (set by a single 16-byte key argument). This function returns a string, for an equivalent function that decrypts to a binary object, see des_ede_decrypt_cbc().
des_ede_decrypt_cbc_to_string(binary
$encrypted_data
, data $key
, data $iv
= defaultIV) returns string
$str = des_ede_decrypt_cbc_to_string($data, $key);
Table 3.179. Arguments and Return Values for des_ede_decrypt_cbc_to_string()
Argument Type |
Return Type |
Description |
---|---|---|
Decrypts data to a string using the Cipher Block Chaining function for the two-key triple DES algorithm. The key argument must be at least 16 bytes long; only the first 16 bytes of the key argument will be used for the two 8-byte keys. If the init_vector argument is present, it must be at least 8 bytes long. |
Table 3.180. Exceptions thrown by des_ede_decrypt_cbc_to_string()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Encrypts data using the Cipher Block Chaining function for the three-key triple DES algorithm using three 8-byte keys (set by a single 24-byte key argument) and an optional 8-byte initialization vector. Returns a binary object of the encrypted data.
des_ede3_encrypt_cbc(data
$data
, data $key
, data $iv
= defaultIV) returns binary
$bin = des_ede3_encrypt_cbc($data, $key);
Table 3.181. Arguments and Return Values for des_ede3_encrypt_cbc()
Argument Type |
Return Type |
Description |
---|---|---|
Encrypts data using the Cipher Block Chaining function for the three-key triple DES algorithm using three 8-byte keys (set by a single 24-byte key argument) and an optional 8-byte initialization vector. Returns a binary object of the encrypted data. |
Table 3.182. Exceptions thrown by des_ede3_encrypt_cbc()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Decrypts data using the Cipher Block Chaining function for the three-key triple DES algorithm using three 8-byte keys (set by a single 24-byte key argument) and an optional 8-byte initialization vector. This function returns a binary object, for an equivalent function that decrypts to a string, see des_ede3_decrypt_cbc_to_string().
des_ede3_decrypt_cbc(binary
$encrypted_data
, data $key
, data $iv
= defaultIV) returns binary
$bin = des_ede3_decrypt_cbc($data, $key);
Table 3.184. Exceptions thrown by des_ede3_decrypt_cbc()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Decrypts data to a string using the Cipher Block Chaining function for the three-key triple DES algorithm using three 8-byte keys (set by a single 24-byte key argument) and an optional 8-byte initialization vector. This function returns a string, for an equivalent function that decrypts to a binary object, see des_ede3_decrypt_cbc().
des_ede3_decrypt_cbc_to_string(binary
$encrypted_data
, data $key
, data $iv
= defaultIV) returns string
$str = des_ede3_decrypt_cbc_to_string($data, $key);
Table 3.185. Arguments and Return Values for des_ede3_decrypt_cbc_to_string()
Argument Type |
Return Type |
Description |
---|---|---|
Decrypts data to a string using the Cipher Block Chaining function for the three-key triple DES algorithm using three 8-byte keys (set by a single 24-byte key argument) and an optional 8-byte initialization vector. |
Table 3.186. Exceptions thrown by des_ede3_decrypt_cbc_to_string()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Encrypts data using the Cipher Block Chaining function for RSA's DESX algorithm using a 24-byte key and an optional 8-byte initialization vector. Returns a binary object of the encrypted data.
desx_encrypt_cbc(data
$data
, data $key
, data $iv
= defaultIV) returns binary
$bin = desx_encrypt_cbc($data, $key);
Table 3.188. Exceptions thrown by desx_encrypt_cbc()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Decrypts data using the Cipher Block Chaining function for RSA's DESX algorithm using a 24-byte key and an optional 8-byte initialization vector. This function returns a binary object, for an equivalent function that decrypts to a string, see desx_decrypt_cbc_to_string().
desx_decrypt_cbc(binary
$encrypted_data
, data $key
, data $iv
= defaultIV) returns binary
my binary $bin = desx_decrypt_cbc($data, $key);
Table 3.190. Exceptions thrown by desx_decrypt_cbc()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Decrypts data to a string using the Cipher Block Chaining function for RSA's DESX algorithm using a 24-byte key and an optional 8-byte initialization vector. This function returns a string, for an equivalent function that decrypts to a binary object, see desx_decrypt_cbc().
desx_decrypt_cbc_to_string(binary
$encrypted_data
, data $key
, data $iv
= defaultIV) returns string
$str = desx_decrypt_cbc_to_string($data, $key);
Table 3.192. Exceptions thrown by desx_decrypt_cbc_to_string()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Encrypts data using the Cipher Block Chaining function for RSA's RC2(tm) algorithm using a variable-length key and an optional 8-byte initialization vector. Returns a binary object of the encrypted data.
rc2_encrypt_cbc(data
$data
, data $key
, data $iv
= defaultIV) returns binary
$bin = rc2_encrypt_cbc($data, $key);
Table 3.194. Exceptions thrown by rc2_encrypt_cbc()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Decrypts data using the Cipher Block Chaining function for RSA's RC2(tm) algorithm using a variable-length key and an optional 8-byte initialization vector. This function returns a binary object, for an equivalent function that decrypts to a string, see rc2_decrypt_cbc_to_string().
rc2_decrypt_cbc(binary
$encrypted_data
, data $key
, data $iv
= defaultIV) returns binary
$bin = rc2_decrypt_cbc($data, $key);
Table 3.196. Exceptions thrown by rc2_decrypt_cbc()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Decrypts data to a string using the Cipher Block Chaining function for RSA's RC2(tm) algorithm using a variable-length key and an optional 8-byte initialization vector. This function returns a string, for an equivalent function that decrypts to a binary object, see rc2_decrypt_cbc().
rc2_decrypt_cbc_to_string(binary
$encrypted_data
, data $key
, data $iv
= defaultIV) returns string
$str = rc2_decrypt_cbc_to_string($data, $key);
Table 3.198. Exceptions thrown by rc2_decrypt_cbc_to_string()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Encrypts data using the Cipher Block Chaining function for the CAST5 algorithm using a variable-length key and an optional 8-byte initialization vector. Returns a binary object of the encrypted data.
cast5_encrypt_cbc(data
$data
, data $key
, data $iv
= defaultIV) returns binary
$bin = cast5_encrypt_cbc($data, $key);
Table 3.200. Exceptions thrown by cast5_encrypt_cbc()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Decrypts data using the Cipher Block Chaining function for the CAST5 algorithm using a variable-length key and an optional 8-byte initialization vector. This function returns a binary object, for an equivalent function that decrypts to a string, see cast5_decrypt_cbc_to_string().
cast5_decrypt_cbc(binary
$encrypted_data
, data $key
, data $iv
= defaultIV) returns binary
$bin = cast5_decrypt_cbc($data, $key);
Table 3.202. Exceptions thrown by cast5_decrypt_cbc()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Decrypts data to a string using the Cipher Block Chaining function for the CAST5 algorithm using a variable-length key and an optional 8-byte initialization vector. This function returns a string, for an equivalent function that decrypts to a binary object, see cast5_decrypt_cbc().
cast5_decrypt_cbc_to_string(binary
$encrypted_data
, data $key
, data $iv
= defaultIV) returns string
$str = cast5_decrypt_cbc_to_string($data, $key);
Table 3.204. Exceptions thrown by cast5_decrypt_cbc_to_string()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Encrypts data using the Alleged RC4 cipher algorithm, which should be compatible with RSA's RC4(tm) algorithm using a variable-length key and an optional 8-byte initialization vector. Returns a binary object of the encrypted data.
rc4_encrypt(data
$data
, data $key
, data $iv
= defaultIV) returns binary
$bin = rc4_encrypt($data, $key);
Table 3.206. Exceptions thrown by rc4_encrypt()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Decrypts data using the Alleged RC4 cipher algorithm, which should be compatible with RSA's RC4(tm) algorithm using a variable-length key and an optional 8-byte initialization vector. This function returns a binary object, for an equivalent function that decrypts to a string, see rc4_decrypt_to_string().
rc4_decrypt(binary
$encrypted_data
, data $key
, data $iv
= defaultIV) returns binary
$bin = rc4_decrypt($data, $key);
Table 3.208. Exceptions thrown by rc4_decrypt()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Decrypts data to a string using the Alleged RC4 cipher algorithm, which should be compatible with RSA's RC4(tm) algorithm using a variable-length key and an optional 8-byte initialization vector. This function returns a string, for an equivalent function that decrypts to a binary object, see rc4_decrypt().
rc4_decrypt_to_string(binary
$encrypted_data
, data $key
, data $iv
= defaultIV) returns string
$str = rc4_decrypt_to_string($data, $key);
Table 3.210. Exceptions thrown by rc4_decrypt_to_string()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
Encrypts data using the Cipher Block Chaining function for RSA's RC5(tm) algorithm using a variable-length key and an optional 8-byte initialization vector. Returns a binary object of the encrypted data. The availability of this function depends on the availability of the RC5 algorithm in the openssl library used to compile the Qore library; for maximum portability check the constant HAVE_RC5
before running this function. See Library Option Constants for a list of all option constants.
rc5_encrypt_cbc(data
$data
, data $key
, data $iv
= defaultIV) returns binary
$bin = rc5_encrypt_cbc($data, $key);
Table 3.212. Exceptions thrown by rc5_encrypt_cbc()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Decrypts data using the Cipher Block Chaining function for RSA's RC5(tm) algorithm using a variable-length key and an optional 8-byte initialization vector. This function returns a binary object, for an equivalent function that decrypts to a string, see rc5_decrypt_cbc_to_string(). The availability of this function depends on the availability of the RC5 algorithm in the openssl library used to compile the Qore library; for maximum portability check the constant HAVE_RC5
before running this function. See Library Option Constants for a list of all option constants.
rc5_decrypt_cbc(binary
$encrypted_data
, data $key
, data $iv
= defaultIV) returns binary
$bin = rc5_decrypt_cbc($data, $key);
Table 3.214. Exceptions thrown by rc5_decrypt_cbc()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Decrypts data to a string using the Cipher Block Chaining function for RSA's RC5(tm) algorithm using a variable-length key and an optional 8-byte initialization vector. This function returns a string, for an equivalent function that decrypts to a binary object, see rc5_decrypt_cbc(). The availability of this function depends on the availability of the RC5 algorithm in the openssl library used to compile the Qore library; for maximum portability check the constant HAVE_RC5
before running this function. See Library Option Constants for a list of all option constants.
rc5_decrypt_cbc_to_string(binary
$encrypted_data
, data $key
, data $iv
= defaultIV) returns string
$str = rc5_decrypt_cbc_to_string($data, $key);
Table 3.216. Exceptions thrown by rc5_decrypt_cbc_to_string()
err |
desc |
---|---|
|
missing data (string or binary) parameter to function, invalid data type (expecing string or binary) |
|
missing or invalid key parameter (ex: invalid size) or invalid initialization vector (less than 8 bytes, only raised if initialization vector present) |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Table 3.218. Exceptions thrown by DSS()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Table 3.220. Exceptions thrown by DSS_bin()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Table 3.222. Exceptions thrown by DSS1()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Table 3.224. Exceptions thrown by DSS1()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Table 3.226. Exceptions thrown by MD2()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Table 3.228. Exceptions thrown by MD2_bin()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Table 3.230. Exceptions thrown by MD4()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Table 3.232. Exceptions thrown by MD4_bin()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Table 3.234. Exceptions thrown by MD5()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Table 3.236. Exceptions thrown by MD5_bin()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Returns the MDC2 message digest of the supplied argument (for strings, the trailing null character is not included in the digest). The availability of this function depends on the availability of the MDC2 algorithm in the openssl library used to compile the Qore library; for maximum portability check the constant HAVE_MDC2
before running this function. See Library Option Constants for a list of all option constants.
$str = MDC2("hello");
Table 3.238. Exceptions thrown by MDC2()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Returns the MDC2 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) as a binary object. The availability of this function depends on the availability of the MDC2 algorithm in the openssl library used to compile the Qore library; for maximum portability check the constant HAVE_MDC2
before running this function. See Library Option Constants for a list of all option constants.
$bin = MDC2_bin("hello");
Table 3.240. Exceptions thrown by MDC2_bin()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Table 3.242. Exceptions thrown by RIPEMD160()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Returns the RIPEMD160 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) as a binary object.
RIPEMD160_bin(data) returns binary
$str = RIPEMD160_bin("hello"); # returns "108f07b8382412612c048d07d13f814118445acd"
Table 3.244. Exceptions thrown by RIPEMD160_bin()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Table 3.246. Exceptions thrown by SHA()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Table 3.248. Exceptions thrown by SHA_bin()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Table 3.250. Exceptions thrown by SHA1()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Table 3.252. Exceptions thrown by SHA1_bin()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Returns the SHA224 message digest of the supplied argument as a string of hex characters. For string arguments, the trailing null character is not included in the digest. The availability of this function depends on the availability of the SHA224 algorithm in the openssl library used to compile the Qore library; for maximum portability check the constant HAVE_SHA224
before running this function. See Library Option Constants for a list of all option constants.
$str = SHA224("hello"); # "ea09ae9cc6768c50fcee903ed054556e5bfc8347907f12598aa24193"
Table 3.254. Exceptions thrown by SHA224()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Returns the SHA224 message digest of the supplied argument as a string of hex characters. For string arguments, the trailing null character is not included in the digest. The availability of this function depends on the availability of the SHA224 algorithm in the openssl library used to compile the Qore library; for maximum portability check the constant HAVE_SHA224
before running this function. See Library Option Constants for a list of all option constants.
SHA224_bin(data) returns binary
$bin = SHA224_bin("hello"); # <ea09ae9cc6768c50fcee903ed054556e5bfc8347907f12598aa24193>
Table 3.256. Exceptions thrown by SHA224_bin()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Returns the SHA256 message digest of the supplied argument as a string of hex characters. For string arguments, the trailing null character is not included in the digest. The availability of this function depends on the availability of the SHA256 algorithm in the openssl library used to compile the Qore library; for maximum portability check the constant HAVE_SHA256
before running this function. See Library Option Constants for a list of all option constants.
SHA256_bin(data) returns binary
$str = SHA256("hello"); # "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
Table 3.258. Exceptions thrown by SHA256()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Returns the SHA256 message digest of the supplied argument as a string of hex characters. For string arguments, the trailing null character is not included in the digest. The availability of this function depends on the availability of the SHA256 algorithm in the openssl library used to compile the Qore library; for maximum portability check the constant HAVE_SHA256
before running this function. See Library Option Constants for a list of all option constants.
SHA256_bin(data) returns binary
$bin = SHA256_bin("hello"); # <2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824>
Table 3.260. Exceptions thrown by SHA256_bin()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Returns the SHA384 message digest of the supplied argument as a string of hex characters. For string arguments, the trailing null character is not included in the digest. The availability of this function depends on the availability of the SHA384 algorithm in the openssl library used to compile the Qore library; for maximum portability check the constant HAVE_SHA384
before running this function. See Library Option Constants for a list of all option constants.
SHA384_bin(data) returns binary
$str = SHA384("hello"); # "59e1748777448c69de6b800d7a33bbfb9ff1b463e44354c3553bcdb9c666fa90125a3c79f90397bdf5f6a13de828684f"
Table 3.262. Exceptions thrown by SHA384()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Returns the SHA384 message digest of the supplied argument as a string of hex characters. For string arguments, the trailing null character is not included in the digest. The availability of this function depends on the availability of the SHA384 algorithm in the openssl library used to compile the Qore library; for maximum portability check the constant HAVE_SHA384
before running this function. See Library Option Constants for a list of all option constants.
SHA384_bin(data) returns binary
$bin = SHA384_bin("hello"); # <59e1748777448c69de6b800d7a33bbfb9ff1b463e44354c3553bcdb9c666fa90125a3c79f90397bdf5f6a13de828684f>
Table 3.264. Exceptions thrown by SHA384_bin()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Returns the SHA512 message digest of the supplied argument as a string of hex characters. For string arguments, the trailing null character is not included in the digest. The availability of this function depends on the availability of the SHA512 algorithm in the openssl library used to compile the Qore library; for maximum portability check the constant HAVE_SHA512
before running this function. See Library Option Constants for a list of all option constants.
SHA512_bin(data) returns binary
$str = SHA512("hello"); # "9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043"
Table 3.266. Exceptions thrown by SHA512()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Returns the SHA512 message digest of the supplied argument as a string of hex characters. For string arguments, the trailing null character is not included in the digest. The availability of this function depends on the availability of the SHA512 algorithm in the openssl library used to compile the Qore library; for maximum portability check the constant HAVE_SHA512
before running this function. See Library Option Constants for a list of all option constants.
SHA512_bin(data) returns binary
$bin = SHA512_bin("hello"); # <9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043>
Table 3.268. Exceptions thrown by SHA512_bin()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
The following functions return information about or are related to the filesystem. See the File class for a class enabling files to be created, read or written, and the Dir class allowing directories to be manipulated.
Changes the current working directory.
chdir("/usr/share");
Not available with PO_NO_FILESYSTEM
Table 3.270. Exceptions Thrown by chdir()
err | desc |
---|---|
| The string for the new directory was missing from the call. |
Changes the mode of a file.
chmod("/bin/login", 0755);
Not available with PO_NO_FILESYSTEM
Table 3.272. Exceptions Thrown by chmod()
err | desc |
---|---|
| Either the filename or the mode was missing from the call. |
Changes the user and group owners of a file, if the current user has permission to do so (normally only the superuser can change the user owner), follows symbolic links. For a version of this function that does not follow symbolic links, see the lchown() function.
chown("/bin/login", 0, 0);
Not available with PO_NO_FILESYSTEM
Returns a string giving the current working directory or NOTHING if the current working directory could not be read.
See getcwd2() for a similar function that throws an exception if an error occurs instead.
my $cwd = getcwd();
Not available with PO_NO_FILESYSTEM
or PO_NO_EXTERNAL_INFO
Returns a string giving the current working directory; throws an exception if the current directory cannot be read.
See getcwd() for a similar function that returns NOTHING instead of throwing an exception if an error occurs.
my string $cwd = getcwd2();
Not available with PO_NO_FILESYSTEM
or PO_NO_EXTERNAL_INFO
Table 3.275. Arguments and Return Values for getcwd2()
Argument Type | Return Type | Description |
---|---|---|
n/a | Returns the complete path of the current working directory as a string. |
Table 3.276. Exceptions Thrown by getcwd2()
err | desc |
---|---|
| The operating system error is reported in the description string. |
Returns a hash of filesystem values for the file passed; symbolic links are not followed; information is returned about symbolic links (see hstat() for a version of this function that follows symbolic links).
$type = hlstat("/bin/sh").type; # returns "REGULAR"
Not available with PO_NO_FILESYSTEM
Table 3.277. Arguments and Return Values for hlstat()
Argument Type | Return Type | Description |
---|---|---|
| Returns a hash of filesystem values for the file passed or NOTHING if the |
Table 3.278. Stat Hash Description
Key | Value Description |
---|---|
| device inode number the file is on |
| inode of the file |
| inode protection mode |
| number of hard links to this file |
| user ID of the owner |
| group ID of the owner |
| device type number |
| file size in bytes |
| last access time of the file |
| last modified time of the file |
| last change time of the file's inode |
| block size |
| blocks allocated for the file |
| a string indicating the type of file: 'BLOCK-DEVICE', 'DIRECTORY', 'CHARACTER-DEVICE', 'FIFO', 'SYMBOLIC-LINK', 'SOCKET', 'CHARACTER-DEVICE', 'REGULAR', 'UNKNOWN' |
This function does not throw any exceptions.
Returns a hash of filesystem values for the file passed; symbolic links are followed; see hlstat() to retrieve information about a symbolic link.
$type = hstat("/bin/sh").type; # returns "REGULAR"
Not available with PO_NO_FILESYSTEM
This function does not throw any exceptions.
Returns True
if the string passed identifies a block device file on the filesystem.
$bool = is_bdev("/dev/sda");
Not available with PO_NO_FILESYSTEM
Returns True
if the string passed identifies a character device file on the filesystem.
$bool = is_cdev("/dev/tty");
Not available with PO_NO_FILESYSTEM
Returns True
if the string passed identifies a device file (either block or character) on the filesystem.
$bool = is_dev("/dev/sda");
Not available with PO_NO_FILESYSTEM
Returns True
if the string passed identifies a directory on the filesystem.
$bool = is_dir("/usr/share");
Not available with PO_NO_FILESYSTEM
Returns True
if the string passed identifies an executable file.
is_executable(string
$path
) returns bool (CONST)
$bool = is_executable("/bin/sh");
Not available with PO_NO_FILESYSTEM
Returns True
if the string passed identifies a regular file on the filesystem.
$bool = is_file("/etc/hosts");
Not available with PO_NO_FILESYSTEM
Returns True
if the string passed identifies a symbolic link on the filesystem.
$bool = is_link("/bin/sh");
Not available with PO_NO_FILESYSTEM
Returns True
if the string passed identifies a pipe (FIFO) on the filesystem.
$bool = is_pipe("/bin/sh");
Not available with PO_NO_FILESYSTEM
Returns True
if the string passed identifies a file readable by the current user.
is_readable(string
$path
) returns bool (CONST)
$bool = is_readable("/etc/hosts");
Not available with PO_NO_FILESYSTEM
Returns True
if the string passed identifies a socket on the filesystem.
$bool = is_socket("/tmp/X0");
Not available with PO_NO_FILESYSTEM
Returns True
if the string passed identifies a file writable by the current user.
is_writeable(string
$path
) returns bool (CONST)
$bool = is_writeable("/etc/hosts");
Not available with PO_NO_FILESYSTEM
Changes the user and group owners of a file, if the current user has permission to do so (normally only the superuser can change the user owner), does not follow symbolic links. For a version of this function that follows symbolic links, see the chown() function.
lchown(string
$path
, softint $uid
= -1, softint $gid
= -1) returns int
lchown("/bin/login", 0, 0);
Not available with PO_NO_FILESYSTEM
Returns a list of filesystem values for the file or symbolic link passed. Does not follow symbolic links, but rather returns filesystem information for symbolic links. See also stat() for a version of this function that follows symbolic links, and hlstat() for a version of this function that returns a user-friendly hash instead of a list.
$list = lstat(("/bin/sh");
Not available with PO_NO_FILESYSTEM
This function does not throw any exceptions.
Creates a directory, optionally specifying the mode.
mkdir("/tmp/newdir", 0755);
Not available with PO_NO_FILESYSTEM
Creates a named pipe file with an optional file mode (default = 0600).
mkfifo("/tmp/pipe");
Not available with PO_NO_FILESYSTEM
This function does not throw any exceptions.
Returns the target of a symbolic link; throws an exception if an error occurs (ex: file does not exist or is not a symbolic link).
my string $str = readlink("/tmp/symbolic_link");
Not available with PO_NO_FILESYSTEM
Table 3.296. Exceptions Thrown by readlink()
err | desc |
---|---|
| Invalid arguments or a system error occured (ex: file does not exist or is not a symbolic link). |
Renames (or moves) files or directories. Note that for this call to function properly, the Qore process must have sufficient permissions and access to the given filesystem objects or paths to execute the rename operation.
This function does not return any value; if any errors occur, an exception is thrown.
rename("/tmp/temp_file", "/home/test/test_file.txt");
Not available with PO_NO_FILESYSTEM
Table 3.298. Exceptions Thrown by rename()
err | desc |
---|---|
| Invalid arguments or a system error occured. |
Removes a directory.
rmdir("/tmp/newdir");
Not available with PO_NO_FILESYSTEM
This section documents functions for compressing and uncompressing data.
Uncompresses the given data with the bzip2 algorithm and returns the uncompressed data as a binary.
bunzip2_to_binary(binary
$bin
) returns binary
bunzip2_to_binary() returns nothing (RT_NOOP)
$bin = bunzip2_to_binary($data);
Table 3.303. Exceptions Thrown by bunzip2_to_binary()
err | desc |
---|---|
| bzlib returned an error while processing. |
Uncompresses the given data with the bzip2 algorithm and returns the uncompressed data as a string. An optional second string argument may be passed to give the character encoding of the string; if not present, the default character encoding for the process is assumed.
bunzip2_to_string(binary
$bin
, string $encoding
= defaultEncoding
) returns string
bunzip2_to_string() returns nothing (RT_NOOP)
$str = bunzip2_to_string($bzip2_string);
Table 3.304. Arguments and Return Values for bunzip2_to_string()
Argument Type | Return Type | Description |
---|---|---|
Uncompresses the input data and returns a string. The optional second argument sets the string |
Table 3.305. Exceptions Thrown by bunzip_to_string()
err | desc |
---|---|
| bzlib returned an error while processing. |
Compresses the given data with the bzip2 algorithm and returns the uncompressed data as a binary. The optional second argument specifies the compression level; if no second argument is given, a value of 9 is used, taking the most memory and proving the best compression ratio. The second argument if given must be a value from 1 - 9. Note that strings are compressed without the trailing null character.
bzip2(data $bin
, softint $level
= 9) returns binary
$bin = compress("hello");
Table 3.306. Arguments and Return Values for bzip2()
Argument Type | Return Type | Description |
---|---|---|
Compresses the input data and returns a binary object. The optional |
Table 3.307. Exceptions Thrown by bzip2()
err | desc |
---|---|
| The bzip2 library reported an error while performing the compression. |
| The level argument was not between 1 and 9 inclusive. |
Performs zlib-based "deflate" data compression (RFC 1951) and returns a binary object of the compressed data. The optional second argument specifies the compression level; if no second argument is given, then a tradeoff between speed and compression size is taken (default: Z_DEFAULT_COMPRESSION
, meaning to let zlib use its default compression ratio). Note that strings are compressed without the trailing null character.
compress(data
$bin
, softint $level
= Z_DEFAULT_COMPRESSION) returns binary
$bin = compress("hello");
Table 3.308. Arguments and Return Values for compress()
Argument Type | Return Type | Description |
---|---|---|
Compresses the input data and returns a binary object. The optional |
Table 3.309. Exceptions Thrown by compress()
err | desc |
---|---|
| the compression level is invalid (must be between 1 - 9 inclusive). |
| zlib returned an error while processing. |
Uncompresses gzipped data using zlib functions and returns a binary object of the uncompressed data.
gunzip_to_binary(binary
$bin
) returns binary
gunzip_to_binary() returns nothing (RT_NOOP)
$bin = gunzip_to_binary($data);
Table 3.311. Exceptions Thrown by gunzip_to_binary()
err | desc |
---|---|
| zlib returned an error while processing. |
Uncompresses gzipped data using zlib functions and returns a string of the uncompressed data. An optional second string argument may be passed to give the character encoding of the string; if not present, the default character encoding for the process is assumed.
gunzip_to_string(binary
$bin
) returns string
gunzip_to_string(binary
$bin
, string $encoding
) returns string
gunzip_to_string() returns nothing (RT_NOOP)
$str = gunzip_to_string($gzipped_string);
Table 3.312. Arguments and Return Values for gunzip_to_string()
Argument Type | Return Type | Description |
---|---|---|
Uncompresses the input data and returns a string. The optional second argument sets the string |
Table 3.313. Exceptions Thrown by gunzip_to_string()
err | desc |
---|---|
| zlib returned an error while processing. |
Performs zlib-based "gzip" data compression (RFC 1952) and returns a binary object of the compressed data. The optional second argument specifies the compression level between 1 (lowest comperssion level) and 9 (highest compression level); if no second argument is given, then a tradeoff between speed and compression size is taken (default: Z_DEFAULT_COMPRESSION
). Note that strings are compressed without the trailing null character.
gzip(string
$data
, softint $level
= Z_DEFAULT_COMPRESSION) returns binary
$bin = gzip($data);
Table 3.314. Arguments and Return Values for gzip()
Argument Type | Return Type | Description |
---|---|---|
Compresses the input data and returns a binary object of the gzipped data. The optional |
Table 3.315. Exceptions Thrown by gzip()
err | desc |
---|---|
| the compression level is invalid (must be between 1 - 9 inclusive). |
| zlib returned an error while processing. |
Uncompresses data using zlib functions and returns a binary object of the uncompressed data.
uncompress_to_binary(binary
$bin
) returns binary
uncompress_to_binary() returns nothing (RT_NOOP)
$bin = uncompress_to_binary($compressed_data);
Table 3.317. Exceptions Thrown by uncompress_to_binary()
err | desc |
---|---|
| zlib returned an error while processing. |
Uncompresses data using zlib functions and returns a string of the uncompressed data. An optional second string argument may be passed to give the character encoding of the string; if not present, the default character encoding for the process is assumed.
uncompress_to_string(binary
$bin
) returns string
uncompress_to_string(binary
$bin
, string $encoding
) returns string
uncompress_to_string() returns nothing (RT_NOOP)
$str = uncompress_to_string($compressed_data);
Table 3.318. Arguments and Return Values for uncompress_to_string()
Argument Type | Return Type | Description |
---|---|---|
Uncompresses the input data and returns a string. The optional second argument sets the string |
Table 3.319. Exceptions Thrown by uncompress_to_string()
err | desc |
---|---|
| zlib returned an error while processing. |
Table 3.321. Exceptions Thrown by backquote()
err | desc |
---|---|
| An error occurred with the |
Calls a builtin function and returns the return value, passing the remaining arguments after the function name to the builtin function. This function can be used to override a builtin function's functionality with a custom implementation.
call_builtin_function(string
$name
, ...) returns any
$result = call_builtin_function("func_name", $arg1, $arg2);
Table 3.323. Exceptions Thrown by call_builtin_function()
err | desc |
---|---|
| Parse options do not allow access to the function. |
| The builtin function does not exist. |
Calls a builtin function and returns the return value, using the optional second argument as a list of arguments for the function.
call_builtin_function_args(string
$name
, list $args
) returns any
call_builtin_function_args(string
$name
, any $arg
) returns any
call_builtin_function_args("func_name", $arg_list);
Table 3.325. Exceptions Thrown by call_builtin_function_args()
err | desc |
---|---|
| Parse options do not allow access to the function. |
| The builtin function does not exist. |
Calls a function, closure, or call reference and returns the return value, passing the remaining arguments after the function name to the function, closure, or call reference.
call_function(string
$name
, ...) returns any
call_function(code
$code
, ...) returns any
$result = call_function("func_name", $arg1, $arg2);
$result = call_function($call_ref, $arg1, $arg2);
Table 3.326. Arguments and Return Values for call_function()
Argument Type | Return Type | Description |
---|---|---|
Executes the given function, closure, or call reference with the remainder of the arguments as the arguments to the function, closure, or call reference to be called. |
Table 3.327. Exceptions Thrown by call_function()
err | desc |
---|---|
| Parse options do not allow access to the function. |
| The function does not exist. |
Calls a function, closure, or call reference and returns the return value, using the optional second argument as a list of arguments for the function, closure, or call reference to be called.
call_function_args(string
$name
, list $args
) returns any
call_function_args(string
$name
, any $arg
) returns any
call_function_args(code
$code
, list $args
) returns any
call_function_args(code
$code
, any $arg
) returns any
call_function_args("func_name", $arg_list);
call_function_args($call_ref, $arg_list);
Table 3.329. Exceptions Thrown by call_function_args()
err | desc |
---|---|
| Parse options do not allow access to the function. |
| The function does not exist. |
Calls a method of an object, passing the remainder of the arguments to the function as arguments to the method.
callObjectMethod(object
$obj
, string $method
, ...) returns any
callObjectMethod() returns nothing (RT_NOOP)
$result = callObjectMethod($obj, "method", $arg1, $arg2);
Table 3.331. Exceptions Thrown by callObjectMethod()
err | desc |
---|---|
| The named method does not exist in this class. |
| The named method may not be called explicitly. |
| The named method is private and therefore can only be called within the class. |
| The named method is a member of a privately inherited base class. |
Calls a method of an object, using the optional third argument as the argument list to the method.
callObjectMethodArgs(object
$obj
, string $method
, list $args
) returns any
callObjectMethodArgs(object
$obj
, string $method
, any $arg
) returns any
callObjectMethodArgs() returns nothing (RT_NOOP)
$result = callObjectMethodArgs($obj, "method", $arg_list);
Table 3.333. Exceptions Thrown by callObjectMethodArgs()
err | desc |
---|---|
| The named method does not exist in this class. |
| The named method may not be called explicitly. |
| The named method is private and therefore can only be called within the class. |
| The named method is a member of a privately inherited base class. |
Returns True
if the function exists in the current program's function name space.
existsFunction(string
$name
) returns bool (CONST)
existsFunction(code
$code
) returns bool (NOOP)
existsFunction() returns nothing (RT_NOOP)
$bool = existsFunction("func_name");
This function does not throw any exceptions.
Returns "builtin", "user", or NOTHING according to the function name passed.
functionType(string) returns any (CONST)
functionType() returns nothing (RT_NOOP)
$type = functionType("print");
This function does not throw any exceptions.
Returns the byte value of the offset (starting with 0) in the object passed. Of no offset is passed, then the value of the first byte (offset 0) is returned. Note that the [] operator provides a more efficient way to retrieve a byte from a binary object.
Note that this function is identical to getByte() except that this version has no RT_NOOP
variant.
get_byte(data
$data
, softint $offset
$offset
= 0) returns any (CONST)
$byte = get_byte($bin, 2); # returns the third byte of the binary object
Returns the 16-bit integer value at the 2-byte offset (starting with 0) in the data passed. Of no offset is passed, then the value of the first 16-bit position at offset 0 is returned. Note that the [] operator provides a more efficient way to retrieve a byte from a binary object.
This function assumes MSB byte order when retrieving the value from the data.
See also get_word_16_lsb().
get_word_16(data
$data
, softint $offset
= 0) returns any (CONST)
$val = get_word_16($bin, 2); # returns the third 16-bit value in MSB format of the binary object
Table 3.337. Arguments and Return Values for get_word_16()
Arguments | Return Type | Description |
---|---|---|
The MSB integer value of the data at the 2-byte offset given in the string or binary object. If no offset is passed, then the first 16-bit value is returned. If the object is empty or the offset is larger than the object's size, then no value is returned. |
Returns the 16-bit integer value at the 2-byte offset (starting with 0) in the data passed. Of no offset is passed, then the value of the first 16-bit position at offset 0 is returned. Note that the [] operator provides a more efficient way to retrieve a byte from a binary object.
This function assumes LSB byte order when retrieving the value from the data.
See also get_word_16().
get_word_16_lsb(data
$data
, softint $offset
= 0) returns any (CONST)
$val = get_word_16_lsb($bin, 2); # returns the third 16-bit value in LSB format of the binary object
Table 3.338. Arguments and Return Values for get_word_16_lsb()
Arguments | Return Type | Description |
---|---|---|
The LSB integer value of the data at the 2-byte offset given in the string or binary object. If no offset is passed, then the first 16-bit value is returned. If the object is empty or the offset is larger than the object's size, then no value is returned. |
Returns the 32-bit integer value at the 4-byte offset (starting with 0) in the data passed. Of no offset is passed, then the value of the first 32-bit position at offset 0 is returned. Note that the [] operator provides a more efficient way to retrieve a byte from a binary object.
This function assumes MSB byte order when retrieving the value from the data.
Note that this function is identical to getWord32() except that this version has no RT_NOOP
variant.
See also get_word_32_lsb().
get_word_32(data
$data
, softint $offset
= 0) returns any (CONST)
$val = get_word_32($bin, 2); # returns the third 32-bit value in MSB format of the binary object
Table 3.339. Arguments and Return Values for get_word_32()
Arguments | Return Type | Description |
---|---|---|
The MSB integer value of the data at the 4-byte offset given in the string or binary object. If no offset is passed, then the first 32-bit value is returned. If the object is empty or the offset is larger than the object's size, then no value is returned. |
Returns the 32-bit integer value at the 4-byte offset (starting with 0) in the data passed. Of no offset is passed, then the value of the first 32-bit position at offset 0 is returned. Note that the [] operator provides a more efficient way to retrieve a byte from a binary object.
This function assumes LSB byte order when retrieving the value from the data.
See also get_word_32().
get_word_32_lsb(data
$data
, softint $offset
= 0) returns any (CONST)
$val = get_word_32_lsb($bin, 2); # returns the third 32-bit value in LSB format of the binary object
Table 3.340. Arguments and Return Values for get_word_32_lsb()
Arguments | Return Type | Description |
---|---|---|
The LSB integer value of the data at the 4-byte offset given in the string or binary object. If no offset is passed, then the first 32-bit value is returned. If the object is empty or the offset is larger than the object's size, then no value is returned. |
Returns the 64-bit integer value at the 8-byte offset (starting with 0) in the data passed. Of no offset is passed, then the value of the first 64-bit position at offset 0 is returned. Note that the [] operator provides a more efficient way to retrieve a byte from a binary object.
This function assumes MSB byte order when retrieving the value from the data.
See also get_word_64_lsb().
get_word_64(data
$data
, softint $offset
= 0) returns any (CONST)
$val = get_word_64($bin, 2); # returns the third 64-bit value in MSB format of the binary object
Table 3.341. Arguments and Return Values for get_word_64()
Arguments | Return Type | Description |
---|---|---|
The MSB integer value of the data at the 8-byte offset given in the string or binary object. If no offset is passed, then the first 64-bit value is returned. If the object is empty or the offset is larger than the object's size, then no value is returned. |
Returns the 64-bit integer value at the 8-byte offset (starting with 0) in the data passed. Of no offset is passed, then the value of the first 64-bit position at offset 0 is returned. Note that the [] operator provides a more efficient way to retrieve a byte from a binary object.
This function assumes LSB byte order when retrieving the value from the data.
See also get_word_64().
get_word_64_lsb(data
$data
, softint $offset
= 0) returns any (CONST)
$val = get_word_64_lsb($bin, 2); # returns the third 64-bit value in LSB format of the binary object
Table 3.342. Arguments and Return Values for get_word_64_lsb()
Arguments | Return Type | Description |
---|---|---|
The LSB integer value of the data at the 8-byte offset given in the string or binary object. If no offset is passed, then the first 64-bit value is returned. If the object is empty or the offset is larger than the object's size, then no value is returned. |
Returns a hash of library build and version info with the keys in the table Library Info Hash. For constants giving the same information, see Build and Version Constants.
get_qore_library_info() returns hash (CONST)
$info = get_qore_library_info();
Table 3.343. Arguments and Return Values for get_qore_library_info()
Arguments | Return Type | Description |
---|---|---|
n/a | A hash of library build and version info with the keys in the table Library Info Hash. For constants giving the same information, see Build and Version Constants. |
This function does not throw any exceptions.
Table 3.344. Library Info Hash
Key | Description |
---|---|
| The operating system used to build the Qore library. |
| The CPU used as a target for the Qore library build. |
| The full version string for this version of the Qore library. |
| An integer giving the Qore library's major version number. |
| An integer giving the Qore library's minor version number. |
| An integer giving the Qore library's release version number. |
| An integer giving the Qore library's subversion revision number. |
| A string giving information about the host used to compile the Qore library. |
| The compiler used to build the Qore library. |
| The module directory assumed by default in the Qore library. |
| The compiler flags used to compile the Qore library. |
| The linker flags used to link the Qore library. |
Returns a list of hashes giving information about Qore library options for the current build. See Library Option Hash for information about the elements in the list returned. See Library Options for information about Qore library options.
get_qore_option_list() returns list (CONST)
$list = get_qore_option_list();
Table 3.345. Arguments and Return Values for get_qore_option_list()
Arguments | Return Type | Description |
---|---|---|
n/a | A list of hashes giving information about Qore library options for the current build. See Library Option Hash for information about the elements in the list returned. |
Table 3.346. Library Option Hash
Key | Description |
---|---|
| The string description of the option |
| A string giving the name of the constant that has the boolean value for this option. |
| The type of option. |
| The boolean value of the option. |
This function does not throw any exceptions.
Returns the byte value of the offset (starting with 0) in the object passed. Of no offset is passed, then the value of the first byte (offset 0) is returned. Note that the [] operator provides a more efficient way to retrieve a byte from a binary object.
getByte(data
$data
, softint $offset
= 0) returns any (CONST)
$byte = getByte($bin, 2); # returns the third byte of the binary object
Returns the class name of an object.
getClassName(object) returns string (CONST)
getClassName() returns nothing (RT_NOOP)
$name = getClassName($obj);
This function does not throw any exceptions.
Returns an integer representing the capabilities of a DBI driver corresponding to the driver name passed as an argument. See SQL constants for constants for names of drivers shipping with the qore distribution.
getDBIDriverCapabilities(string) returns any
getDBIDriverCapabilities() returns nothing (RT_NOOP)
$caps = getDBIDriverCapabilities("oracle");
Table 3.349. Arguments and Return Values for getDBIDriverCapabilities()
Argument Type | Return Type | Description |
---|---|---|
Returns an integer representing the capabilities of a DBI driver binary-OR'ed together (see DBI Capability Constants). Returns NOTHING if the driver cannot be found. |
This function does not throw any exceptions.
Returns a list of each capability supported by the given DBI driver. See SQL constants for constants giving names of drivers shipping with the Qore distribution.
getDBIDriverCapabilityList(string) returns any
getDBIDriverCapabilityList() returns nothing (RT_NOOP)
$list = getDBIDriverCapabilityList("mysql");
Table 3.350. Arguments and Return Values for getDBIDriverCapabilityList()
Argument Type | Return Type | Description |
---|---|---|
Returns a list of each capability supported by the given DBI driver (see DBI Capability Constants). Returns NOTHING if the driver cannot be found. |
This function does not throw any exceptions.
Returns a list of strings of DBI drivers currently loaded.
getDBIDriverList() returns any
$list = getDBIDriverList();
Table 3.351. Arguments and Return Values for getDBIDriverList()
Argument Type | Return Type | Description |
---|---|---|
n/a | Returns a list of strings of DBI drivers currently loaded. |
This function does not throw any exceptions.
Returns a list of strings of the builtin and module-supplied features of Qore.
getFeatureList() returns list (CONST)
$list = getFeatureList();
Table 3.352. Arguments and Return Values for getFeatureList()
Argument Type | Return Type | Description |
---|---|---|
n/a | Returns a list of strings of the builtin and module-supplied features of Qore. |
This function does not throw any exceptions.
Returns a list of strings of the names of the methods of the class of the object passed as a parameter.
getMethodList(object) returns list (CONST)
getMethodList() returns nothing (RT_NOOP)
$list = getMethodList($obj);
This function does not normally throw any exceptions, however an OBJECT-ALREADY-DELETED
exception could be raised if there is a race condition and a stale pointer to an object is accessed with this function.
Returns a list of hashes describing the currently-loaded Qore modules.
getModuleList() returns list (CONST)
$list = getModuleList();
Table 3.354. Arguments and Return Values for getModuleList()
Argument Type | Return Type | Description |
---|---|---|
n/a | Each element in the list is a hash describing currently-loaded qore modules. |
This function does not throw any exceptions.
Returns the name of the default character encoding for the currently-running Qore process.
get_default_encoding() returns string (CONST)
$encoding = get_default_encoding();
Table 3.355. Arguments and Return Values for get_default_encoding()
Argument Type | Return Type | Description |
---|---|---|
n/a | Returns the name of the default character encoding. |
This function does not throw any exceptions.
Returns a group information hash representing the group information for the group ID passed; or, if the group ID does not exist NOTHING is returned.
For a similar function that throws an exception if the group ID is invalid, see getgrgid2().
my hash $hash = getgrgid(0); # returns the login information for root
Not available with PO_NO_EXTERNAL_INFO
Table 3.356. Arguments and Return Values for getgrgid()
Argument Type |
Return Type |
Description |
---|---|---|
|
Returns a hash representing the group information for the group ID passed. If the gid does not exist, NOTHING is returned. See the Group Information Hash for information about the return value. |
This function does not throw any exceptions.
Returns a group information hash representing the group information for the group ID passed. If the group ID does not exist, an exception is raised.
For a similar function that does not throw an exception if the group ID is invalid, see getgrgid().
my hash $hash = getgrgid2(0); # returns the login information for root
Not available with PO_NO_EXTERNAL_INFO
Table 3.358. Arguments and Return Values for getgrgid2()
Argument Type |
Return Type |
Description |
---|---|---|
|
Returns a hash representing the group information for the group ID passed. If the gid does not exist, an exception is thrown. See the Group Information Hash for information about the return value. |
Table 3.359. Exceptions Thrown by getgrgid2()
err | desc |
---|---|
| The group information could not be retrieved (group does not exist or other error in call) |
Returns a group information hash representing the group information for the group name passed; or, if the group name does not exist NOTHING is returned.
For a similar function that throws an exception if the group ID is invalid, see getgrnam2().
my hash $hash = getgrnam("root"); # returns the login information for root
Not available with PO_NO_EXTERNAL_INFO
Table 3.360. Arguments and Return Values for getgrnam()
Argument Type |
Return Type |
Description |
---|---|---|
|
Returns a hash representing the group information for the group name passed. If the group name does not exist, NOTHING is returned. See the Group Information Hash for information about the return value. |
This function does not throw any exceptions.
Returns a group information hash representing the group information for the group name passed. If the group name does not exist, an exception is rasied.
For a similar function that does not throw an exception if the group ID is invalid, see getgrnam().
my hash $hash = getgrnam2("root"); # returns the login information for root
Not available with PO_NO_EXTERNAL_INFO
Table 3.361. Arguments and Return Values for getgrnam2()
Argument Type |
Return Type |
Description |
---|---|---|
|
Returns a hash representing the group information for the group name passed. If the group name does not exist, an exception is thrown. See the Group Information Hash for information about the return value. |
Table 3.362. Exceptions Thrown by getgrnam2()
err | desc |
---|---|
| The group information could not be retrieved (group does not exist or other error in call) |
Returns a password information hash representing the user information for the user name passed; or, if the user name does not exist NOTHING is returned.
For a similar function that throws an exception if the user ID is invalid, see getpwnam2().
my hash $hash = getpwnam("root"); # returns the login information for root
Not available with PO_NO_EXTERNAL_INFO
Table 3.363. Arguments and Return Values for getpwnam()
Argument Type |
Return Type |
Description |
---|---|---|
|
Returns a hash representing the user information for the user name passed. If the user name does not exist, NOTHING is returned. See the Password Information Hash for information about the return value. |
This function does not throw any exceptions.
Table 3.364. Password Information Hash
Key | Type | Description |
---|---|---|
| The username of the user. | |
| The encrypted password for the user. | |
| The real name or description of the user. | |
| The user's home directory. | |
| The user's login shell. | |
| The user's userid. | |
| The group id of the user's primary group. |
Returns a password information hash representing the user information for the user name passed. If the user name does not exist, an exception is rasied.
For a similar function that does not throw an exception if the user ID is invalid, see getpwnam().
my hash $hash = getpwnam2("root"); # returns the login information for root
Not available with PO_NO_EXTERNAL_INFO
Table 3.365. Arguments and Return Values for getpwnam2()
Argument Type |
Return Type |
Description |
---|---|---|
|
Returns a hash representing the user information for the user name passed. If the user name does not exist, an exception is thrown. See the Password Information Hash for information about the return value. |
Table 3.366. Exceptions Thrown by getpwnam2()
err | desc |
---|---|
| The user information could not be retrieved (user does not exist or other error in call) |
Returns a password information hash representing the user information for the user ID passed; or, if the user ID does not exist NOTHING is returned.
For a similar function that throws an exception if the user ID is invalid, see getpwuid2().
my hash $hash = getpwuid(0); # returns the login information for root
Not available with PO_NO_EXTERNAL_INFO
Table 3.367. Arguments and Return Values for getpwuid()
Argument Type |
Return Type |
Description |
---|---|---|
|
Returns a hash representing the user information for the user ID passed. If the uid does not exist, NOTHING is returned. See the Password Information Hash for information about the return value. |
This function does not throw any exceptions.
Returns a password information hash representing the user information for the user ID passed. If the user ID does not exist, an exception is raised.
For a similar function that does not throw an exception if the user ID is invalid, see getpwuid().
my hash $hash = getpwuid2(0); # returns the login information for root
Not available with PO_NO_EXTERNAL_INFO
Table 3.368. Arguments and Return Values for getpwuid2()
Argument Type |
Return Type |
Description |
---|---|---|
|
Returns a hash representing the user information for the user ID passed. If the uid does not exist, an exception is thrown. See the Password Information Hash for information about the return value. |
Table 3.369. Exceptions Thrown by getpwuid2()
err | desc |
---|---|
| The user information could not be retrieved (user does not exist or other error in call) |
Returns the path (directory and filename) of the current script. Returns NOTHING if unknown (i.e. no parent script, script read from stdin, etc).
get_script_path() returns any (CONST)
$path = get_script_path();
This function does not throw any exceptions.
Returns the name of the directory from which the current script was executed. Returns NOTHING if the parent script is unknown (i.e. no parent script, script read from stdin, etc).
get_script_dir() returns any (CONST)
$dir = get_script_dir();
This function does not throw any exceptions.
Returns the filename of the current script if known; returns NOTHING if not (i.e. no parent script, script read from stdin, etc).
get_script_name() returns any (CONST)
$name = get_script_name();
This function does not throw any exceptions.
Returns the 32-bit integer value at the 4-byte offset (starting with 0) in the data passed. Of no offset is passed, then the value of the first 32-bit position at offset 0 is returned. Note that the [] operator provides a more efficient way to retrieve a byte from a binary object.
This function assumes MSB byte order when retrieving the value from the data.
Note that this function is identical to get_word_32() except that this version has a RT_NOOP
variant.
See also get_word_32_lsb().
getWord32(data
$data
, softint $offset
= 0) returns any (CONST)
$val = getWord32($bin, 2); # returns the third 32-bit value in MSB format of the binary object
Table 3.373. Arguments and Return Values for getWord32()
Arguments | Return Type | Description |
---|---|---|
The MSB integer value of the data at the 4-byte offset given in the string or binary object. If no offset is passed, then the first 32-bit value is returned. If the object is empty or the offset is larger than the object's size, then no value is returned. |
Returns a list of all the values in the hash argument passed.
hash_values(hash) returns list (CONST)
hash_values() returns nothing (RT_NOOP)
$list = hash_values($hash);
This function does not throw any exceptions.
Returns a string with any HTML escape codes translated to the original characters.
html_decode(string) returns string (CONST)
html_decode() returns nothing (RT_NOOP)
html_decode("<hello>"); # returns "<hello>"
This function does not throw any exceptions.
Returns a string with any characters that can be escaped translated to HTML escape codes.
html_encode(string) returns string (CONST)
html_encode() returns nothing (RT_NOOP)
$str = html_encode("<hello>"); # returns "<hello>"
This function does not throw any exceptions.
Tests if the first argument is a member of the second argument list; types are converted if necessary. If the second argument is NOTHING, then False
is returned unconditionally (i.e. even if the first argument is NOTHING as well), however if the second argument is not a list then the return value of the function is the comparison of the two arguments. For a version of this function that requires types to be equal for the comparison to succeed, see inlist_hard().
inlist(any
$value
, list $list
) returns bool
my $bool = inlist(123, (True
, "123",False
); # this will return True
Table 3.378. Arguments and Return Values for inlist()
Argument Type | Return Type | Description |
---|---|---|
Returns | ||
Always returns | ||
Returns the value of the comparison of the first argument with the second argument; types are converted if necessary. |
This function does not throw any exceptions.
Tests if the first argument is a member of the second argument list; no type conversions are performed (i.e. the comparison fails if types are not equal). If the second argument is NOTHING, then False
is returned unconditionally (i.e. even if the first argument is NOTHING as well), however if the second argument is not a list then the return value of the function is the comparison of the two arguments (types must be equal). For a "soft" version of this function that performs type conversions when doing the comparison, see inlist().
inlist_hard(any
$value
, list $list
) returns bool
inlist_hard(any
$value
, any $other_value
) returns bool
my $bool = inlist_hard(123, (True
, "123",False
); # this will return False
Table 3.379. Arguments and Return Values for inlist_hard()
Argument Type | Return Type | Description |
---|---|---|
Returns | ||
Always returns | ||
Returns the value of the comparison of the first argument with the second argument; no type conversions are performed (the comparison fails if the types are not equal). |
This function does not throw any exceptions.
Loads in a Qore module 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 with the %requires
directive instead, unless all references to the objects provided by the module will be made in code embedded in Program objects.
See also getFeatureList() for a function providing a list of available features.
load_module(string
$path_or_name
) returns nothing
load_module() returns nothing (RT_NOOP)
load_module("pgsql");
Table 3.381. Exceptions Thrown by load_module()
err | desc |
---|---|
| An error occurred loading the module (module not found, libraries not resolved, wrong module API, etc). |
Returns a base64-encoded representation of a binary object or a string (see also makeHexString()).
makeBase64String(data) returns string (CONST)
makeBase64String() returns nothing (RT_NOOP)
$str = makeBase64String($bin);
This function does not throw any exceptions.
Returns a hex-encoded representation of a binary object or a string (see also makeBase64String()).
makeHexString(data) returns string (CONST)
makeHexString() returns nothing (RT_NOOP)
$str = makeHexString($bin);
This function does not throw any exceptions.
Returns the maximum value in a list (see also min()). Without a callback, this function will only work on basic data types. A closure or call reference can be used to find the maximum value of a list of complex data types. The closure or call reference must accept two arguments and must return -1, 0, or 1 if the first is less than, equal to, or greater than the second, respectively.
max(list
$list
) returns any (CONST)
$max = max($complex_list, \callback_function());
$max = max(1, 2, 3, 4);
Table 3.384. Arguments and Return Values for max()
Argument Type | Return Type | Description |
---|---|---|
Finds the maxmimum value in the list and returns that value. The list must be made up of basic data types unless a closure or call reference is used as described above. | ||
... | Finds the maximum value in the list of simple data types passed as top-level arguments to the function and returns that value. No callback reference can be specified with this variant. |
This function does not throw any exceptions (note a closure or call reference could throw an exception).
Returns the minumum value in a list (see also max()). Without a callback, this function will only work on basic data types. A closure or call reference can be used to find the minimum value of a list of complex data types. The closure or call reference must accept two arguments and must return -1, 0, or 1 if the first is less than, equal to, or greater than the second, respectively.
min(list
$list
) returns any (CONST)
$min = min($complex_list, \callback_function());
$min = min(1, 10, 2, 3);
Table 3.385. Arguments and Return Values for min()
Argument Type | Return Type | Description |
---|---|---|
Finds the minimum value in the list and returns that value. The list must be made up of basic data types unless a closure or call reference is used as described above. | ||
... | Finds the minimum value in the list of simple data types passed as top-level arguments to the function and returns that value. No callback reference can be specified with this variant. |
This function does not throw any exceptions (note that a closure or call reference could throw an exception).
Parses a URL string and returns a hash of the components with the following keys (if data in the URL is present): protocol, path, username, password, host, port
. If the URL cannot be parsed, an exception is thrown..
For a similar function that returns NOTHING instead of throwing an exception if the URL string cannot be parsed, see parseURL().
my hash $hash = parse_url($url_string);
Table 3.389. Exceptions Thrown by parse_url()
err | desc |
---|---|
| The URL string given could not be parsed. |
Parses a base64 encoded string and returns the binary object (see also parseHexString()).
parseBase64String(string) returns binary
parseBase64String() returns nothing (RT_NOOP)
$bin = parseBase64String($base64_string);
Table 3.391. Exceptions Thrown by parseBase64String()
err | desc |
---|---|
| A syntax error occurred parsing the base64 string (invalid character, etc). |
Returns a hash of the components of a datasource string.
parseDatasource(string) returns hash
parseDatasource() returns nothing (RT_NOOP)
$hash = parseDatasource($ds_string);
Table 3.392. Arguments and Return Values for parseDatasource()
Argument Type | Return Type | Description |
---|---|---|
Returns a hash of the components of a datasource string. A datasource string has the following structure: |
Table 3.393. Exceptions Thrown by parseDatasource()
err | desc |
---|---|
| A syntax error occurred parsing the datasource string (missing field, unexpected character, etc). |
Table 3.394. parseDatasource() hash
Key | Description |
---|---|
| the name of the driver, if present |
| the username given in the string |
| the password for the connection |
| the database name for the connection |
| The name of the DB-specific character encoding to use for the connection, if present in the string |
| the hostname for the connection, if present in the string |
| the port number to use for the connection, if present in the string |
| A hash of options given in the string, if present. Currently-supported options are |
Parses a hex-encoded string and returns the binary object (see also parseBase64String()).
parseHexString(string) returns binary
parseHexString() returns nothing (RT_NOOP)
$bin = parseHexString($hex_string);
Table 3.396. Exceptions Thrown by parseHexString()
err | desc |
---|---|
| A syntax error occurred parsing the hex string (odd number of digits, invalid character, etc). |
Parses a URL string and returns a hash of the components with the following keys (if data in the URL is present): protocol, path, username, password, host, port
. If the URL cannot be parsed, no value is returned.
For a similar function that throws an exception instead of returning NOTHING if the URL string cannot be parsed, see parse_url().
$hash = parseURL($url_string);
This function does not throw any exceptions.
Removes a signal handler and returns the signal handling state to the default. By the time this function returns, changes to the signal handling thread have already been effected. See Signal Handling for more information.
remove_signal_handler(softint) returns nothing
remove_signal_handler(SIGINT);
Not available with PO_NO_PROCESS_CONTROL
Table 3.399. Arguments and Return Values for remove_signal_handler()
Argument Type | Return Type | Description |
---|---|---|
n/a | The signal number to process. |
This function does not throw any exceptions.
This function does not throw any exceptions.
Sets or replaces a signal handler according to the signal number and closure or call reference (function or object method reference) passed. By the time this function returns, changes to the signal handling thread have already been effected. See Signal Handling for more information.
When a signal is raised and the signal handler code is called, the signal number is passed as an integer argument to the signal handling code.
set_signal_handler(softint
$signal
, code $handler
) returns nothing
set_signal_handler(SIGINT, \signal_handler());
Not available with PO_NO_PROCESS_CONTROL
This function does not throw any exceptions.
Performs an unstable sort in ascending order and returns the new list (for a stable version see sortStable()). Without a callback, this function will only sort basic data types. A closure or call reference can be used to sort complex data types. The closure or call reference must accept two arguments and must return -1, 0, or 1 if the first is less than the second, if the first and second are equal, or if the first is greater than the second, respectively.
sort(list
$list
) returns list (CONST)
sort(list
$list
, code $code
) returns list
$list = sort($complex_list, \callback());
This function does not throw any exceptions.
Performs an unstable sort in descending order and returns the new list (for a stable version see sortDescendingStable()). Without a closure or call reference, this function will only sort basic data types. A closure or call reference can be used to sort complex data types. The closure or call reference must accept two arguments and must return -1, 0, or 1 if the first is less than the second, if the first and second are equal, or if the first is greater than the second, respectively.
sortDescending(list
$list
) returns list (CONST)
sortDescending(list
$list
, code $code
) returns list
sortDescending(list
$list
, string $func_name
) returns list
sortDescending() returns nothing (RT_NOOP)
$list = sortDescending($complex_list, \callback());
This function does not throw any exceptions.
Performs a stable sort in descending order and returns the new list (for an unstable version see sortDescending()). Without a closure or call reference, this function will only sort basic data types. A closure or call reference can be used to sort complex data types. The closure or call reference must accept two arguments and must return -1, 0, or 1 if the first is less than the second, if the first and second are equal, or if the first is greater than the second, respectively.
sortDescendingStable(list
$list
) returns list (CONST)
sortDescendingStable(list
$list
, code $code
) returns list
sortDescendingStable(list
$list
, string $func_name
) returns list
sortDescendingStable() returns nothing (RT_NOOP)
$list = sortDescendingStable($complex_list, \callback());
This function does not throw any exceptions.
Performs a stable sort in ascending order and returns the new list (for an unstable version see sort()). Without a closure or call reference, this function will only sort basic data types. A closure or call reference can be used to sort complex data types. The closure or call reference must accept two arguments and must return -1, 0, or 1 if the first is less than the second, if the first and second are equal, or if the first is greater than the second, respectively.
sortStable(list
$list
) returns list (CONST)
sortStable(list
$list
, code $code
) returns list
sortStable(list
$list
, string $func_name
) returns list
sortStable() returns nothing (RT_NOOP)
$list = sortStable($complex_list, \callback());
This function does not throw any exceptions.
Seeds the random number generator with the integer passed (uses the C library function srandom()
).
This function is tagged with PO_NO_PROCESS_CONTROL
because it affects the process as a whole.
srand(now()); # seeds with current time
Not available with PO_NO_PROCESS_CONTROL
This function does not throw any exceptions.
Table 3.407. Arguments and Return Values for strtoint()
Argument Type |
Return Type |
Description |
---|---|---|
|
Returns an integer corresponding to the string value in the base specified. If no base is passed, then base 10 is assumed. |
This function does not throw any exceptions.
Deletes all keys in the thread-local data hash.
delete_all_thread_data();
Not available with PO_NO_THREAD_CONTROL
Table 3.408. Arguments and Return Values for delete_all_thread_data()
Argument Type | Return Type | Description |
---|---|---|
n/a | n/a | Deletes all keys in the thread-local data hash. |
This function does not throw any exceptions.
Deletes the data associated to one or more keys in the thread-local data hash; if the data is an object, then it is destroyed. See remove_thread_data() for a similar function that does not explicitly destroy objects in the thread-local data hash.
delete_thread_data(list) returns nothing
delete_thread_data(...) returns nothing
delete_thread_data("key1", "key2"); delete_thread_data($list_of_strings);
Not available with PO_NO_THREAD_CONTROL
Table 3.409. Arguments and Return Values for delete_thread_data()
Arguments | Return Values | Description |
---|---|---|
n/a | Deletes the data associated to one or more keys in the thread-local data hash corresponding to the elements of the list converted to a string (if necessary). | |
| n/a | Deletes the data associated to one or more keys in the thread-local data hash corresonding to each string argument in the top-level argument list; arguments are converted to strings if necessary. |
This function does not throw any exceptions, however any objects deleted could throw exceptions in their destructors.
Returns the entire thread-local data hash.
get_all_thread_data() returns hash (CONST)
$hash = get_all_thread_data();
Not available with PO_NO_THREAD_CONTROL
or PO_NO_THREAD_INFO
Table 3.410. Arguments and Return Values for get_all_thread_data()
Argument Type | Return Type | Description |
---|---|---|
n/a | Returns the entire thread-local data hash. |
This function does not throw any exceptions.
Returns a hash of call stacks keyed by each TID (thread ID). The availability of this function depends on an optional debugging feature in the Qore library (maintaining run-time thread call stacks incurrs a performance penalty, therefore this option is normally only available in debugging builds of Qore); the function is only available if the constant HAVE_RUNTIME_THREAD_STACK_TRACE
is True
. See Library Option Constants for a list of all option constants.
getAllThreadCallStacks() returns hash
getAllThreadCallStacks() returns hash
Not available with PO_NO_THREAD_CONTROL
or PO_NO_THREAD_INFO
Table 3.411. Arguments and Return Values for getAllThreadCallStacks()
Argument Type | Return Type | Description |
---|---|---|
n/a | Returns a hash of call stacks keyed by each TID (thread ID). See Call Stack Description for a description of the call stack format. |
Table 3.412. Exceptions Thrown by getAllThreadCallStacks()
err | desc |
---|---|
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Returns the value of the thread-local data attached to the key passed.
get_thread_data(string) returns any (CONST)
get_thread_data() returns nothing (RT_NOOP)
$data = get_thread_data("key1");
Not available with PO_NO_THREAD_CONTROL
or PO_NO_THREAD_INFO
This function does not throw any exceptions.
Returns the Qore thread ID (TID) of the current thread.
$tid = gettid();
Not available with PO_NO_THREAD_INFO
Table 3.414. Arguments and Return Values for gettid()
Argument Type | Return Type | Description |
---|---|---|
n/a | Returns the Qore thread ID (TID) of the current thread. |
This function does not throw any exceptions.
Returns the current number of threads in the process (not including the special signal handling thread).
num_threads() returns int (CONST)
$num = num_threads();
Not available with PO_NO_THREAD_INFO
Table 3.415. Arguments and Return Values for num_threads()
Argument Type | Return Type | Description |
---|---|---|
n/a | Returns the current number of threads in the process. |
This function does not throw any exceptions.
Removes the data associated to one or more keys in the thread-local data hash. For a similar function that also explicitly destroys objects, see delete_thread_data.
remove_thread_data(list) returns nothing
remove_thread_data(...) returns nothing
remove_thread_data("key1", "key2"); remove_thread_data($list_of_strings);
Not available with PO_NO_THREAD_CONTROL
Table 3.416. Arguments and Return Values for remove_thread_data()
Arguments | Return Values | Description |
---|---|---|
n/a | Removes the data associated to one or more keys in the thread-local data hash corresponding to the elements of the list converted to a string (if necessary). | |
| n/a | Removes the data associated to one or more keys in the thread-local data hash corresonding to each string argument in the top-level argument list; arguments are converted to strings if necessary. |
This function does not throw any exceptions.
Saves the data passed against the key passed in thread-local storage.
save_thread_data(hash
$hash
) returns nothing
save_thread_data(string
$key
, any $value
) returns nothing
save_thread_data() returns nothing (RT_NOOP)
save_thread_data("key1", $value);
Not available with PO_NO_THREAD_CONTROL
Table 3.417. Arguments and Return Values for save_thread_data()
Argument Type | Return Type | Description |
---|---|---|
n/a | Saves the data passed against the key passed in thread-local storage. | |
| n/a | Saves the data passed in the hash giving key-value pairs in thread-local storage; the hash argument is added to the therad-local data, replacing any keys already present in the thread-local data. |
This function does not throw any exceptions, however if a value is removed from the thread-local data hash by being overwritten with a new value, and the value is an object that goes out of scope, then such an object could throw an exception in its destructor.
Returns a list of all current thread IDs. Note that the special signal handling thread with TID 0 is never included in this list.
thread_list() returns list (CONST)
$list = thread_list();
Not available with PO_NO_THREAD_INFO
Table 3.418. Arguments and Return Values for thread_list()
Argument Type | Return Type | Description |
---|---|---|
n/a | Returns a list of all current thread IDs |
This function does not throw any exceptions.
Immediately runs all thread resource cleanup routines for the current thread and throws all associated exceptions. This function is particularly useful when used in combination with embedded code in order to catch (and log, for example) thread resource errors (ex: uncommitted transactions, unlocked locks, etc).
throwThreadResourceExceptions() returns nothing
try { throwThreadResourceExceptions(); } catch ($ex) { # ... log or handle exceptions }
Not available with PO_NO_THREAD_CONTROL
Table 3.419. Arguments and Return Values for throwThreadResourceExceptions()
Argument Type | Return Type | Description |
---|---|---|
n/a | n/a | This function returns no value. |
This function can throw any exception thrown by a thread resource handler.
XML functions allow serializing and deserializing between XML strings and qore data structures. There are also functions for XML-RPC support; see below for details and see the XmlRpcClient Class for a class supporting communication with this protocol.
Serializes a hash into an XML string with formatting without an XML header.
makeFormattedXMLFragment(hash
$data
, string $encoding
) returns string
makeFormattedXMLFragment(hash
$data
) returns string
makeFormattedXMLFragment() returns nothing (RT_NOOP)
$xml = makeFormattedXMLFragment($hash);
Table 3.420. Arguments and Return Values for makeFormattedXMLFragment()
Argument Type | Return Type | Description |
---|---|---|
Serializes the Qore hash to an XML string (see XML Integration for more information) without an XML header but with formatting. The hash must have only one top-level key or an exception will be thrown. The optional second argument can give the output string encoding, otherwise UTF-8 is used (not the default encoding for the process). |
Table 3.421. Exceptions Thrown by makeFormattedXMLFragment()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
Serializes the arguments into an XML string in XML-RPC call format with whitespace formatting.
For information about XML-RPC serialization, see XML-RPC Serialization.
makeFormattedXMLRPCCallString(string
$method
, ...) returns string
$xml = makeFormattedXMLRPCCallString("method.name", $arg1, $arg2);
Table 3.422. Arguments and Return Values for makeFormattedXMLRPCCallString()
Argument Type | Return Type | Description |
---|---|---|
| Serializes the arguments into an XML string in XML-RPC call format with whitespace formatting. The encoding of the resulting string will always be the default encoding. |
Table 3.423. Exceptions Thrown by makeFormattedXMLRPCCallString()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
Serializes the arguments into an XML string for an XML-RPC call with whitespace formatting, taking an initial string argument to give the encoding for the created XML.
For information about XML-RPC serialization, see XML-RPC Serialization.
makeFormattedXMLRPCCallStringWithEncoding(string
$encoding
, string $method
, ...) returns string
$xml = makeFormattedXMLRPCCallStringWithEncoding("ISO-8859-1", "method.name", $arg1, $arg2);
Table 3.425. Exceptions Thrown by makeFormattedXMLRPCCallStringWithEncoding()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
Serializes the arguments into an XML string in XML-RPC call format with whitespace formatting, taking a single argument following the XML-RPC method name for the argument list to the method.
For information about XML-RPC serialization, see XML-RPC Serialization.
makeFormattedXMLRPCCallStringArgs(string
$method
, any $args
) returns string
$xml = makeFormattedXMLRPCCallStringArgs("method.name", $arg_list);
Table 3.426. Arguments and Return Values for makeFormattedXMLCallStringArgs()
Argument Type | Return Type | Description |
---|---|---|
Serializes the arguments into an XML string in XML-RPC call format with whitespace formatting, using a single argument following the XML-RPC method name as the argument list for the method. The encoding of the resulting string will always be the default encoding. |
Table 3.427. Exceptions Thrown by makeFormattedXMLRPCCallStringArgs()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
Serializes the arguments into an XML string formatted for an XML-RPC call with whitespace formatting, taking an initial string argument to give the encoding for the created XML, followed by the method name, followed by a single list argument for the argument list.
For information about XML-RPC serialization, see XML-RPC Serialization.
makeFormattedXMLRPCCallStringArgsWithEncoding(string
$encoding
, string $method
, any $args
) returns string
$xml = makeFormattedXMLRPCCallStringArgsWithEncoding("ISO-8859-1", "method.name", $arg_list);
Table 3.428. Arguments and Return Values for makeFormattedXMLRPCCallStringArgsWithEncoding()
Argument Type | Return Type | Description |
---|---|---|
Serializes the arguments into an XML string in XML-RPC call format with whitespace formatting, using a single argument following the XML-RPC method name as the argument list for the method. The encoding of the resulting string will be the encoding given by the first argument. |
Table 3.429. Exceptions Thrown by makeFormattedXMLRPCCallStringArgsWithEncoding()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
Serializes the arguments into an XML string formatted for an XML-RPC fault response with whitespace formatting.
For information about XML-RPC serialization, see XML-RPC Serialization.
makeFormattedXMLRPCFaultResponseString(any
$code
, string $msg
) returns string
$xml = makeFormattedXMLRPCFaultResponseString(10, "oh no, big error");
Table 3.430. Arguments and Return Values for makeFormattedXMLRPCFaultResponseString()
Argument Type | Return Type | Description |
---|---|---|
Serializes the arguments into an XML string formatted for an XML-RPC fault response with whitespace formatting. The first argument is converted to an integer to give the XML-RPC error code. The encoding of the resulting string will always be the default encoding. |
Table 3.431. Exceptions Thrown by makeFormattedXMLRPCCallStringArgs()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
| missing either the error code or the error string arguments. |
Serializes the arguments into an XML string formatted for an XML-RPC fault response with whitespace formatting, taking an initial string argument to give the encoding for the created XML.
For information about XML-RPC serialization, see XML-RPC Serialization.
makeFormattedXMLRPCFaultResponseStringWithEncoding(string
$encoding
, any $code
, string $msg
) returns string
$xml = makeFormattedXMLRPCFaultResponseStringWithEncoding("ISO-8859-2", 10, "oh no, big error");
Table 3.432. Arguments and Return Values for makeFormattedXMLRPCFaultResponseStringWithEncoding()
Argument Type | Return Type | Description |
---|---|---|
Serializes the arguments into an XML string formatted for an XML-RPC fault response with whitespace formatting. The first argument give the XML-RPC fault code. The encoding of the resulting string will be the encoding given by the first argument. |
Table 3.433. Exceptions Thrown by makeFormattedXMLRPCCallStringArgsWithEncoding()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
| missing either the error code or the error string arguments. |
Serializes the arguments into an XML string formatted for an XML-RPC response with whitespace formatting.
For information about XML-RPC serialization, see XML-RPC Serialization.
makeFormattedXMLRPCResponseString(...) returns any
$xml = makeFormattedXMLRPCResponseString($value);
Table 3.434. Arguments and Return Values for makeFormattedXMLRPCResponseString()
Argument Type | Return Type | Description |
---|---|---|
| Serializes the arguments into an XML string formatted for an XML-RPC response with whitespace formatting>. The encoding of the resulting string will always be the default encoding. |
Table 3.435. Exceptions Thrown by makeFormattedXMLRPCResponseString()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
Serializes the arguments into an XML string formatted for an XML-RPC response with whitespace formatting, taking an initial string argument to give the encoding for the created XML.
For information about XML-RPC serialization, see XML-RPC Serialization.
makeFormattedXMLRPCResponseStringWithEncoding(string
$encoding
, ...) returns any
$xml = makeFormattedXMLRPCResponseStringWithEncoding("ISO-8859-1", $value);
Table 3.437. Exceptions Thrown by makeFormattedXMLRPCResponseStringWithEncoding()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
Serializes the arguments into an XML string in XML-RPC value format with whitespace formatting.
For information about XML-RPC serialization, see XML-RPC Serialization.
makeFormattedXMLRPCValueString(any
$data
, string $encoding
) returns string
makeFormattedXMLRPCValueString(any
$data
) returns string
$xml = makeFormattedXMLRPCValueString($value);
Table 3.438. Arguments and Return Values for makeFormattedXMLRPCValueString()
Argument Type | Return Type | Description |
---|---|---|
Serializes the arguments into an XML string in XML-RPC value format with whitespace formatting. The optional second argument may be given to set the output string encoding, otherwise the encoding of the resulting string will be the default encoding. |
Table 3.439. Exceptions Thrown by makeFormattedXMLRPCValueString()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
Serializes a hash into an XML string with formatting and an XML header.
makeFormattedXMLString(hash
$data
) returns string
makeFormattedXMLString(hash
$data
, string $encoding
) returns string
makeFormattedXMLString(string
$top_element
, hash $data
) returns string
makeFormattedXMLString(string, hash
$data
, string) returns string $encoding
$xml = makeFormattedXMLString($hash);
$xml = makeFormattedXMLString("key", $hash);
Table 3.440. Arguments and Return Values for makeFormattedXMLString()
Argument Type | Return Type | Description |
---|---|---|
Serializes the Qore hash to an XML string (see XML Integration for more information) with an XML header and formatting. The hash must have only one top-level key or an exception will be thrown. The optional second argument may be given to specify the output string encoding, otherwise UTF-8 will be used. | ||
Serializes the Qore hash to an XML string (see XML Integration for more information) with an XML header and formatting. The first parameter will be the top-level XML element. The optional third argument may be given to specify the output string encoding, otherwise UTF-8 will be used. |
Table 3.441. Exceptions Thrown by makeFormattedXMLString()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
| Incorrect arguments passed. |
Serializes a hash into an XML string without whitespace formatting and without an XML header.
makeXMLFragment(hash
$data
, string $encoding
) returns string
makeXMLFragment(hash
$data
) returns string
makeXMLFragment() returns nothing (RT_NOOP)
$xml = makeXMLFragment($hash);
Table 3.442. Arguments and Return Values for makeXMLFragment()
Argument Type | Return Type | Description |
---|---|---|
Serializes the Qore hash to an XML string (see XML Integration for more information) without an XML header and without whitespace formatting. The hash must have only one top-level key or an exception will be thrown. The optional second argument can give the output string encoding, otherwise the default encoding is used. |
Table 3.443. Exceptions Thrown by makeXMLFragment()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
Serializes the arguments into an XML string in XML-RPC call format without whitespace formatting.
For information about XML-RPC serialization, see XML-RPC Serialization.
makeXMLRPCCallString(string
$method
, ...) returns string
$xml = makeXMLRPCCallString("method.name", $arg1, $arg2);
Table 3.444. Arguments and Return Values for makeXMLRPCCallString()
Argument Type | Return Type | Description |
---|---|---|
| Serializes the arguments into an XML string in XML-RPC call format without whitespace formatting. The encoding of the resulting string will always be the default encoding. |
Table 3.445. Exceptions Thrown by makeXMLRPCCallString()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
Serializes the arguments into an XML string in XML-RPC call format without whitespace formatting, taking an initial string argument to give the target character encoding for the XML string.
For information about XML-RPC serialization, see XML-RPC Serialization.
makeXMLRPCCallStringWithEncoding(string
$encoding
, string $method
, ...) returns string
$xml = makeXMLRPCCallStringWithEncoding("ISO-8859-2", "method.name", $arg1, $arg2);
Table 3.447. Exceptions Thrown by makeXMLRPCCallStringWithEncoding()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
Serializes the arguments into an XML string in XML-RPC call format without whitespace formatting, taking a single argument following the XML-RPC method name for the argument list to the method.
For information about XML-RPC serialization, see XML-RPC Serialization.
makeXMLRPCCallStringArgs(string
$method
, any $args
) returns string
$xml = makeXMLRPCCallStringArgs("method.name", $arg_list);
Table 3.448. Arguments and Return Values for makeXMLCallStringArgs()
Argument Type | Return Type | Description |
---|---|---|
Serializes the arguments into an XML string in XML-RPC call format without whitespace formatting, using a single argument following the XML-RPC method name as the argument list for the method. The encoding of the resulting string will always be the default encoding. |
Table 3.449. Exceptions Thrown by makeXMLRPCCallStringArgs()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
Serializes the arguments into an XML string formatted for an XML-RPC call without whitespace formatting, taking an initial string argument to give the target character encoding for the XML string followed by a list argument for the argument list.
For information about XML-RPC serialization, see XML-RPC Serialization.
makeXMLRPCCallStringArgsWithEncoding(string
$encoding
, string $method
, any $args
) returns string
$xml = makeXMLRPCCallStringArgsWithEncoding("ISO-8859-2", "method.name", $arg_list);
Table 3.450. Arguments and Return Values for makeXMLCallStringArgsWithEncoding()
Argument Type | Return Type | Description |
---|---|---|
Serializes the arguments into an XML string in XML-RPC call format without whitespace formatting, using a single argument following the XML-RPC method name as the argument list for the method. The encoding of the resulting string will correspond to the encoding given as the first argument to the function. |
Table 3.451. Exceptions Thrown by makeXMLRPCCallStringArgsWithEncoding()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
Serializes the arguments into an XML string formatted for an XML-RPC fault response without whitespace formatting.
For information about XML-RPC serialization, see XML-RPC Serialization.
makeXMLRPCFaultResponseString(any
$code
, string $msg
) returns string
$xml = makeXMLRPCFaultResponseString(10, "oh no, an error occured");
Table 3.453. Exceptions Thrown by makeXMLRPCFaultResponseString()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
| missing either the error code or the error string arguments. |
Serializes the arguments into an XML string formatted for an XML-RPC fault response without whitespace formatting, taking an initial string argument to give the target character encoding for the XML string.
For information about XML-RPC serialization, see XML-RPC Serialization.
makeXMLRPCFaultResponseStringWithEncoding(string
$encoding
, any $code
, string $msg
) returns string
$xml = makeXMLRPCFaultResponseStringWithEncoding("ISO-8859-2", 10, "oh no, an error occured");
Table 3.455. Exceptions Thrown by makeXMLRPCFaultResponseStringWithEncoding()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
| missing either the error code or the error string arguments. |
Serializes the arguments into an XML string formatted for an XML-RPC response without whitespace formatting.
For information about XML-RPC serialization, see XML-RPC Serialization.
makeXMLRPCResponseString(...) returns any
$xml = makeXMLRPCResponseString($response);
Table 3.456. Arguments and Return Values for makeXMLRPCResponseString()
Argument Type | Return Type | Description |
---|---|---|
| Serializes the arguments into an XML string formatted for an XML-RPC response without whitespace formatting>. The encoding of the resulting string will always be the default encoding. |
Table 3.457. Exceptions Thrown by makeXMLRPCResponseString()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
Serializes the arguments into an XML string formatted for an XML-RPC response without whitespace formatting.
For information about XML-RPC serialization, see XML-RPC Serialization.
makeXMLRPCResponseStringWithEncoding(string
$encoding
, ...) returns any
$xml = makeXMLRPCResponseStringWithEncoding("ISO-8859-2", $response);
Table 3.459. Exceptions Thrown by makeXMLRPCResponseStringWithEncoding()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
Serializes the arguments into an XML string in XML-RPC value format without whitespace formatting.
For information about XML-RPC serialization, see XML-RPC Serialization.
makeXMLRPCValueString(any,
$data
string $encoding
) returns string
makeXMLRPCValueString(any
$data
) returns string
$xml = makeXMLRPCValueString($value);
Table 3.460. Arguments and Return Values for makeXMLRPCValueString()
Argument Type | Return Type | Description |
---|---|---|
Serializes the arguments into an XML string in XML-RPC value format without whitespace formatting. The encoding of the resulting string will always be the default encoding. |
Table 3.461. Exceptions Thrown by makeXMLRPCValueString()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
Serializes a hash into an XML string without whitespace formatting but with an XML header.
makeXMLString(hash
$data
) returns string
makeXMLString(hash
$data
, string $encoding
) returns string
makeXMLString(string
$top_element
, hash $data
) returns string
makeXMLString(string, hash
$data
, string) returns string $encoding
$xml = makeXMLString($hash);
$xml = makeXMLString("key", $hash);
Table 3.462. Arguments and Return Values for makeXMLString()
Argument Type | Return Type | Description |
---|---|---|
Serializes the Qore hash to an XML string (see XML Integration for more information) with an XML header but without whitespace formatting. The hash must have only one top-level key or an exception will be thrown. The optional second argument may be given to specify the output string encoding, otherwise UTF-8 will be used. | ||
Serializes the Qore hash to an XML string (see XML Integration for more information) with an XML header but without whitespace formatting. The first parameter will be the top-level XML element. The optional third argument may be given to specify the output string encoding, otherwise UTF-8 will be used. |
Table 3.463. Exceptions Thrown by makeXMLString()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
| Incorrect arguments passed. |
Parses an XML string and returns a Qore hash structure. If duplicate, out-of-order XML elements are found in the input string, they are deserialized to Qore hash elements with the same name as the XML element but including a caret "^" and a numeric prefix to maintain the same key order in the Qore hash as in the input XML string.
This function should only be used when it is important to maintain the XML element order in the resulting Qore data structure (for example, when the data must be re-serialized to an XML string and the element order within a subelement must be maintained), for example, when parsing and reserializing an OSX property list in XML format. Otherwise parseXMLAsData() should be used instead.
parseXML(string
$xml_string
) returns hash
$hash = parseXML($xml);
Table 3.464. Arguments and Return Values for parseXML()
Argument Type | Return Type | Description |
---|---|---|
Parses an XML string and returns a Qore hash structure. If no second argument is given, specifying the output string encoding, all strings will have the default encoding. |
Parses an XML string as data (does not preserve hash order with out-of-order duplicate keys: collapses all to the same list) and returns a Qore hash structure.
Note that data deserialized with this function may not be reserialized to an identical XML string to the input due to the fact that duplicate, out-of-order XML elements are collapsed into lists in the resulting Qore hash, thereby losing the order in the original XML string.
For a similar function preserving the order of keys in the XML in the resulting Qore hash by generating Qore hash element names with numeric suffixes, see parseXML().
parseXMLAsData(string
$xml_string
) returns hash
parseXMLAsData(string
$xml_string
, string $encoding
) returns hash
parseXMLAsData() returns nothing (RT_NOOP)
$hash = parseXMLAsData($xml);
Table 3.466. Arguments and Return Values for parseXMLAsData()
Argument Type | Return Type | Description |
---|---|---|
Parses an XML string and returns a Qore hash structure. If no second argument is given, specifying the output string encoding, all strings will have the default encoding. |
Table 3.467. Exceptions Thrown by parseXMLAsData()
err | desc |
---|---|
| Error parsing the XML string. |
Parses an XML string as data (does not preserve hash order with out-of-order duplicate keys: collapses all to the same list), validates the XML string against a RelaxNG schema string, and returns a Qore hash structure. If any errors occur parsing the RelaxNG schema string, parsing the XML string, or validating the XML against the XSD, exceptions are thrown. If no encoding string argument is passed, then all strings in the resulting hash will be in UTF-8 encoding regardless of the input encoding of the XML string.
Please note that data deserialized with this function may not be reserialized to an identical XML string to the input due to the fact that duplicate, out-of-order XML elements are collapsed into lists in the resulting Qore hash, thereby losing the order in the original XML string.
For a similar function preserving the order of keys in the XML in the resulting Qore hash by generating Qore hash element names with numeric suffixes, see parseXMLWithRelaxNG(). See also parseXMLAsDataWithSchema() and parseXMLWithSchema().
The availability of this function depends on the presence of libxml2's xmlTextReaderRelaxNGSetSchema() function when Qore was compiled; for maximum portability check the constant HAVE_PARSEXMLWITHRELAXNG
before running this function. See Library Option Constants for a list of all option constants.
parseXMLAsDataWithRelaxNG(string
$xml_string
, string $relaxng_string
) returns hash
parseXMLAsDataWithRelaxNG(string
$xml_string
, string $relaxng_string
, string $encoding
) returns hash
$hash = parseXMLAsDataWithRelaxNG($xml, $rng);
Table 3.468. Arguments and Return Values for parseXMLAsDataWithRelaxNG()
Argument Type | Return Type | Description |
---|---|---|
| Parses an XML string (1st argument), validates against the RelaxNG string (2nd argument), and returns a Qore hash structure. If no third argument is given, specifying the output string encoding, all strings will have the default encoding. |
Table 3.469. Exceptions Thrown by parseXMLAsDataWithRelaxNG()
err | desc |
---|---|
| Error parsing the XML string. |
| Invalid arguments passed to the function. |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Parses an XML string as data (does not preserve hash order with out-of-order duplicate keys: collapses all to the same list), validates the XML string against an XSD schema string, and returns a Qore hash structure. If any errors occur parsing the XSD string, parsing the XML string, or validating the XML against the XSD, exceptions are thrown. If no encoding string argument is passed, then all strings in the resulting hash will be in UTF-8 encoding regardless of the input encoding of the XML string.
Please note that data deserialized with this function may not be reserialized to an identical XML string to the input due to the fact that duplicate, out-of-order XML elements are collapsed into lists in the resulting Qore hash, thereby losing the order in the original XML string.
For a similar function preserving the order of keys in the XML in the resulting Qore hash by generating Qore hash element names with numeric suffixes, see parseXMLWithSchema(). See also parseXMLAsDataWithRelaxNG() and parseXMLWithRelaxNG().
The availability of this function depends on the presence of libxml2's xmlTextReaderSetSchema() function when Qore was compiled; for maximum portability check the constant HAVE_PARSEXMLWITHSCHEMA
before running this function. See Library Option Constants for a list of all option constants.
parseXMLAsDataWithSchema(string
$xml_string
, string $xsd
) returns hash
parseXMLAsDataWithSchema(string
$xml_string
, string $xsd
, string $encoding
) returns hash
$hash = parseXMLAsDataWithSchema($xml, $xsd);
Table 3.470. Arguments and Return Values for parseXMLAsDataWithSchema()
Argument Type | Return Type | Description |
---|---|---|
Parses an XML string (1st argument), validates against the XSD string (2nd argument), and returns a Qore hash structure. If no third argument is given, specifying the output string encoding, all strings will have the default encoding. |
Table 3.471. Exceptions Thrown by parseXMLAsDataWithSchema()
err | desc |
---|---|
| Error parsing the XML string. |
| Invalid arguments passed to the function. |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Deserializies an XML-RPC call string, returning a Qore data structure representing the call information.
parseXMLRPCCall(string
$xml_string
) returns hash
parseXMLRPCCall(string
$xml_string
, string $encoding
) returns hash
parseXMLRPCCall() returns nothing (RT_NOOP)
$hash = parseXMLRPCCall($xml);
Table 3.472. Arguments and Return Values for parseXMLRPCCall()
Argument Type | Return Type | Description |
---|---|---|
Deserializies an XML-RPC call string, returning a Qore data structure representing the call information. The hash will have the following keys: |
Table 3.473. Exceptions Thrown by parseXMLRPCCall()
err | desc |
---|---|
| Error parsing the XML-RPC call string. |
| Error parsing an XML-RPC value node. |
Deserializies an XML-RPC response string, returning a Qore data structure representing the response information.
parseXMLRPCResponse(string
$xml_string
) returns hash
parseXMLRPCResponse(string
$xml_string
, string $encoding
) returns hash
parseXMLRPCResponse() returns nothing (RT_NOOP)
$hash = parseXMLRPCResponse($xml);
Table 3.474. Arguments and Return Values for parseXMLRPCResponse()
Argument Type | Return Type | Description |
---|---|---|
Deserializies an XML-RPC response string, returning a Qore data structure representing the response information. The hash will have either a "fault" or a "params" key, depending on if it's a fault response or a non-fault response. If no second argument is given, specifying the output string encoding, all strings will have the default encoding. |
Table 3.475. Exceptions Thrown by parseXMLRPCResponse()
err | desc |
---|---|
| Error parsing the XML-RPC response string. |
| Error parsing an XML-RPC value node. |
Deserializies an XML-RPC value tree, returning a Qore data structure representing the information.
parseXMLRPCValue(string
$xml_string
) returns hash
parseXMLRPCValue(string
$xml_string
, string $encoding
) returns hash
parseXMLRPCValue() returns nothing (RT_NOOP)
my any $data = parseXMLRPCValue($xml);
Table 3.476. Arguments and Return Values for parseXMLRPCValue()
Argument Type | Return Type | Description |
---|---|---|
Deserializies an XML-RPC value string, returning Qore data representing the value data. If no second argument is given, specifying the output string encoding, all strings will have the default encoding. |
Table 3.477. Exceptions Thrown by parseXMLRPCValue()
err | desc |
---|---|
| Error parsing an XML-RPC value node. |
Parses an XML string, validates the XML string against a RelaxNG schema string, and returns a Qore hash structure. If any errors occur parsing the RelaxNG string, parsing the XML string, or validating the XML against the RelaxNG schema, exceptions are thrown. If no encoding string argument is passed, then all strings in the resulting hash will be in UTF-8 encoding regardless of the input encoding of the XML string.
If duplicate, out-of-order XML elements are found in the input string, they are deserialized to Qore hash elements with the same name as the XML element but including a caret "^" and a numeric prefix to maintain the same key order in the Qore hash as in the input XML string.
This function should only be used when it is important to maintain the XML element order in the resulting Qore data structure (for example, when the data must be re-serialized to an XML string and the element order within a subelement must be maintained), for example, when parsing and reserializing an OSX property list in XML format. Otherwise parseXMLAsDataWithRelaxNG() should be used instead.
See also parseXMLWithSchema() and parseXMLAsDataWithSchema().
The availability of this function depends on the presence of libxml2's xmlTextReaderRelaxNGSetSchema() function when Qore was compiled; for maximum portability check the constant HAVE_PARSEXMLWITHRELAXNG
before running this function. See Library Option Constants for a list of all option constants.
parseXMLWithRelaxNG(string
$xml_string
, string $relaxng_string
) returns hash
parseXMLWithRelaxNG(string
$xml_string
, string $relaxng_string
, string $encoding
) returns hash
$hash = parseXMLWithRelaxNG($xml, $rng);
Table 3.478. Arguments and Return Values for parseXMLWithRelaxNG()
Argument Type | Return Type | Description |
---|---|---|
| Parses an XML string (1st argument), validates against the RelaxNG schema string (2nd argument), and returns a Qore hash structure. If no third argument is given, specifying the output string encoding, all strings will have the default encoding. |
Table 3.479. Exceptions Thrown by parseXMLWithRelaxNG()
err | desc |
---|---|
| Error parsing the XML string. |
| Invalid arguments passed to the function. |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Parses an XML string, validates the XML string against an XSD schema string, and returns a Qore hash structure. If any errors occur parsing the XSD string, parsing the XML string, or validating the XML against the XSD, exceptions are thrown. If no encoding string argument is passed, then all strings in the resulting hash will be in UTF-8 encoding regardless of the input encoding of the XML string.
If duplicate, out-of-order XML elements are found in the input string, they are deserialized to Qore hash elements with the same name as the XML element but including a caret "^" and a numeric prefix to maintain the same key order in the Qore hash as in the input XML string.
This function should only be used when it is important to maintain the XML element order in the resulting Qore data structure (for example, when the data must be re-serialized to an XML string and the element order within a subelement must be maintained), for example, when parsing and reserializing an OSX property list in XML format. Otherwise parseXMLAsDataWithSchema() should be used instead.
See also parseXMLWithRelaxNG() and parseXMLAsDataWithRelaxNG().
The availability of this function depends on the presence of libxml2's xmlTextReaderSetSchema() function when Qore was compiled; for maximum portability check the constant HAVE_PARSEXMLWITHSCHEMA
before running this function. See Library Option Constants for a list of all option constants.
parseXMLWithSchema(string
$xml_string
, string $xsd
) returns hash
parseXMLWithSchema(string
$xml_string
, string $xsd
, string $encoding
) returns hash
$hash = parseXMLWithSchema($xml, $xsd);
Table 3.480. Arguments and Return Values for parseXMLWithSchema()
Argument Type | Return Type | Description |
---|---|---|
Parses an XML string (1st argument), validates against the XSD string (2nd argument), and returns a Qore hash structure. If no third argument is given, specifying the output string encoding, all strings will have the default encoding. |
Table 3.481. Exceptions Thrown by parseXMLWithSchema()
err | desc |
---|---|
| Error parsing the XML string. |
| Invalid arguments passed to the function. |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
JSON (JavaScript Object Notation) functions allow serializing and deserializing between JSON strings and qore data structures. There are also functions for JSONRPC support for easier integration with JavaScript clients; see below for details.
Creates a JSON-RPC 1.1 error response string from the parameters passed, formatted with line breaks for easier readability. To follow JSON-RPC specifications, the generated string will always be in UTF-8 encoding. The first code argument must be an integer between 100 and 999 (inclusive). The last argument can be of any Qore type (or complex data structure).
makeFormattedJSONRPC11ErrorString(softint
$code
, string $error
, any $id
, any $error_response
) returns string
$json = makeFormattedJSONRPC11ErrorString(200, $msg, $id, $error);
Table 3.483. Exceptions Thrown by makeFormattedJSONRPC11ErrorString()
err | desc |
---|---|
| Error serializing to JSON string. |
| Invalid argument to method. |
Creates a generic JSON-RPC error response string from the parameters passed, formatted with line breaks for easier readability. To follow JSON-RPC specifications, the generated string will always be in UTF-8 encoding. The last argument can be of any qore type (or complex data structure).
makeFormattedJSONRPCErrorString(any
$json_version
, any $id
, any $response_msg
) returns string
$json = makeFormattedJSONRPCErrorString("1.1", $id, $response);
Table 3.485. Exceptions Thrown by makeFormattedJSONRPCErrorString()
err | desc |
---|---|
| Error serializing to JSON string. |
Creates a JSON-RPC request string from the parameters passed, formatted with line breaks for easier readability. To follow JSON-RPC specifications, the generated string will always be in UTF-8 encoding. The last argument can be of any qore type (or complex data structure).
makeFormattedJSONRPCRequestString(string
$method_name
, any $json_version
, any $id
, any $request_msg
) returns string
$json = makeFormattedJSONRPCRequestString("method_name", "1.1", $id, $request_data);
Table 3.487. Exceptions Thrown by makeFormattedJSONRPCRequestString()
err | desc |
---|---|
| Error serializing to JSON string. |
| missing method name as first parameter. |
Creates a JSON-RPC response string from the parameters passed, formatted with line breaks for easier readability. To follow JSON-RPC specifications, the generated string will always be in UTF-8 encoding. The last argument can be of any qore type (or complex data structure).
makeFormattedJSONRPCResponseString(any
$json_version
, any $id
, any $response_msg
) returns string
$json = makeFormattedJSONRPCResponseString("1.1", $id, $response);
Table 3.489. Exceptions Thrown by makeFormattedJSONRPCResponseString()
err | desc |
---|---|
| Error serializing to JSON string. |
Serializes qore data into a JSON string, formatted with line breaks for easier readability. By default the string produced will be in UTF-8 encoding, but this can be overridden by the second argument.
makeFormattedJSONString(any
$data
, string $encoding
) returns string
makeFormattedJSONString(any
$data
) returns string
$json = makeFormattedJSONString($value);
Table 3.491. Exceptions Thrown by makeFormattedJSONString()
err | desc |
---|---|
| Error serializing to JSON string. |
Creates a JSON-RPC 1.1 error response string from the parameters passed, without any line breaks. To follow JSON-RPC specifications, the generated string will always be in UTF-8 encoding. The last argument can be of any qore type (or complex data structure).
makeJSONRPC11ErrorString(softint
$code
, string $error
, any $id
, any $error_response
) returns string
$json = makeJSONRPC11ErrorString(200, $msg, $id, $error);
Table 3.493. Exceptions Thrown by makeJSONRPC11ErrorString()
err | desc |
---|---|
| Error serializing to JSON string. |
| Invalid argument to method. |
Creates a generic JSON-RPC error response string from the parameters passed, without any line breaks. To follow JSON-RPC specifications, the generated string will always be in UTF-8 encoding. The last argument can be of any qore type (or complex data structure).
makeJSONRPCErrorString(any
$json_version
, any $id
, any $response_msg
) returns string
$json = makeJSONRPCErrorString("1.1", $id, $response);
Table 3.495. Exceptions Thrown by makeJSONRPCErrorString()
err | desc |
---|---|
| Error serializing to JSON string. |
Creates a JSON-RPC request string from the parameters passed, without any line breaks. To follow JSON-RPC specifications, the generated string will always be in UTF-8 encoding. The last argument can be of any qore type (or complex data structure).
makeJSONRPCRequestString(string
$method_name
, any $json_version
, any $id
, any $request_msg
) returns string
$json = makeJSONRPCRequestString("method_name", "1.1", $id, $request_data);
Table 3.497. Exceptions Thrown by makeJSONRPCRequestString()
err | desc |
---|---|
| Error serializing to JSON string. |
| missing method name as first parameter. |
Creates a JSON-RPC response string from the parameters passed, without any line breaks. To follow JSON-RPC specifications, the generated string will always be in UTF-8 encoding. The last argument can be of any qore type (or complex data structure).
makeJSONRPCResponseString(any
$json_version
, any $id
, any $response_msg
) returns string
$json = makeJSONRPCResponseString("1.1", $id, $response);
Table 3.499. Exceptions Thrown by makeJSONRPCResponseString()
err | desc |
---|---|
| Error serializing to JSON string. |
Serializes qore data into a JSON string, without any line breaks. By default the string produced will be in UTF-8 encoding, but this can be overridden by the second argument.
makeJSONString(any
$data
, string $encoding
) returns string
makeJSONString(any
$data
) returns string
$json = makeJSONString($value);
Table 3.501. Exceptions Thrown by makeJSONString()
err | desc |
---|---|
| Error serializing to JSON string. |
This is the standard "printf" format string.
There are three types of objects in the format string:
Plain characters, which are copied as-is to the output string
Escape characters, which are converted and copied to the output string
Format specifications for arguments to be included in the output string, which are preceded by the percent sign "%" as follows:
After the "%" sign, there can be zero or more flags as follows:
Table 3.504. Printf Formatting Flags
Flag | Description |
---|---|
- | left-justify the field |
+ | include the sign for the number (+ or -) |
0 | use zero left padding rather than space padding |
<space> | use space padding |
Then a field width specifier can be given as a string of digits specifying the length of the field. With "field" functions (function names preceded by "f_"), these width specifiers are hard limits; that is; arguments longer than the width specified are limited to the specified width.
For floating-point arguments, a precision specifier may be given by including a period "." and another digit string, which indicates the number of digits to appear after the decimal point.
Then the format character is given as follows:
Table 3.505. Printf Formatting Characters
Character | Description |
---|---|
s | string |
d | Integer, output in base 10 format |
f | Floating point value |
n | Any Qore value, formatted as a string, without any line breaks |
N | Any Qore value, formatted as a string, with line breaks and whitespace formatting for complex objects |
x | Integer, output in base 16 (hexadecimal) format with lower-case a-f |
X | Integer, output in base 16 (hexadecimal) format with upper-case A-F |
Table 3.506. String Escape Characters
Character | Description |
---|---|
\n | a newline character |
\r | a carriage-return character |
\t | a tab character |
\b | a backspace character |
\f | a form-feed character |
\num | an 8-bit character whose value is the 1, 2, or 3 digit octal number |
\" | a double-quote character |
Table 4.1. Qore Class List
Name | Description |
---|---|
For reading and writing files. | |
For handling of directories, listing files, and creating/removing subdirectories. | |
For communicating with FTP servers. | |
For processing command-line options. | |
For parsing and executing application-embedded or user-supplied logic. | |
For communication with IPv4 sockets with and without TSL/SSL encryption. | |
Used when getting or setting terminal settings. | |
For communication with HTTP servers with and without TSL/SSL encryption. | |
For communication using the XML-RPC protocol with and without TSL/SSL encryption. | |
For communication using the JSON-RPC protocol with and without TSL/SSL encryption. | |
For working with X.509 certificates. | |
For working with private key data. | |
For working with databases; provides the user interface to qore DBI drivers. | |
Provides transparent per-thread, per-transaction Datasource connection pooling. | |
The abstract base class for locks that support the internal API for use with the Condition class. | |
A helper class for the Gate class for exception-safe Gate handling. | |
A helper class for the Mutex class for exception-safe Mutex handling. | |
A helper class for the RWLock class for exception-safe read lock handling. | |
A helper class for the RWLock class for exception-safe write lock handling. | |
For blocking a thread until a condition becomes true. | |
For blocking a thread until a counter becomes zero. | |
A reentrant thread lock. | |
A simple thread lock. | |
A blocking, thread-safe queue class, useful for message passing (can also be used as a stack). | |
DEPRECATED: A reentrant thread lock; use Gate instead. | |
A read-write thread lock. | |
A thread-safe integral counter. | |
For analyzing and manipulating XML documents. | |
Gives information about XML data in an XML document. | |
For parsing or iterating through the elements of an XML document. |
The following constants are defined in the Qore namespace.
Table 4.2. Build and Version Constants
Key | Type | Description |
---|---|---|
| The operating system used to build the Qore library. | |
| The CPU used as a target for the Qore library build. | |
| The full version string for this version of the Qore library. | |
| An integer giving the Qore library's major version number. | |
| An integer giving the Qore library's minor version number. | |
| An integer giving the Qore library's release version number. | |
| An integer giving the Qore library's subversion revision number. | |
| A string giving information about the host used to compile the Qore library. | |
| The compiler used to build the Qore library. | |
| The compiler flags used to compile the Qore library. | |
| The linker flags used to link the Qore library. |
Table 4.3. Machine Constants
Key | Type | Description |
---|---|---|
| If |
Table 4.4. Library Options
Name | Type | Description |
---|---|---|
| Indicates if the Qore library supports fast atomic reference counting. Note that if this constant is | |
| Indicates if protection against stack overruns is provided | |
| Indicates if active thread stack tracing has been enabled as a debugging option and if the getAllThreadCallStacks() function is available. | |
| Indicates if the round() function is available. | |
| Always | |
| Indicates if the seteuid() function is available. | |
| Indicates if the setegid() function is available. | |
| Indicates if parseXMLWithRelaxNG() and XmlReader::relaxNGValidate() are available. | |
| Indicates if parseXMLWithSchema() and XmlReader::schemaValidate() are available. | |
| Indicates if the openssl library used to build the qore library supported the SHA224 algorithm and therefore if the SHA224() and SHA224_bin() functions are available. | |
| Indicates if the openssl library used to build the qore library supported the SHA256 algorithm and therefore if the SHA256() and SHA256_bin() functions are available. | |
| Indicates if the openssl library used to build the qore library supported the SHA384 algorithm and therefore if the SHA384() and SHA384_bin() functions are available. | |
| Indicates if the openssl library used to build the qore library supported the SHA512 algorithm and therefore if the SHA512() and SHA512_bin() functions are available. | |
| Indicates if the openssl library used to build the qore library supported the MDC2 algorithm and therefore if the MDC2() and MDC2_bin() functions are available. | |
| Indicates if the openssl library used to build the qore library supported the RC5 encryption algorithm and therefore if the rc5_encrypt_cbc(), rc5_decrypt_cbc() and rc5_encrypt_cbc_to_string() functions are available. | |
| Indicates if the openssl library used to build the qore library supported the MD2 algorithm and therefore if the MD2() and MD2_bin() functions are available. |
Table 4.7. Warning Constants
Name | Type | Description |
---|---|---|
| No warnings are enabled with this constant | |
| This warning means that the embedded code tried to change the warning mask, but it was locked, so the warning mask was actually unchanged | |
| Indicates that a local variable was redeclared with the same name in the same local scope | |
| Indicates that the embedded code tried to enable or disable an unknown warning | |
| Indicates that the embedded code referenced an undeclared variable that will be assumed to be a global variable | |
| Indicates that the embedded code has declared the same global variable more than once | |
| Indicates that code cannot be reached (for example; code in the same local block after an unconditional return or thread_exit statement) | |
| Indicates that the embedded code is calling an unknown method in a class; this may be vaild if the calling method is only called from a base class that actually implements the method | |
| Indicates that the embedded code performs some operation that is guaranteed to produce no result (for example, using the [] operator on an integer value) | |
| Enables all warnings |
Table 4.8. Event Constants
Name | Value | Description |
---|---|---|
| Raised when a network packet is received. | |
| Raised when a network packet is sent. | |
| Raised when the HTTP "Content-Length" header is received. | |
| Raised when HTTP chunked data is about to be received. | |
| Raised when all HTTP chunked data has been received. | |
| Raised when an HTTP redirect message is received. | |
| Raised when a socket is closed. | |
| Raised when the object being monitored is deleted. | |
| Raised immediately before an FTP control message is sent. | |
| Raised when an FTP reply is received on the control channel. | |
| Raised when a hostname lookup is attempted. | |
| Raised when a hostname lookup is resolved. | |
| Raised when an HTTP message is sent. | |
| Raised when an HTTP message is received. | |
| Raised when HTTP footers are received. | |
| Raised when a block of HTTP chunked data is received. | |
| Raised when the next chunk size for HTTP chunked data is known. | |
| Raised right before a socket connection attempt is made. | |
| Raised when the socket connection has been established. | |
| Raised when socket SSL negotiation starts. | |
| Raised when SSL communication has been negotiated and established. | |
| Raised right before a file is opened. | |
| Raised when a file has been successfully opened. | |
| Raised when data has been read from a file. | |
| Raised when data has been written to a file. | |
This constant is a hash that maps event numbers to string descriptions as described in this table. |
Table 4.9. Event Map Hash Constant
Key | String Value |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Table 4.12. Terminal Attributes Local Mode Constants
Name | Description |
---|---|
| visual erase for line kill |
| visually erase chars |
| enable echoing |
| echo NL even if ECHO is off |
| visual erase mode for hardcopy |
| enable signals INTR, QUIT, [D]SUSP |
| canonicalize input lines |
| enable DISCARD and LNEXT |
| stop background jobs from output |
| output being flushed (state) |
| retype pending input (state) |
| don't flush after interrupt |
| use alternate WERASE algorithm (this constant is only available on some systems; do not use in portable programs) |
| external processing (this constant is only available on some systems; do not use in portable programs) |
| no kernel output from VSTATUS (this constant is only available on some systems; do not use in portable programs) |
Table 4.13. Terminal Attributes Control Mode Constants
Name | Description |
---|---|
| character size mask |
| 5 bits (pseudo) |
| 6 bits |
| 7 bits |
| 8 bits |
| send 2 stop bits |
| enable receiver |
| parity enable |
| odd parity, else even |
| hang up on last close |
| ignore modem status lines |
| CTS flow control of output (this constant is only available on some systems; do not use in portable programs) |
| same as CCTS_OFLOW (this constant is only available on some systems; do not use in portable programs) |
| RTS flow control of input (this constant is only available on some systems; do not use in portable programs) |
| flow control output via Carrier (this constant is only available on some systems; do not use in portable programs) |
Table 4.14. Terminal Attributes Output Mode Constants
Name | Description |
---|---|
| enable following output processing |
| map NL to CR-NL (ala CRMOD) |
| map CR to NL |
| No CR output at column 0 |
| NL performs CR function |
| expand tabs to spaces (this constant is only available on some systems; do not use in portable programs) |
| discard EOT's ctrl-D on output (this constant is only available on some systems; do not use in portable programs) |
| translate lower case to upper case (this constant is only available on some systems; do not use in portable programs) |
Table 4.15. Terminal Attributes Input Mode Constants
Name | Description |
---|---|
| ignore BREAK condition |
| map BREAK to SIGINTR |
| ignore (discard) parity errors |
| mark parity and framing errors |
| enable checking of parity errors |
| strip 8th bit off chars |
| map NL into CR |
| ignore CR |
| map CR to NL (ala CRMOD) |
| enable output flow control |
| enable input flow control |
| any char will restart after stop |
| ring bell on input queue full |
| translate upper case to lower case (this constant is only available on some systems; do not use in portable programs) |
Table 4.16. Terminal Attributes Control Character Constants
Name | Special Character | Default Value |
---|---|---|
|
| ^D |
|
|
|
|
|
|
|
| ^? `177' |
|
| ^W |
|
| ^U |
|
| ^C |
|
| ^\ `34' |
|
| ^Z |
|
| ^Q |
|
| ^S |
|
| ^V |
| n/a | 1 |
| n/a | 0 |
|
| ^R (this constant is only available on some systems; do not use in portable programs) |
|
| ^Y (this constant is only available on some systems; do not use in portable programs) |
|
| ^O (this constant is only available on some systems; do not use in portable programs) |
| n/a | ^T (this constant is only available on some systems; do not use in portable programs) |
The X509_VerificationReasons_Hash
is a constant in the Qore namespace that maps verfication code strings (as returned from FtpClient::verifyPeerCertificate() and Socket::verifyPeerCertificate()) to textual descriptions.
Table 4.17. X506_VerificationReasons Hash
Key | Value |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The following gives a list of signal constants that may be present in Qore. Signal constants and their values are system-dependent; only signals that the host system defines will be present in Qore, therefore not all of the signals in the following list will be present in any given version of Qore. All signal constants are integers.
Table 4.18. Signal Constants in the Qore Namespace
Name | Description |
---|---|
| Hangup signal. |
| Interrupt signal. |
| Quit signal. |
| Illegal instruction signal. |
| Trace trap signal. |
| Abort signal. |
| Pollable event signal. |
| Synonym for SIBABRT |
| EMT instruction signal. |
| Floating-point exception signal. |
| Kill signal (cannot be caught) |
| Bus error signal. |
| Segmentation violation signal. |
| Bad argument to a system call. |
| Write on pipe with no reader (this signal is always ignored in Qore). |
| Alarm clock signal. |
| Software termination signal. |
| Urgent condition on I/O channel. |
| Sendable stop signal (not from tty). |
| Stop signal from tty. |
| Continue a stopped process. |
| To parent on child stop or exit. |
| To reader's process group on background tty read. |
| To writer's process group on background tty write. |
| Input/Output possible signal. |
| Exceeded CPU time limit. |
| Exceeded file size limit. |
| Virtual time alarm signal. |
| Profiling time alarm signal. |
| Window size changes signal. |
| Information request signal. |
| User-defined signal 1. |
| User-defined signal 2. |
| Stack fault on coprocessor. |
| Synonym for SIGCHLD on some systems. |
| Power failure signal. |
| Resource (ex: file lock) lost signal. |
| (Solaris) Waiting signal. |
| (Solaris) Light-weight process (thread) signal. |
| (Solaris) Checkpoint freeze signal. |
| (Solaris) Checkpoint freeze thaw signal. |
| (Solaris) Cancel signal. |
| (Solaris) Resource control exceeded. |
| (Solaris) Java virtual machine 1 signal. |
| (Solaris) Java virtual machine 2 signal. |
There are two special system-specific constants mapping signal names to signal number and vice-versa as given in the following table.
Table 4.19. Signal Mapping Hash Constants in the Qore Namespace
Name | Description |
---|---|
| A hash mapping signal numbers to signal names (ex: |
| A hash mapping signal names to signal numbers (ex: |
The Err namespace contains error constants, returned by the errno() function.
Table 4.20. Error Constants in the Err Namespace
Name | Type | Description |
---|---|---|
| System-dependent integer ERRNO constants (ex: ENOMEM, etc) |
Table 4.21. Exception Constants in the Qore Namespace
Name | Type | Description |
---|---|---|
| Exception Type System: used for system exceptions. | |
| Exception Type User: used for user exceptions (thrown using the throw statement. | |
| Call Type User: used for user function/method calls in a call stack. | |
| Call Type Builtin: used for builtin function/method calls in a call stack. | |
| Call Type New Thread: used in a call stack when a new thread is started with the background expression. | |
| Call Type Rethrow: a marker for a rethrown exception in a call stack. |
Table 4.22. Regular Expression Option Constants in the Qore Namespace
Name | Type and Value | Description |
---|---|---|
|
| Ignores case when matching regular expressions, equivalent to /i |
|
| makes start-of-line (^) or end-of-line ($) match after or before any newline in the subject string, equivalent to /m |
|
| makes a dot (.) match a newline character, equivalent to /s |
|
| ignores whitespace characters and enables comments prefixed by #, equivalent to /x |
The Type namespace only has constant definitions for basic Qore datatypes in it. There are no class definitions in the Type namespace. The type() function returns values in the set of the following constants. All of the following constants have string values.
Table 4.23. Type Constant Definitions
Name | Value | Corresponding Type |
---|---|---|
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
|
Note: This class is not available with the PO_NO_FILESYSTEM
parse option.
The File class allows Qore programs to read, write, and create files.
File objects can be created and/or opened with a specific character encoding, meaning that any string read from the file will be tagged with the file's character encoding, and any string data written to the file will be transparently converted to that character encoding before being written (if necessary). If no character encoding is specified, then the default Qore character encoding is assumed for the file.
This class supports posting events to a Queue. See Event Handling for more information.
The events raised by this object are listed in the following table:
Table 4.24. File Events
Name | Description |
---|---|
Raised when data is read from the file. | |
Raised when data is written to the file. | |
Raised when the file is closed. | |
Raised when the object being monitored is deleted. | |
Raised right before an attempt to open a file is made. | |
Raised when the file has been successfully opened. |
Table 4.25. File Method Overview
Method | Except? | Description |
---|---|---|
| N | Creates the object and optionally sets the file's character encoding. |
N | Closes the file if it is open and destroys the file object. | |
N | Creates a new file object with the same character encoding specification as the original, otherwise no other information is copied. | |
| N | Changes the user and group owners of the file on the filesystem (if the current user has sufficient permission to do so). |
| N | Closes the file object |
| Y | Writes a formatted string to a file, enforces hard field limits. |
| Y | Writes a formatted string to a file, where the second argument is the formatting argument list, enforces hard field limits. |
| N | Reads one character from the file; returns NOTHING if no data can be read from the file. |
| N | Returns the character encoding for the file |
| Y | Returns a hash of lock information. |
| N | Gets the current file position (in bytes) |
| Y | Saves the current terminal attributes for the file in the TermIOS object passed; changes the object passed to reflect the terminal attributes as set for the file. |
| Y | Returns true if there is data available for reading from the file within the timeout period. |
| Y | Attempts to lock the file according to the arguments passed, does not block. |
| Y | Attempts to lock the file according to the arguments passed, blocking. |
| Y | Opens a file in a particular mode, returns an error code on failure. |
| Y | Opens a file in a particular mode; throws an exception on failure. |
| Y | Writes a formatted string to a file. |
| Y | Reads a certain number of bytes from the file within an optional timeout period and returns a string of the data read or NOTHING if no data can be read. |
| Y | Reads a certain number of bytes from the file within an optional timeout period and returns binary data or NOTHING if no data can be read. |
| Y | Reads a 1-byte signed integer from the file or NOTHING if no data can be read. |
| Y | Reads a 2-byte signed integer from the file in big-endian format or NOTHING if no data can be read. |
| Y | Reads a 4-byte signed integer from the file in big-endian format or NOTHING if no data can be read. |
| Y | Reads an 8-byte signed integer from the file in big-endian format or NOTHING if no data can be read. |
| Y | Reads a 2-byte signed integer from the file in little-endian format or NOTHING if no data can be read. |
| Y | Reads a 4-byte signed integer from the file in little-endian format or NOTHING if no data can be read. |
| Y | Reads an 8-byte signed integer from the file in little-endian format or NOTHING if no data can be read. |
| Y | Reads a 1-byte unsigned integer from the file or NOTHING if no data can be read. |
| Y | Reads a 2-byte unsigned integer from the file in big-endian format or NOTHING if no data can be read. |
| Y | Reads a 4-byte unsigned integer from the file in big-endian format or NOTHING if no data can be read. |
| Y | Reads a 2-byte unsigned integer from the file in little-endian format or NOTHING if no data can be read. |
| Y | Reads a 4-byte unsigned integer from the file in little-endian format or NOTHING if no data can be read. |
| Y | Reads until an EOL marker is found and returns the string read or NOTHING if no data can be read. |
| N | Sets the character encoding for the file; if passed with no argument, the default encoding is set. |
| N | Sets the current file position (in bytes). |
| Y | Sets the current terminal attributes for the file from the TermIOS object passed; does not change the object passed. |
| N | Flushes the file's buffer to disk. |
| Y | Writes a formatted string to a file, where the second argument is the formatting argument list. |
| Y | Writes string or binary data to a file |
| Y | Writes a 1-byte integer to the file. |
| Y | Writes a 2-byte integer in big-endian format. |
| Y | Writes a 4-byte integer in big-endian format. |
| Y | Writes an 8-byte integer in big-endian format. |
| Y | Writes a 2-byte integer in little-endian format. |
| Y | Writes a 4-byte integer in little-endian format. |
| Y | Writes an 8-byte integer in little-endian format. |
Creates the File object. It accepts one optional argument that will set the default character encoding for the file (only affects reading and writing string data).
File::constructor(string
$encoding
)
my File $f("ISO-8859-1"); # specify ISO-8859-1 encoding for the file
Table 4.29. Arguments for File::constructor()
Argument | Type | Description |
---|---|---|
| The character encoding for the file. Any strings written to the file will be converted to this character encoding if necessary. |
Closes the file if it's open and destroys the File object.
delete $f;
Creates a new File object with the same character encoding specification as the original.
my File $f1 = $f.copy();
Changes the file's user and group owner (if the user has sufficient permissions to do so).
File::chown(softint
$uid
, softint $gid
= -1) returns nothing
$f.chown(0, 0);
Table 4.31. Return Value for File::chown()
Return Type | Description |
---|---|
n/a | This method does not return a value; if an error occurs, an exception is thrown. |
Table 4.32. Exceptions Thrown by File::chown()
err | desc |
---|---|
| File is not open or the chown operation failed. |
Closes the file object if it's open. Note that this is automatically called by File::destructor().
File::close() returns int
$f.close();
Table 4.33. Return Value for File::close()
Return Type | Description |
---|---|
0 for success, -1 for an error (see errno() and strerror() for the error information) |
Writes a formatted string to a file, enforces hard field limits (similar to the f_printf() function). See String Formatting for more information about the format string.
File::f_printf(string
$fmt
, ...) returns int
File::f_printf() returns int (RT_NOOP)
$f.f_printf("%5s\n", "long string"); # will print "long \n", respecting the 5-character field width
Table 4.34. Arguments for File::f_printf()
Argument | Description |
---|---|
| The format string, see String Formatting for a specification. |
| The remainder of the arguments are arguments to the format string. |
Table 4.35. Return Value for File::f_printf()
Return Type | Description |
---|---|
Returns 0 for success, -1 for error. |
Writes a formatted string to a file, where the second argument is the formatting argument list, enforces hard field limits. See String Formatting for more information about the format string.
File::f_vprintf(string
$fmt
, any $args
) returns int
File::f_vprintf() returns int (RT_NOOP)
$f.f_vprintf("%5s %3d\n", ("a long string", 5000)); # outputs "a lon 500", truncating output
Table 4.37. Arguments for File::f_vprintf()
Argument | Description |
---|---|
| The format string, see String Formatting for a specification. |
| This single argument or list of arguments will be used as the argument list or the format string. If a single argument is passed instead of a list, it will be used as the first argument as if a list were passed. |
Table 4.38. Return Value for File::f_vprintf()
Return Type | Description |
---|---|
Returns 0 for success, -1 for error. |
Reads one character from the file and returns it as a one-character string. Returns NOTHING if no data can be read from the file.
File::getchar() returns any
$char = $f.getchar();
Returns the character encoding for the file.
File::getCharset() returns string
$encoding = $f.getCharset();
Table 4.41. Return Value for File::getCharset()
Return Type | Description |
---|---|
The character encoding for the file. |
Returns a hash of lock information for the file. The hash contains the following keys: start, len, pid, type, whence
. If no lock is set on the file, the key type has the value F_UNLCK
.
File::getLockInfo() returns hash
my hash $hash = $f.getLockInfo();
Table 4.43. Exceptions Thrown by File::getLockInfo()
err | desc |
---|---|
| File is not open or the fcntl operation failed. |
Gets the current file position as an integer giving the offset in bytes from the beginning of the file (starting from zero).
File::getPos() returns int
$pos = $f.getPos();
Table 4.44. Return Value for File::getPos()
Return Type | Description |
---|---|
The byte position in the file starting at 0. |
Saves the current terminal attributes for the file in the TermIOS object passed; changes the object passed to reflect the terminal attributes as set for the file. Do not pass a reference to the TermIOS object; pass the object itself.
File::getTerminalAttributes(TermIOS
$termios
) returns nothing
my TermIOS $termios();
stdin.getTerminalAttributes($termios);
Table 4.45. Arguments for File::getTerminalAttributes()
Argument | Description |
---|---|
| The method writes the current terminal attributes for the file to the object passed. |
Table 4.46. Exceptions Thrown by File::getTerminalAttributes()
err | desc |
---|---|
| The file is not open. |
| Error reading terminal attributes from the file descriptor. |
Returns True
is data becomes available for reading on the file within a timeout period. With a timeout of zero (the default if no timeout value is passed), this method can be used for non-blocking polling the file for data. Like all Qore functions and methods taking timeout values, a relative time value may be passed instead of an integer to make the timeout units clear (ex: 25ms
).
File::isDataAvailable(softint
$timeout_ms
) returns bool
File::isDataAvailable(date
$timeout
) returns bool
File::isDataAvailable() returns bool
my bool $b = $file.isDataAvailable(0); # returns True
if data is available now
Table 4.48. Return Values for File::isDataAvailable()
Return Type | Description |
---|---|
True if data becomes available for reading from the file within the timeout period, |
Locks or unlocks a portion of the file or the entire file, for reading or writing, non-blocking. The file must be opened in the appropriate mode before this call or the call will fail with an exception. For a blocking version of this method, see File::lockBlocking().
File::lock(softint
$type
= F_RDLCK, softint $start
= 0, softint $len
= 0, softint $whence
= SEEK_SET) returns int
# lock the entire file exclusively $f.lock(F_WRLCK); # lock a section of the file for reading, start byte 512, 2K range $f.lock(F_RDLCK, 512, 2048); # release all locks $f.lock(F_UNLCK);
Table 4.50. Arguments for File::lock()
Argument | Description |
---|---|
Type of lock (or unlock); see File locking constants. | |
| Start byte for lock, 0 is the default (start of file). |
| Length in bytes for range to lock, 0 is the default (rest of file). |
Indicates how the relative offset of the file should be calculated for the lock; see File seek constants. |
Table 4.51. Return Value for File::lock()
Return Type | Description |
---|---|
Returns 0 for success, |
Table 4.52. Exceptions Thrown by File::lock()
err | desc |
---|---|
| File is not open, lock length is negative, or the fcntl operation failed. |
Locks or unlocks a portion of the file or the entire file, for reading or writing, blocking. The file must be opened in the appropriate mode before this call or the call will fail with an exception. For a non-blocking version of this method, see File::lock().
File::lockBlocking(softint
$type
= F_RDLCK, softint $start
= 0, softint $len
= 0, softint $whence
= SEEK_SET) returns nothing
# lock the entire file exclusively $f.lockBlocking(F_WRLCK); # lock a section of the file for reading, start byte 512, 2K range $f.lockBlocking(F_RDLCK, 512, 2048); # release all locks $f.lockBlocking(F_UNLCK);
Table 4.53. Arguments for File::lockBlocking()
Argument | Description |
---|---|
Type of lock (or unlock), see File locking constants. | |
| Start byte for lock, 0 is the default (start of file). |
| Length in bytes for range to lock, 0 is the default (rest of file). |
Indicates how the relative offset of the file should be calculated for the lock; see File seek constants. |
Table 4.54. Return Value for File::lockBlocking()
Return Type | Description |
---|---|
n/a | This method does not return a value; exceptions are thrown if errors occur. |
Table 4.55. Exceptions Thrown by File::lockBlocking()
err | desc |
---|---|
| File is not open, lock length is negative, or the fcntl operation failed. |
Writes a formatted string with soft field widths to the file. See File::f_printf() for a similar method that enforces field widths. See String Formatting for more information about the format string.
File::printf(string
$fmt
, ...) returns int
File::printf() returns int (RT_NOOP)
$f.printf("%5s\n", "hello there"); # outputs "hello there\n", exceeding field width
Table 4.56. Arguments for File::printf()
Argument | Description |
---|---|
| The format string, see String Formatting for a specification. |
... | The remainder of the arguments are arguments to the format string. |
Table 4.57. Return Value for File::printf()
Return Type | Description |
---|---|
Returns 0 for success, -1 for error. |
Opens the file in the mode given. Aditionally, the file permissions can be given if the file is to be created, and optionally the file's default character encoding can be specified.
Note that if no encoding is specified, the file will be tagged with the default character encoding for the process. Any string data written to the file will be converted to the file's encoding, and any string data read from the file will be automatically tagged with the file's encoding.
For a version of this method that throws an exception when errors occur opening the file, see File::open2().
File::open(string
$path
, softint $flags
= O_RDONLY, softint $mode
= 0666) returns int
File::open(string
$path
, softint $flags
= O_RDONLY, softint $mode
= 0666, string $encoding
) returns int
# open a file for writing, truncate data if already exists, create the file if doesn't exist # set 0644 permissions, and convert all string data to ISO-8859-1 encoding $f.open("new_file.txt", O_CREAT | O_TRUNC | O_WRONLY, 0644, "ISO-8859-1");
Table 4.59. Arguments for File::open()
Argument | Description |
---|---|
| The path to the file. |
Flags that determine the way the file is accessed, see File Constants for more information. If this argument is not given, | |
| Permission bits for when the file is to be created (default: 0666) |
| The name of the default character encoding for this file; if this argument is not given, the file will be tagged with the default character encoding for the process. |
Table 4.60. Return Values for File::open()
Return Type | Description |
---|---|
0 = no error, -1 = see errno() and strerror() for the error message |
Table 4.61. Exceptions Thrown by File::open()
err | desc |
---|---|
| Missing filename argument. |
Opens the file in the mode given. Aditionally, the file permissions can be given if the file is to be created, and optionally the file's default character encoding can be specified.
Note that if no encoding is specified, the file will be tagged with the default character encoding for the process. Any string data written to the file will be converted to the file's encoding, and any string data read from the file will be automatically tagged with the file's encoding.
If an error occurs, a FILE-OPEN2-ERROR
exception is thrown. For a version of this method that returns an error code, see File::open().
File::open2(string
$path
, softint $flags
= O_RDONLY, softint $mode
= 0666) returns nothing
File::open2(string
$path
, softint $flags
= O_RDONLY, softint $mode
= 0666, string $encoding
) returns nothing
# open a file for writing, truncate data if already exists, create the file if doesn't exist # set 0644 permissions, and convert all string data to ISO-8859-1 encoding $f.open2("new_file.txt", O_CREAT | O_TRUNC | O_WRONLY, 0644, "ISO-8859-1");
Table 4.62. Arguments for File::open2()
Argument | Description |
---|---|
| The path to the file. |
Flags that determine the way the file is accessed, see File Constants for more information. If this argument is not given, | |
| Permission bits for when the file is to be created (default: 0666) |
| The name of the default character encoding for this file; if this argument is not given, the file will be tagged with the default character encoding for the process. |
Table 4.63. Exceptions Thrown by File::open2()
err | desc |
---|---|
| Missing filename argument. |
| Error opening the file; attempted to reopen a system file (I/O constants). |
Reads a certain amount of string data from the file; the size argument is required. To read binary data, use the File::readBinary() method.
Note that the amount of data read from the file may be less than the size given, for example if the file does not contain enough data to fulfill the request. In this case, only the data available in the file is returned.
An optional timeout period in milliseconds can be passed as well (or a relative time value may be passed instead of an integer to make the timeout units clear; ex: 25ms
). If a timeout value is passed and the data cannot be read within the timeout period, then a FILE-READ-TIMEOUT
exception is thrown. If no timeout value is passed or a negative value is given, then the call will never timeout until either the requested amount of data has been read from the file or an end-of-file condition has been reached.
File::read(softint
$size
) returns any
File::read(softint
$size
, softint $timeout_ms
) returns any
File::read(softint
$size
, date $timeout
) returns any
$data = $f.read(-1); # read an entire text file into a variable
Table 4.64. Arguments for File::read()
Argument | Description |
---|---|
| The number of bytes to read of the file, -1 will read the entire file. |
A timeout period with a resolution of milliseconds (an integer argument will be assumed to be milliseconds)); if not given or negative the call will never time out and will only return when the data has been read. |
Table 4.66. Exceptions Thrown by File::read()
err | desc |
---|---|
| Missing size argument. |
| File is not open; timeout limit exceeded. |
Reads a 1-byte signed integer from the file and returns the integer value read.
File::readi1() returns any
my any $i = $f.readi1();
Reads a 2-byte signed integer from the file in big-endian (MSB, network byte order) format. See File::readi2LSB() for an equivalent method reading a 2-byte signed integer in little-endian (LSB) format.
File::readi2() returns any
my any $i = $f.readi2();
Reads a 4-byte signed integer from the file in big-endian format. See File::readi4LSB() for an equivalent method reading a 4-byte signed integer in little-endian (LSB) format.
File::readi4() returns any
my any $i = $f.readi4();
Reads a 4-byte signed integer from the file in big-endian format. See File::readi8LSB() for an equivalent method reading a 4-byte signed integer in little-endian (LSB) format.
File::readi8() returns any
$i = $f.readi8();
Reads a 2-byte signed integer from the file in little-endian (LSB) format. See File::readi2() for an equivalent method reading a 2-byte signed integer in big-endian (MSB, network byte order) format.
File::readi2LSB() returns any
my any $i = $f.readi2LSB();
Reads a 4-byte signed integer from the file in little-endian format. See File::readi4() for an equivalent method reading a 4-byte signed integer in big-endian (MSB, network byte order) format.
File::readi4LSB() returns any
my any $i = $f.readi4LSB();
Reads an 8-byte signed integer from the file in little-endian format. See File::readi8() for an equivalent method reading a 8-byte signed integer in big-endian (MSB, network byte order) format.
File::readi8LSB() returns any
my any $i = $f.readi8LSB();
Reads a 1-byte unsigned integer from the file and returns the integer value read.
File::readu1() returns any
my any $i = $f.readu1();
Reads a 2-byte signed integer from the file in big-endian (MSB, network byte order) format. See File::readu2LSB() for an equivalent method reading a 2-byte signed integer in little-endian (LSB) format.
File::readu2() returns any
my any $i = $f.readu2();
Reads a 4-byte signed integer from the file in big-endian format. See File::readu4LSB() for an equivalent method reading a 4-byte signed integer in little-endian (LSB) format.
File::readu4() returns any
my any $i = $f.readu4();
Reads a 2-byte signed integer from the file in little-endian (LSB) format. See File::readu2() for an equivalent method reading a 2-byte signed integer in big-endian (MSB, network byte order) format.
File::readu2LSB() returns any
my any $i = $f.readu2LSB();
Reads a 4-byte unsigned integer from the file in little-endian format. See File::readu4() for an equivalent method reading a 4-byte signed integer in big-endian (MSB, network byte order) format or NOTHING if no data can be read.
File::readu4LSB() returns any
my any $i = $f.readu4LSB();
Read a certain amount of data and return a binary object; the size parameter is mandatory.
Note that the amount of data read from the file may be less than the size given, for example if the file does not contain enough data to fulfill the request. In this case, only the data available in the file is returned.
An optional timeout period in milliseconds can be passed as well (or a relative time value may be passed instead of an integer to make the timeout units clear; ex: 25ms
). If a timeout value is passed and the data cannot be read within the timeout period, then a FILE-READ-TIMEOUT
exception is thrown. If no timeout value is passed or a negative value is given, then the call will never timeout until either the requested amount of data has been read from the file or an end-of-file condition has been reached.
File::readBinary(softint
$size
) returns any
File::readBinary(softint
$size
, softint $timeout_ms
) returns any
File::readBinary(softint
$size
, date $timeout
) returns any
$data = $f.readBinary(-1); # reads an entire binary file into a variable
Table 4.91. Arguments for File::readBinary()
Argument | Type | Description |
---|---|---|
| The number of bytes to read of the file. | |
| Integer or Relative Date/Time | A timeout period in milliseconds; if not given or negative the call will never time out and will only return when the data has been read. |
Table 4.93. Exceptions Thrown by File::readBinary()
err | desc |
---|---|
| Missing size argument. |
| File is not open; timeout limit exceeded. |
Reads until an EOL marker is found and returns a string containing the EOL marker. Returns NOTHING on end of file.
File::readLine() returns any
while (exists (my $line = $f.readLine())) { # remove EOL marker chomp $line; # print out the line just read printf("%s\n", $line); }
Sets the characte encoding for the file.
File::setCharset() returns nothing
File::setCharset(string
$encoding
) returns nothing
$f.setCharset("ISO-8859-1");
Table 4.96. Arguments for File::setCharset()
Argument | Description |
---|---|
| The character encoding for the file. |
Sets the current file position in bytes starting with zero.
File::setPos(softint
$pos
= 0) returns int
$f.setPos(0); # go to the beginning of the file
Table 4.97. Arguments for File::setPos()
Argument | Description |
---|---|
| The position in the file as offset from position 0. |
Table 4.98. Return Value for File::setPos()
Return Type | Description |
---|---|
Returns the new offset in the file, -1 for error. |
Sets the terminal attributes for the file from the TermIOS object passed; does not change the object passed.
File::setTerminalAttributes(softint
$action
= TCSANOW, TermIOS $termios
) returns nothing
my TermIOS $termios(); stdin.getTerminalAttributes($termios); my TermIOS $orig = $termios.copy(); on_exit stdin.setTerminalAttributes(TCSADRAIN, $orig); my $lflag = $termios.getLFlag(); $lflag &= ~ICANON; $lflag &= ~ECHO; $lflag &= ~ISIG; $termios.setLFlag($lflag); $termios.setCC(VMIN, 1); $termios.setCC(VTIME, 0); stdin.setTerminalAttributes(TCSADRAIN, $termios);
Table 4.100. Return Value for File::setTerminalAttributes()
Return Type | Description |
---|---|
Always returns 0; if an error is encountered, an exception is raised. |
Table 4.101. Exceptions Thrown by File::setTerminalAttributes()
err | desc |
---|---|
| The file is not open. |
| Error setting terminal attributes on the file descriptor. |
Flushes the file's buffer to disk.
File::sync() returns int
$f.sync();
Table 4.102. Return Value for File::sync()
Return Type | Description |
---|---|
Returns 0 for success, -1 for error. |
Writes a formatted string to a file, where the first argument is a format string,and the second argument is the formatting argument list.
File::vprintf(string
$fmt
, any $args
) returns int
File::vprintf() returns int (RT_NOOP)
$f.vprintf("%5s\n", "hello");
Table 4.103. Arguments for File::vprintf()
Argument | Description | |
---|---|---|
| The format string, see String Formatting for a specification. | |
| This single argument or list of arguments will be used as the argument list or the format string. If a single argument is passed instead of a list, it will be used as the first argument as if a list were passed. |
Table 4.104. Return Value for File::vprintf()
Return Type | Description |
---|---|
Returns 0 for success, -1 for error. |
Writes string or binary data to a file. String data will be converted to the file's character encoding if necessary before writing.
File::write(data
$data
) returns int
$f.write($data);
Table 4.107. Return Value for File::write()
Return Type | Description |
---|---|
Returns 0 for success, -1 for error. |
Table 4.108. Exceptions Thrown by File::write()
err | desc |
---|---|
| Missing string or binary argument. |
| File is not open. |
Writes a 1-byte integer to the file.
File::writei1(softint
$i
= 0) returns int
$f.writei1($val);
Table 4.109. Arguments for File::writei1()
Argument | Description |
---|---|
| The integer to write; only the least-significant 8 bits will be written to the file. |
Table 4.110. Return Value for File::writei1()
Return Type | Description |
---|---|
Returns 0 for success, -1 for error. |
Writes a 2-byte integer in big-endian format.
File::writei2(softint
$i
= 0) returns int
$f.writei2($val);
Table 4.112. Arguments for File::writei2()
Argument | Description |
---|---|
| The integer to write; writes a 2-byte integer in big-endian format. |
Table 4.113. Return Value for File::writei2()
Return Type | Description |
---|---|
Returns 0 for success, -1 for error. |
Writes a 4-byte integer in big-endian format.
File::writei4(softint
$i
= 0) returns int
$f.writei4($val);
Table 4.115. Arguments for File::writei4()
Argument | Description |
---|---|
| The integer to write; writes a 4-byte integer in big-endian format. |
Table 4.116. Return Value for File::writei4()
Return Type | Description |
---|---|
Returns 0 for success, -1 for error. |
Writes an 8-byte integer in big-endian format.
File::writei8(softint
$i
= 0) returns int
$f.writei8($val);
Table 4.118. Arguments for File::writei8()
Argument | Description |
---|---|
| The integer to write; writes an 8-byte integer in big-endian format. |
Table 4.119. Return Value for File::writei8()
Return Type | Description |
---|---|
Returns 0 for success, -1 for error. |
Writes a 2-byte integer in little-endian format.
File::writei2LSB(softint
$i
= 0) returns int
$f.writei2LSB($val);
Table 4.121. Arguments for File::writei2LSB()
Argument | Description |
---|---|
| The integer to write; writes a 2-byte integer in little-endian format. |
Table 4.122. Return Value for File::writei2LSB()
Return Type | Description |
---|---|
Returns 0 for success, -1 for error. |
Writes a 4-byte integer in little-endian format.
File::writei4LSB(softint
$i
= 0) returns int
$f.writei4LSB($val);
Table 4.124. Arguments for File::writei4LSB()
Argument | Description |
---|---|
| The integer to write; writes a 4-byte integer in little-endian format. |
Table 4.125. Return Value for File::writei4LSB()
Return Type | Description |
---|---|
Returns 0 for success, -1 for error. |
Writes an 8-byte integer to the file in little-endian (LSB) format.
File::writei8LSB(softint
$i
= 0) returns int
$f.writei8LSB($val);
Table 4.127. Arguments for File::writei8LSB()
Argument | Description |
---|---|
| The integer to write; writes an 8-byte integer in little-endian format. |
Table 4.128. Return Value for File::writei8LSB()
Return Type | Description |
---|---|
Returns 0 for success, -1 for error. |
Note: This class is not available with the PO_NO_FILESYSTEM
parse option.
The Dir class allows Qore programs to list and manipulate directories.
Directory objects can be created/opened with a specific character encoding. This means that any entry read from the directory will be tagged with the directory's character encoding. If no character encoding is given the default Qore character encoding is assumed.
Table 4.130. Dir Method Overview
Method | Except? | Description |
---|---|---|
| N | Create a Directory object with optional character encoding. It points to the directory the script is started. |
N | Destroys the directory object. | |
N | Creates a new directory object with the same character encoding specification and the same path as the original. | |
| N | Change the path of the directory. The path specification can be relative or absolute (with leading '/'). This path does not necessarily need to exist. |
N | Returns a string giving the current path of the object, stripped of all '.' and '..' entries or NOTHING if no path is set. | |
| N | Checks if the path in the object is an openable directory. |
| Y | Try to create all directories of the object if they do not exist yet; if any errors occur an exception is thrown. |
| Y | Change the ownership of the directory to the given user. |
| Y | Change the group membership of the directory to the given group. |
| Y | Change the permissions of the directory to the given mode; if any errors occur an exception is thrown. |
| Y | Create a subdirectory with the name in the directory; if any errors occur an exception is thrown. |
| Y | Delete an empty subdirectory with the name in the directory; if any errors occur an exception is thrown. |
Y | Get all entries in this directory, except '.' and '..' directories (takes an optional regular expression filter); if any errors occur an exception is thrown. | |
| Y | Get all entries in the directory which are not subdirectories (takes an optional regular expression filter); if any errors occur an exception is thrown. |
| Y | Get all entries in the directory which are subdirectories, except '.' and '..' directories (takes an optional regular expression filter); if any errors occur an exception is thrown. |
| Y | Get a Dir object as an subdir entry of the current directory. |
| Y | Get a File object which represents a file in the directory. |
| Y | Remove (unlink) a file in this directory. |
Creates a Dir object. It accepts one optional argument that will set the default character encoding encoding for the directory.
Dir::constructor(string
$encoding
)
my Dir $d("UTF-8");
Table 4.131. Arguments for Dir::constructor()
Argument | Description |
---|---|
| The character encoding for the directory. Any entry of the directory will be converted to this character encoding if necessary, and entries read will be tagged with this encoding. If no encoding is given, the default encoding is used. |
Creates a new Dir object with the same character encoding specification and path as the original.
my Dir $d2 = $d.copy();
Change the directory of the Dir object to the path; you can use either an absolute path (leading with '/') or a directory realtive to the actual path.
Dir::chdir(string
$path
) returns bool
if ($d.chdir("../doc")) {
printf("the directory does not exist or is not readable\n");
}
Returns True
if the path in the Dir object points to a directory that already exists and is openable by the current user.
Dir::exists() returns bool
if (!$d.exists()) {
printf("the directory %s does not exist or cannot be opened\n", $d.path());
exit(-1);
}
Table 4.135. Return Value for Dir::exists()
Return Type | Description |
---|---|
True if the directory exists and is openable. |
Create the whole directory tree the Dir object points to, if it does not exist till now.
Dir::create(softint
$mode
= 0777) returns int
if (!$d.exists()) {
printf("directory '%s' does not exist; creating...\n", $d.path());
$cnt = $d.create();
}
Table 4.136. Arguments for Dir::create()
Argument | Description |
---|---|
| The mode of the directory. |
Table 4.138. Exceptions Thrown by Dir::create()
err | desc |
---|---|
| One of the directories in the path could not be created. |
Change the ownership of the directory.
Dir::chown(softint
$uid
) returns nothing
Dir::chown(string
$username
) returns nothing
$d.chown("nobody");
Table 4.140. Exceptions Thrown by Dir::chown()
err | desc |
---|---|
| Parameter error. |
| The error occoured in the chown() call. |
Change the group membership of the directory.
Dir::chgrp(softint
$gid
) returns nothing
Dir::chgrp(string
$groupname
) returns nothing
$d.chgrp("nogroup");
Table 4.142. Exceptions Thrown by Dir::chgrp()
err | desc |
---|---|
| Parameter error. |
| Error occoured during the change group chown() system call. |
Change the mode of the directory.
Dir::chmod(softint
$mode
) returns nothing
$d.chmod(0711); # set mode to u(rwx) and go(x)
Table 4.144. Exceptions Thrown by Dir::chmod()
err | desc |
---|---|
| Parameter error. |
| The error returned from the chmod() system call. |
Make a subdirectory in the Dir object's path. There are no path info allowed (the '/'). If no mode is given the mode 0777 is used.
Dir::mkdir(string
$name
, softint $mode
= 0777) returns nothing
$d.mkdir("newSubDir", 0755);
Table 4.146. Exceptions Thrown by Dir:mkdir()
err | desc |
---|---|
| Parameter error. |
| The error returned from the mkdir() system call. |
Remove a subdirectory from the Dir object's path. There is no pathinfo allowed in the name (the '/' delimiter).
Dir::rmdir(string
$subdir
) returns nothing
$d.rmdir("emptySubdir");
Table 4.147. Arguments for Dir::rmdir()
Argument | Description |
---|---|
| The name of the directory to be removed. |
Table 4.148. Exceptions Thrown by Dir::rmdir()
err | desc |
---|---|
| Parameter error. |
| The error returned from the rmdir() system call. |
List all entries in the directory of the Dir object. It supresses the '.' and '..' directory. An optional regular expression string can be passed to filter the values returned; if this argument is given then only entries that match the regular expression will be returned.
foreach my string $e in ($d.list()) { printf("entry: %s\n"); }
Table 4.149. Arguments for Dir::list()
Argument | Description |
---|---|
An optional regular expression string used to filter the arguments followed by bitwise-or'ed regex option constants. |
Table 4.150. Return Value for Dir::list()
Return Type | Description |
---|---|
A list of Strings with the directories content. |
Table 4.151. Exceptions Thrown by Dir::list()
err | desc |
---|---|
| The error returned from the readdir() system call. |
List all entries in the directory of the Dir object, which are not subdirectories. An optional regular expression string can be passed to filter the values returned; if this argument is given then only entries that match the regular expression will be returned.
Dir::listFiles() returns list
Dir::listFiles(string
$regex
) returns list
Dir::listFiles(string
$regex
, int $options
) returns list
foreach my string $e in ($d.listFiles()) { printf("entry: %s\n"); }
Table 4.152. Arguments for Dir::listFiles()
Argument | Description |
---|---|
An optional regular expression string used to filter the arguments followed by bitwise-or'ed regex option constants. |
Table 4.153. Return Value for Dir::listFiles()
Return Type | Description |
---|---|
A list of strings with the file names as elements. |
Table 4.154. Exceptions Thrown by Dir::listFiles()
err | desc |
---|---|
| The error returned from the readdir() system call. |
List all entries in the directory of the Dir object that are subdirectories, not including the '.' and '..' directories. An optional regular expression string can be passed to filter the values returned; if this argument is given then only entries that match the regular expression will be returned.
Dir::listDirs() returns list
Dir::listDirs(string
$regex
) returns list
Dir::listDirs(string
$regex
, int $options
) returns list
foreach my string $e in ($d.listDirs()) { printf("entry: %s\n"); }
Table 4.155. Arguments for Dir::listDirs()
Argument | Description |
---|---|
An optional regular expression string used to filter the arguments followed by bitwise-or'ed regex option constants. |
Table 4.156. Return Value for Dir::listDirs()
Return Type | Description |
---|---|
A list of strings with the directory names found. |
Table 4.157. Exceptions Thrown by Dir::listDirs()
err | desc |
---|---|
| The error returned from the readdir() system call. |
Return a Dir object in the directory of the Dir object. The dirname does not allow path information (the '/').
Dir::openDir(string
$subdir
) returns Dir
Dir::openDir(string
$subdir
, string $encoding
) returns Dir
# open a subdir for working with my Dir $sd = $d.openDir("mysubdir", "ISO-8859-1"); my list $sd_list = $sd.list();
Table 4.158. Arguments for Dir::openDir()
Argument | Description |
---|---|
The name of the subdirectory. The directory must not exist and can be created with create() afterwards. If no encoding is given, the default encoding is used. |
Table 4.159. Return Value for Dir::openDir()
Return Type | Description |
---|---|
The Dir object created for the directory. |
Table 4.160. Exceptions Thrown by Dir::openDir()
err | desc |
---|---|
| The directory name to be opened contains path information ('/'). |
Create or open a File object in the directory of the Dir object. The filename does not allow path information (the '/'). Uses the File::open2() method.
Dir::openFile(string
$name
, softint $flags
= O_RDONLY, softint $mode
= 0666) returns File
Dir::openFile(string
$name
, softint $flags
= O_RDONLY, softint $mode
= 0666, string $encoding
) returns File
# open a file for writing in the directory and set the mode to
# 0644 and the encoding to UTF-8
my $f = $d.openFile("myfile.txt", O_CREAT|O_WRONLY, 0644, "UTF-8");
Table 4.161. Arguments for Dir::openFile()
Argument | Description |
---|---|
| The name of the file in the current directory. |
Flags that determine the way the file is accessed, see File Constants for more information. If this argument is not given, | |
| Permission bits for when the file is to be created (default: 0666) |
| The name of the default character encoding for this file; if this argument is not given, the file will be tagged with the default character encoding for the process. |
Table 4.162. Return Value for Dir::openFile()
Return Type | Description |
---|---|
Object | The File object created or opened in the directory. |
Table 4.163. Exceptions Thrown by Dir::openFile()
err | desc |
---|---|
| The file name to be opened contains path information ('/'). |
File Exceptions | Exceptions thrown by the File::open2() call. |
Remove the file with the given name in the Dir object's directory.
Dir::removeFile(string
$name
) returns bool
$d.removeFile("myTestFile.dat");
Table 4.164. Arguments for Dir::removeFile()
Argument | Description |
---|---|
| The name of the file in the directory. |
Table 4.165. Return Value for Dir::removeFile()
Return Type | Description |
---|---|
True if the file was present and could be removed. |
Table 4.166. Exceptions Thrown by Dir::removeFile()
err | desc |
---|---|
| Parameter error. |
| The error returned by the unlink() system call. |
Note: This class is not available with the PO_NO_TERMINAL_IO
parse option.
This class contains the data structure used to read and set terminal attributes on terminal I/O constants.
This class is used with File::getTerminalAttributes(), File::setTerminalAttributes(), and the terminal I/O constants to manipulate terminal attributes.
For example, here is some code to set terminal attributes, read in a character from stanrdard input with a timeout, and reset the terminal attributes:
my TermIOS $t(); stdin.getTerminalAttributes($t); my TermIOS $orig = $t.copy(); on_exit stdin.setTerminalAttributes(TCSADRAIN, $orig); my $lflag = $t.getLFlag(); $lflag &= ~ICANON; $lflag &= ~ECHO; $lflag &= ~ISIG; $t.setLFlag($lflag); $t.setCC(VMIN, 1); $t.setCC(VTIME, 0); stdin.setTerminalAttributes(TCSADRAIN, $t); stdout.printf("Press any key: "); while (!stdin.isDataAvailable(20ms)) { stdout.printf("."); stdout.sync(); usleep(1ms); } my $c = stdin.read(1); stdout.printf(" GOT ASCII 0x%02x (%d) '%s'\n", ord($c), ord($c), $c);
For more information on terminal attributes, see your system's manual pages for "termios".
Table 4.167. TermIOS Method Overview
Method | Except? | Description |
---|---|---|
Y | Creates the TermIOS object. | |
N | Destroys the TermIOS object. | |
N | Returns a copy of the object. | |
| N | Gets the local mode value of the object. |
| N | Gets the control mode value of the object. |
| N | Gets the output mode value of the object. |
| N | Gets the input mode value of the object. |
| N | Sets the local mode of the object. |
| N | Sets the control mode of the object. |
| N | Sets the output mode of the object. |
| N | Sets the input mode of the object. |
| Y | Gets the value of a control character for the object. |
| Y | Sets the value of a control character for the object. |
| Y | Returns true if the object passed is equal to the current object, false if not. |
| Y | Returns a hash giving the current terminal window size in hash keys |
Creates the TermIOS object with random contents. Use File::getTerminalAttributes() with a terminal I/O constant to initialize the object with terminal settings.
my TermIOS $termios();
stdin.getTerminalAttributes($termios);
Destroys the TermIOS object.
delete $termios;
This method does not throw any exceptions.
Returns a copy of the object.
my TermIOS $t2 = $t.copy();
This method does not throw any exceptions.
Returns the local mode flag for the object
TermIOS::getLFlag() returns int
Table 4.168. Return Values for TermIOS::getLFlag()
Return Type | Description |
---|---|
The local mode flag for the object |
Returns the control mode flag for the object
TermIOS::getCFlag() returns int
Table 4.169. Return Values for TermIOS::getCFlag()
Return Type |
Description |
---|---|
The control mode flag for the object |
Returns the input mode flag for the object
TermIOS::getIFlag() returns int
Table 4.170. Return Values for TermIOS::getIFlag()
Return Type |
Description |
---|---|
The input mode flag for the object |
Returns the output mode flag for the object
TermIOS::getOFlag() returns int
Table 4.171. Return Values for TermIOS::getOFlag()
Return Type |
Description |
---|---|
The output mode flag for the object |
Sets the local mode flag for the object
TermIOS::setLFlag(softint
$val
= 0) returns nothing
Table 4.172. Arguments for TermIOS::setLFlag()
Argument | Description |
---|---|
| The local mode to set for the object. |
Sets the control mode flag for the object
TermIOS::setCFlag(softint
$val
= 0) returns nothing
Table 4.173. Arguments for TermIOS::setCFlag()
Argument | Description |
---|---|
|
The control mode to set for the object. |
Sets the input mode flag for the object
TermIOS::setIFlag(softint
$val
= 0) returns nothing
Table 4.174. Arguments for TermIOS::setIFlag()
Argument | Description |
---|---|
|
The input mode to set for the object. |
Sets the output mode flag for the object
TermIOS::setOFlag(softint
$val
= 0) returns nothing
Table 4.175. Arguments for TermIOS::setOFlag()
Argument | Description |
---|---|
|
The output mode to set for the object. |
Returns the value of the control character corresponding to the argument passed.
TermIOS::getCC(softint
$offset
= 0) returns int
Table 4.176. Arguments for TermIOS::getCC()
Argument |
Description |
---|---|
| The control character to get from th object. |
Table 4.177. Return Values for TermIOS::getCC()
Return Type |
Description |
---|---|
The value of the given control character. |
Sets the control character corresponding to the first argument to the value of the second argument.
TermIOS::setCC(softint
$offset
= 0, softint $value
= 0) returns nothing
Table 4.178. Arguments for TermIOS::setCC()
Argument |
Description |
---|---|
|
The control character to set. |
|
The value to set |
Returns True
if the TermIOS object passed as an argument is equal to the current object; false if not. If the argument passed to this method is not a TermIOS object, an exception is raised
TermIOS::isEqual(TermIOS
$other
) returns bool
Table 4.179. Arguments for TermIOS::isEqual()
Argument |
Description |
---|---|
|
The object to compare to the current object. |
Table 4.180. Return Values for TermIOS::isEqual()
Return Type |
Description |
---|---|
The result of comparing the current object to the argument |
Table 4.181. Exceptions thrown by TermIOS::isEqual()
err |
desc |
---|---|
|
argument passed is not a TermIOS object |
Returns a hash giving the current terminal window size in hash keys rows
and columns
.
static TermIOS::getWindowSize() returns hash
$hash = TermIOS::getWindowSize()
Table 4.182. Return Values for TermIOS::getWindowSize()
Return Type | Description |
---|---|
Returns a hash giving the current terminal window size in hash keys |
The GetOpt class provides an easy way to process POSIX-style command-line options in Qore scripts/programs.
Table 4.183. GetOpt Method Overview
Method | Except? | Description |
---|---|---|
| Y | Creates the GetOpt object with the option hash passed. |
N | Destroys the object. | |
Y | Throws an exception; objects of this class cannot be copied. | |
| N | Parses the argument list passed and retuns a hash of the results; if there are any errors, they are returned in the |
| N | Parses the argument list passed and retuns a hash of the results; if there are any errors, an exception is thrown. |
Creates the GetOpt object and sets the option hash with the single required argument.
GetOpt::constructor(hash
$options
)
const program_options = ( "url" : "url,u=s", "xml" : "xml,x", "lxml" : "literal-xml,X", "verb" : "verbose,v", "help" : "help,h" ); my GetOpt $getopt(program_options);
Table 4.184. Arguments for GetOpt::constructor()
Argument | Description |
---|---|
| Each key defines the key value for the return hash if any arguments are given corresponding to the string value of the key. |
The string value of each hash follows the following pattern:
opts
[=|:type
[modifier
]]
Table 4.185. Option Hash Value String
Component | Description |
---|---|
| At least one short option and/or a long option name; if both are present, then they must be separated by a comma. The short option must be a single character. |
[=: | if "=" is used, then the option takes a mandatory argument, if ":" is used, then the argument is optional. Types are specified as follows: s=string, i=integer, f=float, d=date, b=boolean |
| @ specifies a list, + an additive value (sum; must be integer or float type) |
Table 4.186. Exceptions Thrown by GetOpt::constructor()
err | desc |
---|---|
| There was a syntax or format error in the option specification. |
Throws an exception; objects of this class cannot be copied.
Table 4.187. Exceptions Thrown by GetOpt::copy()
err | desc |
---|---|
| Objects of this class cannot be copied. |
Parses the list of parameters according to the option hash passed to the constructor. If a reference to a list is passed to this function, then all arguments parsed will be removed from the list, leaving only unparsed arguments (for example, file names).
If any errors are encountered, the return value hash will have a key "_ERRORS_"
giving a list of error messages pertaining to the options parsed.
See GetOpt::parse2() for a similar method that throws an exception instead of putting error information in the _ERRORS_
key of the hash value returned.
GetOpt::parse(reference
$list_ref
) returns hash
GetOpt::parse(list
$list
) returns hash
my hash $o = $getopt.parse(\$ARGV); if (exists $o."_ERRORS_") { stderr.printf("%s\n", $o."_ERRORS_"[0]); exit(1); }
Table 4.189. Return Values for GetOpt::parse()
Return Type | Description |
---|---|
A hash keyed by option names (as given in the hash to the GetOpt constructor), where each key's value is the value of the arguments passed in the list argument. The hash key |
Parses the list of parameters according to the option hash passed to the constructor. If a reference to a list is passed to this function, then all arguments parsed will be removed from the list, leaving only unparsed arguments (for example, file names).
If any errors are encountered, an appropriate exception will be thrown.
See GetOpt::parse() for a similar method that puts error information in the "_ERRORS_"
key of the hash value returned instead of throwing an exception.
GetOpt::parse2(reference
$list_ref
) returns hash
GetOpt::parse2(list
$list
) returns hash
try { my hash $o = $getopt.parse2(\$ARGV); } catch ($ex) { stderr.printf("%s\n", $ex.desc); exit(1); }
Table 4.191. Return Values for GetOpt::parse2()
Return Type | Description |
---|---|
A hash keyed by option names (as given in the hash to the GetOpt constructor), where each key's value is the value of the arguments passed in the list argument. If any errors are encountered processing the arguments, an appropriate exception will be thrown. |
Table 4.192. Exceptions Thrown by GetOpt::parse2()
err | desc |
---|---|
| The description varies according to the error encountered. |
Note: This class is not available with the PO_NO_NETWORK
parse option.
The FtpClient class allows Qore programs to communicate with FTP servers. The constructor takes an optional URL with the following format:
[(ftp|ftps)://][username[:password]@]hostname[:port]
If the URL is not set with the constructor, then the connection parameters must be set with the FtpClient::set*() methods. At the very minimum the hostname must be set. If any path name is given in the URL, it is ignored. See the following table for default URL parameters.
Table 4.193. FtpClient::constructor() Default URL Parameters
Field | Default Value |
---|---|
|
|
|
|
|
|
|
|
Once the URL (at least the hostname) has been set, the FtpClient::connect() method must be called to connect and login to the FTP server.
Objects of this class are capable of making encrypted FTPS connections according to RFC-4217. TLS/SSL encrypted control and data connection will be attempted if the protocol is set to 'ftps' or the FtpClient::setSecure() method is called before connecting.
Note that 'sftp', or FTP over ssh, is not supported with this class; FTPS is an extension of the FTP protocol to allow for secure connections; while 'sftp' is FTP over an encrypted ssh connection. For sftp and ssh support, use the ssh2
module.
When a data connection is required, by default the following modes are tried in series: EPSV (Extended Passive Mode), PASV (Passive Mode), and PORT (Port mode). If the FTP server does not support one of these methods, or network conditions do not allow a data connection of any of these types to be established, then an exception is thrown.
To manually control which modes are tried, see the FtpClient::setModeEPSV(), FtpClient::setModePASV(), and FtpClient::setModePORT() methods.
This class supports posting network events to a Queue, either events on the control or data channels or both can be monitored. See Event Handling for more information.
The events raised by this object are listed in the following table:
Table 4.194. FtpClient Events
Name | Value | Description |
---|---|---|
| Raised immediately before an FTP control message is sent. | |
| Raised when an FTP reply is received on the control channel. |
Table 4.195. FtpClient Method Overview
Method | Except? | Description |
---|---|---|
| Y | Creates object and optionally initializes URL |
N | Destroys the object. | |
Y | Throws an exception to prevent copying of objects this class. | |
| Y | Connects and logs in to FTP server |
| N | Disconnects from the FTP server. |
|
Y |
Make an FTPS connection to the server on the next connect if the argument is |
|
Y |
Make a non-encrypted connection to the server on the next connect. |
|
Y |
Make a non-encrypted data connection to the server on the next connect even if the control connection is secure. |
|
N |
Returns |
|
N |
Returns |
|
N |
Returns the name of the cipher for an encrypted connection or NOTHING if no encrypted connection has been established. |
|
N |
Returns the version string of the cipher for encrypted connections or NOTHING if no encrypted connection has been established. |
|
N |
Returns a string code giving the result of verifying the remote certificate or NOTHING if no encrypted connection has been established. |
|
N |
Sets the object to automatically try to negotiate the data connections in EPSV, PASV, and PORT modes, in this order. |
|
N |
Sets the object to only try to make data connections using EPSV (RFC-2428 extended passive) mode. |
|
N |
Sets the object to only try to make data connections using PASV (RFC-959 passive) mode. |
|
N |
Sets the object to only try to make data connections using PORT mode. |
| Y | Gets a list of files from the FTP server in the server's long format; returns NOTHING if the path cannot be found. |
| Y | Gets a list of file names from the FTP server; returns NOTHING if the path cannot be found. |
| Y | Returns the server-side current working directory. |
| Y | Changes the current working directory on the server. |
| Y | Gets a file from the FTP server and stores it on the local filesystem; if any errors occur, an exception is thrown.. |
| Y | Gets a file from the FTP server and returns it as a binary value. |
| Y | Gets a file from the FTP server and returns it as a string. |
| Y | Transfers a file to the FTP server; if any errors occur, an exception is thrown. |
| Y | Deletes a file from the FTP server |
| N | Sets the user name to use |
| N | Sets the password to use |
| N | Sets the hostname to connect to |
| Y | Sets the port to connect to; throws an exception if the port is <= 0. |
| Y | Sets the URL |
| N | Gets the current user name or NOTHING if not yet set. |
| N | Gets the current password or NOTHING if not yet set. |
| N | Gets the current hostname or NOTHING if not yet set. |
| N | Gets the current port number. |
| N | Gets the current FTP URL. |
| N | Sets a Queue object to receive socket and FtpClient events on both the data and control connections. Calling with no argument clears the queue. |
| N | Sets a Queue object to receive socket and FtpClient events on the data connection. Calling with no argument clears the queue. |
| N | Sets a Queue object to receive socket and FtpClient events on the control connection. Calling with no argument clears the queue. |
Creates the FtpClient object. It accepts one optional argument that will set the URL for the FTP connection; the path is ignored in the URL, however the username, password, hostname and port are respected; additionally if the protocol is "ftps", the client will attempt to establish a secure connection to the server according to RFC-4217 when the first connection is established.
A call to FtpClient::connect() must be made explicitly before any actions requiring a connection to the server are made; connections are not made implicitly by this class.
FtpClient::constructor(string
$url
)
my FtpClient $ftp("ftp://user:pass@hostname");
Table 4.196. Arguments for FtpClient::constructor()
Argument | Description |
---|---|
| The URL of the server to connect to; must have at least the hostname to connect to. |
Table 4.197. Exceptions Thrown by FtpClient::constructor()
err | desc |
---|---|
| Only "ftp" or "ftps" are allowed as the protocol in the URL. |
| No hostname given in the URL. |
Destroys the object.
delete $ftp;
Throws an exception; objects of this class cannot be copied.
Table 4.198. Exceptions Thrown by FtpClient::copy()
err | desc |
---|---|
| Objects of this class cannot be copied. |
Connects to the FTP server and attempts a login; if any errors occur, an exception is thrown.
FtpClient::connect() returns nothing
$ftp.connect(); # connects to the URL set in the constructor
EVENT_CONNECTING, EVENT_CONNECTED,EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED, EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT
Table 4.199. Exceptions Thrown by FtpClient::connect()
err | desc |
---|---|
| Invalid response received from FTP server. |
| Cannot establish connection on data port, no hostname set, FTP server reported an error, etc. |
| Login denied by FTP server. |
Disconnects from an FTP server.
FtpClient::disconnect() returns nothing
$ftp.disconnect();
Make an FTPS connection to the server on the next connect. This method can only be called before a connection is established; if called when a connection has already been established, an exception will be thrown.
FtpClient::setSecure(softbool
$secure
= True) returns nothing
$ftp.setSecure();
Table 4.200. Arguments for FtpClient::setSecure()
Argument |
Description |
---|---|
|
if |
Table 4.201. Exceptions thrown by FtpClient::setSecure()
err |
desc |
---|---|
|
cannot be called while a control connection has already been established. |
Make a non-encrypted connection to the server on the next connect.
FtpClient::setInsecure() returns nothing
$ftp.setInsecure();
Table 4.202. Exceptions thrown by FtpClient::setInsecure()
err |
desc |
---|---|
|
cannot be called while a control connection has already been established. |
Make a non-encrypted data connection to the server on the next connect even if the control connection is secure.
FtpClient::setInsecureData() returns nothing
$ftp.setInsecureData();
Table 4.203. Exceptions thrown by FtpClient::setInsecureData()
err |
desc |
---|---|
|
cannot be called while a control connection has already been established. |
Returns True
if the control connection is a secure TLS/SSL connection.
FtpClient::isSecure() returns bool
my bool $b = $ftp.isSecure();
Table 4.204. Return Values for FtpClient::isSecure()
Return Type |
Description |
---|---|
True if the control connection is encrypted, |
Returns True
if the data connections are secure TLS/SSL connections.
FtpClient::isDataSecure() returns bool
my bool $b = $ftp.isDataSecure();
Table 4.205. Return Values for FtpClient::isDataSecure()
Return Type |
Description |
---|---|
True if data connections are encrypted, |
Returns the name of the cipher for an encrypted connection.
FtpClient::getSSLCipherName() returns any
my any $str = $ftp.getSSLCipherName();
Returns the version string of the cipher for encrypted connections.
FtpClient::getSSLCipherVersion() returns any
my any $str = $ftp.getSSLCipherVersion();
Returns a string code giving the result of verifying the remote certificate for secure (FTPS) connections. Return value are the keys described in the X509_VerificationReasons hash constant. This hash can also be used to generate a textual description of the verification result.
FtpClient::verifyPeerCertificate() returns any
my any $str = $ftp.verifyPeerCertificate();
Sets the object to automatically try to negotiate the data connections in EPSV, PASV, and PORT modes, in this order.
FtpClient::setModeAuto() returns nothing
$ftp.setModeAuto();
Sets the object to only try to make data connections using EPSV (RFC-2428 extended passive) mode.
FtpClient::setModeEPSV() returns nothing
$ftp.setModeEPSV();
Sets the object to only try to make data connections using PASV (RFC-959 passive) mode.
FtpClient::setModePASV() returns nothing
$ftp.setModePASV();
Sets the object to only try to make data connections using PORT mode.
FtpClient::setModePORT() returns nothing
$ftp.setModePORT();
Gets a string giving the list of files from the FTP server in the server's long format in the current working directory; returns NOTHING if the path cannot be found.
FtpClient::list() returns any
FtpClient::list(string
$path
) returns any
my any $str = $ftp.list();
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT
Table 4.209. Arguments for FtpClient::list()
Argument | Description |
---|---|
| The optional path or argument (filter) to list. |
Table 4.211. Exceptions Thrown by FtpClient::list()
err | desc |
---|---|
| Incomplete message received on control port. |
| Not connected to FTP server (call FtpClient::connect() first). |
| FTP server returned an error in response to the LIST command. |
Gets a list of file names in the current working directory from the FTP server.
FtpClient::nlst() returns any
FtpClient::nlst(string
$path
) returns any
my any $str = $ftp.nlst();
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT
Table 4.212. Arguments for FtpClient::nlst()
Argument | Description |
---|---|
| The optional path or argument (filter) to list. |
Table 4.214. Exceptions Thrown by FtpClient::nlst()
err | desc |
---|---|
| Incomplete message received on control port. |
| Not connected to FTP server (call FtpClient::connect() first). |
| FTP server returned an error in response to the NSLT command. |
Returns the server-side current working directory.
FtpClient::pwd() returns string
my string $str = $ftp.pwd();
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT
Table 4.215. Return Values for FtpClient::pwd()
Return Type | Description |
---|---|
The server-side current working directory. |
Table 4.216. Exceptions Thrown by FtpClient::pwd()
err | desc |
---|---|
| Incomplete message received on control port. |
| Not connected to FTP server (call FtpClient::connect() first). |
| FTP server returned an error to the PWD command. |
Changes the current working directory on the server.
FtpClient::cwd(string
$dir
) returns nothing
$ftp.cwd("/pub/gnu");
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT
Table 4.217. Arguments for FtpClient::cwd()
Argument | Description |
---|---|
| The directory to change to. |
Table 4.218. Exceptions Thrown by FtpClient::cwd()
err | desc |
---|---|
| Incomplete message received on control port. |
| Not connected to FTP server (call FtpClient::connect() first). |
| FTP server returned an error to the CWD command. |
| Missing argument to the method. |
Gets a file from the FTP server and stores it on the local system. If any errors occur, an exception is thrown.
This method accesses the filesystem, so it is not available if PO_NO_FILESYSTEM
is set.
FtpClient::get(string
$remote_file
) returns nothing
FtpClient::get(string
$remote_file
, string $local_file
) returns nothing
$ftp.get("file.txt", "/tmp/file-1.txt");
Not available with PO_NO_FILESYSTEM
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT
Table 4.220. Exceptions Thrown by FtpClient::get()
err | desc |
---|---|
| Incomplete message received on control port. |
| Not connected to FTP server (call FtpClient::connect() first). |
| Could not create the local file. |
| There was an error retrieving the file. |
| Missing argument to the method. |
Gets a file from the FTP server and returns the file's contents as a binary value. For a similar function returning the file's contents as a string, see FtpClient::getAsString(); for a function that will get a remote file and save it on the local filesystem, see FtpClient::get().
FtpClient::getAsBinary(string
$remote_file
) returns binary
my binary $b = $ftp.getAsBinary("file.bin");
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT
Table 4.221. Arguments for FtpClient::getAsBinary()
Argument | Description |
---|---|
| The path on the server to the file to get. |
Table 4.222. Return Values for FtpClient::getAsBinary()
Return Type | Description |
---|---|
The file retrieved; if any errors occur an exception is raised. |
Table 4.223. Exceptions Thrown by FtpClient::getAsBinary()
err | desc |
---|---|
| Incomplete message received on control port. |
| Not connected to FTP server (call FtpClient::connect() first). |
| Could not create the local file. |
| There was an error retrieving the file. |
| Missing argument to the method. |
Gets a file from the FTP server and returns the file's contents as a string. For a similar function returning the file's contents as a binary, see FtpClient::getAsBinary(); for a function that will get a remote file and save it on the local filesystem, see FtpClient::get().
FtpClient::getAsString(string
$remote_file
) returns string
my string $str = $ftp.getAsString("file.txt");
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT
Table 4.224. Arguments for FtpClient::getAsString()
Argument | Description |
---|---|
| The path on the server to the file to get. |
Table 4.225. Return Values for FtpClient::getAsString()
Return Type | Description |
---|---|
The file retrieved; if any errors occur an exception is raised. |
Table 4.226. Exceptions Thrown by FtpClient::getAsString()
err | desc |
---|---|
| Incomplete message received on control port. |
| Not connected to FTP server (call FtpClient::connect() first). |
| Could not create the local file. |
| There was an error retrieving the file. |
| Missing argument to the method. |
Transfers a file to the FTP server. If any errors occur, an exception is thrown.
This method accesses the filesystem, so it is not available if PO_NO_FILESYSTEM
is set.
FtpClient::put(string
$local_file
) returns int
FtpClient::put(string
$local_file
, string $remote_file
) returns int
$ftp.put("/tmp/file-1.txt", "file.txt");
Not available with PO_NO_FILESYSTEM
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT
Table 4.228. Exceptions Thrown by FtpClient::put()
err | desc |
---|---|
| Incomplete message received on control port. |
| Not connected to FTP server (call FtpClient::connect() first). |
| Could not open local file for reading. |
| Could not determine file size of local file (stat() failed). |
| An error occurred while sending the file. |
| Missing argument to the method. |
Deletes a file on the FTP server; if any errors occur, an exception is thrown.
FtpClient::del(string
$remote_file
) returns nothing
$ftp.del("file-2.txt");
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT
Table 4.229. Arguments for FtpClient::del()
Argument | Description |
---|---|
| The path on the server to the file to delete. |
Table 4.230. Return Values for FtpClient::del()
Return Type | Description |
---|---|
Always returns 0, on errors exceptions are raised. |
Table 4.231. Exceptions Thrown by FtpClient::del()
err | desc |
---|---|
| Incomplete message received on control port. |
| Not connected to FTP server (call FtpClient::connect() first). |
| FTP server returned an error to the DELE command. |
| Missing argument to the method. |
Sets the username for logging in to the FTP server.
FtpClient::setUserName(string
$user
) returns nothing
$ftp.setUserName("ftp");
Table 4.232. Arguments for FtpClient::setUserName()
Argument | Description |
---|---|
| The username to use when logging in to the FTP server. |
Table 4.233. Exceptions Thrown by FtpClient::setUserName()
err | desc |
---|---|
| Missing argument to the method. |
Sets the login password for the FTP server to connect to.
FtpClient::setPassword(string
$pass
) returns nothing
$ftp.setPassword("ftp");
Table 4.234. Arguments for FtpClient::setPassword()
Argument | Description |
---|---|
| The password to use when logging in to the FTP server. |
Table 4.235. Exceptions Thrown by FtpClient::setPassword()
err | desc |
---|---|
| Missing argument to the method. |
Sets the hostname value for the FTP server to connect to.
FtpClient::setHostName(string
$host
) returns nothing
$ftp.setHostName("hostname");
Table 4.236. Arguments for FtpClient::setHostName()
Argument | Description |
---|---|
| The hostname to use when connecting to the FTP server. |
Table 4.237. Exceptions Thrown by FtpClient::setHostName()
err | desc |
---|---|
| Missing argument to the method. |
Sets the control port value (default is 21).
FtpClient::setPort(softint
$port
) returns nothing
$ftp.setPort(21);
Table 4.238. Arguments for FtpClient::setPort()
Argument | Description |
---|---|
| The port to use when connecting to the FTP server. |
Table 4.239. Exceptions Thrown by FtpClient::setPort()
err | desc |
---|---|
| Missing argument to the method. |
Sets the connection and login parameters based on the URL passed as an argument.
FtpClient::setURL(string
$url
) returns nothing
$ftp.setURL("ftps://user:pass@host");
Table 4.240. Arguments for FtpClient::setURL()
Argument | Description |
---|---|
| The URL to use to set connection and login parameters for the FTP server. |
Table 4.241. Exceptions Thrown by FtpClient::setURL()
err | desc |
---|---|
| Only "ftp" is allowed as the protocol in the URL. |
| No hostname given in the URL. |
| Missing argument to the method. |
Retrieves the current username.
FtpClient::getUserName() returns any
my any $user = $ftp.getUserName();
Retrieves the current login password value for this object.
FtpClient::getPassword() returns any
my any $pass = $ftp.getPassword();
Retrieves the current hostname value for this object.
FtpClient::getHostName() returns any
my any $host = $ftp.getHostName();
Retrieves the current connection port value for this object.
FtpClient::getPort() returns int
my int $port = $ftp.getPort();
Table 4.245. Return Values for FtpClient::getPort()
Return Type | Description |
---|---|
The current connection port value. |
Retrieves the current connection URL string for this object.
FtpClient::getURL() returns string
my string $url = $ftp.getURL();
Sets a Queue object to receive socket and FtpClient events on both the data and control connections.
To remove the event queue and stop monitoring socket events, pass NOTHING
to the method. See Event Handling for more information.
To control monitoring of network events on just the data connection or just the control connection, use FtpClient::setDataEventQueue or FtpClient::setControlEventQueue respectively
FtpClient::setEventQueue() returns nothing
FtpClient::setEventQueue(Queue
$queue
) returns nothing
$ftp.setEventQueue($queue);
Sets a Queue object to receive socket and FtpClient events on the data connection when retrieving data from an FTP server.
To remove the event queue and stop monitoring network events, pass NOTHING
to the method. See Event Handling for more information.
To control monitoring of network events on just the control connection or on both connections with the same queue, use FtpClient::setControlEventQueue or FtpClient::setEventQueue respectively.
FtpClient::setDataEventQueue() returns nothing
FtpClient::setDataEventQueue(Queue
$queue
) returns nothing
$ftp.setDataEventQueue($queue);
Sets a Queue object to receive socket and FtpClient events on both the control connection.
To remove the event queue and stop monitoring network events, pass NOTHING
to the method. See Event Handling for more information.
To control monitoring of network events on just the data connection or for both data and control connections simultaneously, use FtpClient::setDataEventQueue or FtpClient::setEventQueue respectively
FtpClient::setControlEventQueue() returns nothing
FtpClient::setControlEventQueue(Queue
$queue
) returns nothing
$ftp.setControlEventQueue($queue);
Program objects allow Qore programs to support subprograms with restricted capabilities, for example, to support user-defined logic for application actions.
Parsing in Qore happens in two steps; first all code is parsed to pending data structures, and then in the second stage, all references are resolved, and, if there are no errors, then all changes are committed to the Program object. Note that all parse actions (Program::parse(), Program::parsePending(), Program::parseCommit(), and Program::parseRollback()) are atomic; there is a thread lock on each Program object to ensure atomicity, and if any parse errors occur in any stage of parsing, any pending changes to the Program object are automatically rolled back. However parse actions that affect only one stage of the two stages of parsing (Program::parsePending(), Program::parseCommit() and Program::parseRollback()) are atomic within themselves, but not between calls, so one thread may inadvertently commit changes to a Program object if two or more threads are trying to perform transaction-safe two-stage parsing on a Program object without explicit user locking.
The constants in the following table can be used to limit the capabilities of a Program object. These options should be binary-OR'ed together and passed to the Program object's constructor. Also see Command-Line Parsing for equivalent command-line options, and Parse Directives for equivalent parse directives.
Note that a program can provide controlled access to functionality otherwise restricted by parse options by exporting a custom API into the child program object using either the Program::importFunction() or Program::importGlobalVariable() method. This is possible because code (functions or object methods) imported into and called from a subprogram will run in the parent's space and therefore with the parent's capabilities.
The following constants are all in the Qore
namespace.
Table 4.250. Parse Options
Constant | Details | Description |
---|---|---|
| Disallows the use of global variables. | |
| no parse options | This option is the empty option, meaning no options are set. |
| Disallows subroutine (function) definitions. | |
| Disallows any thread operations (the background operator and the thread_exit statement, for example) and the use of thread-relevant classes and functions (equivalent to PO_NO_THREAD_CLASSES | PO_NO_THREAD_CONTROL). | |
| Disallows access to any thread classes. | |
| Disallows access to any thread-control functions and thread-relevant statements and operators (for example the background operator and the thread_exit statement). | |
| Disallows top level code. | |
| Disallows class definitions. | |
| Disallows new namespace definitions. | |
| Disallows constant definitions. | |
| Disallows use of the new operator. | |
| n/a | Prohibits system classes from being imported into the new Program object. |
| n/a | Prohibits user classes from being imported into the new Program object. |
| Allows child program objects to have fewer parse restrictions than the parent object. | |
| Disallows access to functionality that provides information about the computing environment. | |
| Disallows any access to external processes (with system(), backquote(), exec(), etc). | |
| Requires global variables to be declared with our before use. | |
| Disallows access to functions that would affect the current process (exit(), exec(), fork(), etc). | |
| Prohibits the warning mask from being changed. | |
| Disallows access to network functions. | |
| Disallows access to the filesystem. | |
| Disallows changes to the warning mask. | |
| Disallows access to database functionality. | |
| Disallows access to functionality that draws graphics to the display. | |
| Disallows access to reading from and/or writing to the terminal. | |
| Disallows access to functionality that provides information about threading. | |
| Disallows access to functionality that can change locale parameters. | |
| Requires all function and method parameters and return types to have type declarations. Variables and object members are not required to have type declarations. | |
| Requires all function and method parameters, return types, variables, and object members to have type declarations. Additionally, this option implies | |
| Prohibits access to builtin functions and methods flagged with |
Table 4.251. Program Method Overview
Method | Except? | Description |
---|---|---|
| N | Creates the program object and optionally sets program capabilities (parse options) |
N | Destroys the object. Blocks until all threads have terminated. | |
Y | Throws an exception to prevent objects of this class from being copied. | |
| Y | Calls a function in the program object and returns the return value. |
| Y | Calls a function in the program object with the arguments given as a list |
| Y | Removes the given parse options to the current parse option mask. |
| N | Checks if a user function exists in the program object |
| N | Returns a the value of the global variable identified by the first string argument. |
| N | Returns a code of parse options set in the object. |
| N | Returns the current script directory as a string or NOTHING if not set. |
| N | Returns the current script name as a string or NOTHING if not set. |
| N | Returns the current script directory and filename as a string or NOTHING if not set. |
| N | Returns the default local time zone for the object. |
| N | Returns a list of strings of all user functions defined in the program object. |
| Y | Imports a user function into the program object's space; any calls to the function will run in the parent's space. |
| Y | Imports a global variable into the Program object's space. If the variable is an object, then any methods called will run in the parent's space. |
| N | Locks parse options so that they cannot be changed. |
| Y | Performs a complete parse and commit of the string passed; if a warning mask is given and warnings are raised, then the method returns an exception hash. |
| Y | Commits all pending changes to the program object; if a warning mask is given and warnings are raised, then the method returns an exception hash. |
| Y | Performs a 1st stage parse of the string passed; if a warning mask is given and warnings are raised, then the method returns an exception hash. |
| N | Rolls back all pending changes to the program object |
| Y | Runs the top-level code of the program object |
| Y | Adds the given parse options to the current parse option mask. |
| N | Sets (or clears) the script path (directory and filename) for the object. |
| N | Sets the default local time zone for the object. |
| Y | Sets the default local time zone for the object from a path to a zoneinfo time zone region file. |
| N | Sets the default local time zone for the object from a UTC offset in seconds east of UTC; for zones west of UTC, use negative numbers. |
Creates the Program object. It accepts one optional argument that will set the program capabilities for the program object.
Program::constructor(softint
$options
= PO_DEFAULT)
my Program $pgm();
Table 4.252. Arguments for Program::constructor()
Argument | Description |
---|---|
| A binary OR'ed product of parse options. |
Destroys the object. If any threads are running in the program, the destructor will block until the threads terminate.
delete $pgm;
Throws an exception; objects of this class cannot be copied.
Table 4.253. Exceptions Thrown by Program::copy()
err | desc |
---|---|
| Objects of this class cannot be copied. |
Calls a function in the program object and returns the return value. The function runs with the permissions of the Program object containing the function.
Program::callFunction(string
$func
, ...) returns any
$result = $pgm.callFunction("func_name", $arg1, $arg2);
Table 4.254. Arguments for Program::callFunction()
Argument | Description |
---|---|
| The name of the function to call. |
| The remaining arguments passed to the method are passed to the function to be called. |
Table 4.255. Return Values for Program::callFunction()
Return Type | Description |
---|---|
Depends on the function being called. |
Table 4.256. Exceptions Thrown by Program::callFunction()
err | desc |
---|---|
| Parse options do not allow this builtin function to be called. |
| The function does not exist. |
Calls a function in the program object and returns the return value, using the second argument as the argument list for the function call. The function runs with the permissions of the Program object containing the function.
Program::callFunctionArgs(string
$func
, list $args
) returns any
Program::callFunctionArgs(string
$func
, any $args
) returns any
$result = $pgm.callFunctionArgs("func_name", $arg_list);
Table 4.258. Return Values for Program::callFunctionArgs()
Return Type | Description |
---|---|
Depends on the function being called. |
Table 4.259. Exceptions Thrown by Program::callFunctionArgs()
err | desc |
---|---|
| Parse options do not allow this builtin function to be called. |
| The function does not exist. |
Disables parse options in the parse option mask for the Program object. An exception is thrown if parse options have been locked (for example with Program::lockOptions()). For a reciprocal method that sets parse options, see Program::setParseOptions().
Program::disableParseOptions(int
$options
= PO_DEFAULT) returns nothing
# allow threading and GUI operations $pgm.disableParseOptions(PO_NO_THREADS | PO_NO_GUI);
Table 4.260. Arguments for Program::disableParseOptions()
Argument | Description |
---|---|
| A single parse option or binary-or combination of parse options to disable in the parse option mask for the current object. |
Table 4.261. Exceptions Thrown by Program::disableParseOptions()
err | desc |
---|---|
| Parse options have been locked and cannot be changed. |
Checks if a user function exists in the program object.
Program::existsFunction(function_name
)
Program::existsFunction(string
$func
) returns bool
Program::existsFunction() returns nothing (RT_NOOP)
Table 4.262. Arguments for Program::existsFunction()
Argument | Description |
---|---|
| The name of the function to check. |
Table 4.263. Return Values for Program::existsFunction()
Return Type | Description |
---|---|
Returns |
Returns the value of the global variable identified by the first string argument giving the name of the variable (without any leading "$" symbol. An lvalue reference can be passed as the second argument in order to determine if the global variable exists (because this method could return NOTHING when the variable exists as well as when it does not).
Program::getGlobalVariable(string
$name
) returns any
Program::getGlobalVariable(string
$name
, reference $found
) returns any
$val = $pgm.getGlobalVariable("error_count", \$exists);
Table 4.264. Arguments for Program::getGlobalVariable()
Argument | Description |
---|---|
| The string name of the variable to find, not including the leading "$" character. |
| If a reference is passed in this position, it will contain a boolean value after the method exits: if this value is |
This method does not throw any exceptions.
Returns the current binary-or parse option mask for the Program object.
Program::getParseOptions() returns int
$mask = $pgm.getParseOptions();
Table 4.266. Return Values for Program::getParseOptions()
Return Type | Description |
---|---|
A mask of all parse options set (combined with binary or) for the current object. |
Gets the script directory set with Program::setScriptPath(). This is the same value that will be returned in the Qore program code with the get_script_dir() function if called from within the Program. The value returned should normally include the trailing '/' character.
Program::getScriptDir() returns any
my any $dir = $pgm.getScriptDir();
This method does not throw any exceptions.
Gets the script filename set with Program::setScriptPath(). This is the same value that will be returned in the Qore program code with the get_script_path() function if called from within the Program.
Program::getScriptName() returns any
my any $name = $pgm.getScriptName();
This method does not throw any exceptions.
Gets the script directory and filename set with Program::setScriptPath(). This is the same value that will be returned in the Qore program code with the get_script_path() function if called from within the Program.
Program::getScriptPath() returns any
my any $path = $pgm.getScriptPath();
This method does not throw any exceptions.
Returns the default local time zone for the object.
See also TimeZone::get()
Program::getTimeZone() returns TimeZone
my TimeZone $zone = $pgm.getTimeZone();
Table 4.270. Return Values for Program::getTimeZone()
Return Type | Description |
---|---|
Returns the default local time zone for the object. |
This method does not throw any exceptions.
Returns a list of all user functions defined in the Program object.
Program::getUserFunctionList() returns list
my list $l = $pgm.getUserFunctionList();
Table 4.271. Return Values for Program::getUserFunctionList()
Return Type | Description |
---|---|
A list of strings giving the names of all functions implemented in the program object. |
Imports a user function into the program object's space; any calls to the imported function will run in the parent's space. This allows a user-defined API with greater capabilities than the embedded Program object to be imported into the embedded code.
Program::importFunction(string
$name
) returns nothing
Program::importFunction(string
$name
, string $new_name
) returns nothing
$pgm.importFunction("function");
Table 4.273. Exceptions Thrown by Program::importFunction()
err | desc |
---|---|
| No function name was passed to the method. |
| Cannot import a function into the same Program object. |
| The function does not exist. |
Imports a global variable into the program object's space. If the variable is an object, then any methods called from the subprogram will run in the parent's space.
Program::importGlobalVariable(string
$name
, bool $readonly
= False) returns nothing
$pgm.importGlobalVariable("var");
Table 4.275. Exceptions Thrown by Program::importGlobalVariable()
err | desc |
---|---|
| No variable name was passed to the method. |
| The global variable does not exist. |
Locks parse options so they cannot be changed.
Program::lockOptions() returns nothing
$pgm.lockOptions();
This method does not throw any exceptions.
Parses the string argument and adds the code to the program object.
If a warning mask is given and masked warnings are raised during parsing, this method will return a hash with warning information.
Program::parse(string
$code
, string $label
) returns nothing
Program::parse(string
$code
, string $label
, softint $warn_mask
) returns any
$pgm.parse($code, "label");
Table 4.276. Arguments for Program::parse()
Argument | Description |
---|---|
| The code to parse. |
| A label identifying the code. |
| An optional warning mask of bitwise-ORed warning values; if this option is non-zero and any warnings are raised during parsing, then a hash is returned of warning information. |
Table 4.277. Return Values for Program::parse()
Return Type | Description |
---|---|
If a warning mask is set and any masked warnings are raised during parsing, then an exception hash is returned of warning information (multiple warnings are linked in the hash through the "next" key, as with chained exceptions). |
Table 4.278. Exceptions Thrown by Program::parse()
err | desc |
---|---|
| An error occurred parsing the text. |
Commits and pending code processed with Program::parsePending() to the Program object and resolves all outstanding references in the pending code. An exception in this method causes all pending code to be rolled back immediately.
If a warning mask is given and masked warnings are raised during parsing, this method will return a hash with warning information.
Program::parseCommit() returns nothing
Program::parseCommit(softint
$warn_mask
) returns any
$pgm.parseCommit();
Table 4.279. Arguments for Program::parseCommit()
Argument | Description |
---|---|
| An optional warning mask of bitwise-ORed warning values; if this option is non-zero and any warnings are raised during parsing, then a hash is returned of warning information. |
Table 4.280. Return Values for Program::parseCommit()
Return Type | Description |
---|---|
If a warning mask is set and any masked warnings are raised during parsing, then an exception hash is returned of warning information (multiple warnings are linked in the hash through the "next" key, as with chained exceptions). |
Table 4.281. Exceptions Thrown by Program::parseCommit()
err | desc |
---|---|
| An error occurred parsing the text. |
Parses the text passed to pending lists in the Program object; does not resolve all references or commit the code to the Program object. References are resolved in the Program::parseCommit() method. If an exception occurs in this method, all pending code is backed out, not just code parsed by this method.
If a warning mask is given and masked warnings are raised during parsing, this method will return a hash with warning information.
Program::parsePending(string
$code
, string $label
) returns nothing
Program::parsePending(string
$code
, string $label
, softint $warn_mask
) returns any
$pgm.parsePending($code, "label");
Table 4.282. Arguments for Program::parsePending()
Argument | Description |
---|---|
| The code to parse. |
| A label identifying the code. |
| An optional warning mask of bitwise-ORed warning values; if this option is non-zero and any warnings are raised during parsing, then a hash is returned of warning information. |
Table 4.283. Return Values for Program::parsePending()
Return Type | Description |
---|---|
If a warning mask is set and any masked warnings are raised during parsing, then an exception hash is returned of warning information (multiple warnings are linked in the hash through the "next" key, as with chained exceptions). |
Table 4.284. Exceptions Thrown by Program::parsePending()
err | desc |
---|---|
| An error occurred parsing the text. |
Rolls back any pending code processed with Program::parsePending() that has not yet been committed to the Program object with Program::parseCommit()
Program::parseRollback() returns nothing
$pgm.parseRollback();
Runs the program and optionally returns a value if the top-level code exits with a return statement.
Program::run() returns any
$pgm.run();
Table 4.285. Return Values for Program::run()
Return Type | Description |
---|---|
Depends on the program; any return statement at the top level of the program will return a value to this method. |
Sets parse options in the parse option mask for the Program object. An exception is thrown if parse options have been locked (for example with Program::lockOptions()). For a reciprocal method that disables parse options, see Program::disableParseOptions().
Program::setParseOptions(int
$options
= PO_DEFAULT) returns nothing
# disallow threading and GUI operations $pgm.setParseOptions(PO_NO_THREADS | PO_NO_GUI);
Table 4.286. Arguments for Program::setParseOptions()
Argument | Description |
---|---|
| A single parse option or binary-or combination of parse options to set in the parse option mask for the current object. |
Table 4.287. Exceptions Thrown by Program::setParseOptions()
err | desc |
---|---|
| Parse options have been locked and cannot be changed. |
Sets the script path (directory and filename) for later retrieval with Program::getScriptPath(), Program::getScriptDir(), or Program::getScriptName() calls, or from code within the Program object with the get_script_path(), get_script_dir(), or get_script_name() functions.
Program::setScriptPath(string
$path
) returns nothing
Program::setScriptPath() returns nothing
$pgm.setScriptPath("/users/test/test.q");
Table 4.288. Arguments for Program::setScriptPath()
Argument | Description |
---|---|
| The path (directory and filename) for the current script. If the directory component is missing, then "./" is assumed. |
This method does not throw any exceptions.
Sets the default local time zone for the object.
See also TimeZone::set().
Program::setTimeZone(TimeZone
$zone
) returns nothing
$pgm.setTimeZone($zone);
Table 4.289. Arguments for Program::setTimeZone()
Argument | Description |
---|---|
| The time zone to set as the local time zone for the Program object. |
This method does not throw any exceptions.
Sets the default local time zone for the object from a path to a zoneinfo time zone region file; if there are errors reading or parsing the file, an exception is thrown.
See also TimeZone::setRegion().
Program::setTimeZoneRegion(string
$region
) returns nothing
$pgm.setTimeZoneRegion("Europe/Prague");
Table 4.290. Arguments for Program::setTimeZoneRegion()
Argument | Description |
---|---|
| The path to the zoneinfo file for the time zone region to set as the local time zone for the Program object. |
Table 4.291. Exceptions Thrown by Program::setTimeZoneRegion()
err | desc |
---|---|
| Unable to read zoneinfo file; invalid file magic; error parsing zoneinfo file, etc |
Sets the default time zone for the Program object based on the number of seconds east of UTC; for zones west of UTC, use negative numbers.
Time zones set with this method cannot have any daylight savings time information; to set a zone with daylight savings time information, use Program::setTimeZoneRegion() instead.
See also TimeZone::setUTCOffset().
Program::setTimeZoneUTCOffset(softint
$secs_east
) returns nothing
The following examples are all equivalent, setting the time zone to +02 UTC:
$pgm.setTimeZoneUTCOffset(7200);
$pgm.setTimeZoneUTCOffset(2h);
$pgm.setTimeZoneUTCOffset(PT2H);
Table 4.292. Arguments for Program::setTimeZone()
Argument | Description |
---|---|
| The number of seconds east of UTC; for zones west of UTC, use negative numbers |
This method does not throw any exceptions.
Note: This class is not available with the PO_NO_NETWORK
parse option.
Socket objects allow Qore programs safe access to network sockets. Non-blocking socket I/O can be performed by appending a timeout value in milliseconds to all Socket::recv*() methods, or by using the Socket::isDataAvailable() method with a timeout value in milliseconds (1000 ms = 1 second). Note that as with all Qore functions and methods accepting a timeout value, relative date/time values can be given instead of integers to make the source more readable, for example:
my $rc = $socket.isDataAvailable(1250ms); # times out in 1.25 seconds
Socket objects can automatically convert character encodings if desired when sending string data with Socket::send(). Use the Socket::setCharset() method to set the character encoding for the socket. If a character encoding is set, and string data is read with the Socket::recv() method, then it will be tagged with the encoding of the socket as well.
Client applications should call Socket::connect() to connect to a remote port or a UNIX domain socket (socket file on the local server). However, if the remote end is expecting a TLS/SSL connection, use Socket::connectSSL() instead.
Server applications should call Socket::bind(), Socket::listen(), and Socket::accept() in this order to accept incoming connections. Normally a new thread should be started after the Socket::accept() call to handle the new connection in a separate thread (Socket::accept() returns a new Socket object for the accepted connection).
To support TLS/SSL server connections, first set the certificate and private key with the Socket::setCertificate() and Socket::setPrivateKey() methods (see the SSLCertificate Class and the SSLPrivateKey Class for more information on the parameters required for these methods). Then Socket::acceptSSL() should be called after the socket is in a listening state to accept client connections and negotiate a TLS/SSL connection.
This class supports posting events to a Queue. See Event Handling for more information.
The events raised by this object are listed in the following table:
Table 4.293. Socket Events
Name | Description |
---|---|
Raised when a network packet is received. | |
Raised when a network packet is sent. | |
Raised when a socket is closed. | |
Raised when the object being monitored is deleted. | |
Raised when a hostname lookup is attempted. | |
Raised when a hostname lookup is resolved. | |
Raised when an HTTP message is sent. | |
Raised when an HTTP message is received. | |
Raised right before a socket connection attempt is made. | |
Raised when the socket connection has been established. | |
Raised when socket SSL negotiation starts. | |
Raised when SSL communication has been negotiated and established. |
Table 4.294. Socket Method Overview
Method | Except? | Description |
---|---|---|
N | Creates the socket object | |
N | Closes the socket if it's open and destroys the object. | |
N | Creates a new Socket object, not based on the parent. | |
| Y | Connects to a remote port (if the string has a format "host:port") or UNIX domain socket file with an optional timeout value with a millisecond resolution. |
| Y | Connects to the given host and port with an optional timeout value with a millisecond resolution. |
| Y | Connects to the UNIX domain socket file. |
|
Y |
Connects to a remote socket and attempts to establish a TLS/SSL connection; accepts an optional timeout value with a millisecond resolution. |
| Y | Connects to the given host and port and attempts to establish a TLS/SSL connection; accepts an optional timeout value with a millisecond resolution. |
| Y | Connects to the UNIX domain socket file and attempts to establish a TLS/SSL connection. |
| N | Binds the socket to a port, interface and port (if the |
| Y | Accepts connections on a listening socket. |
|
Y |
Accepts a remote connection and attempts to negotiate a TLS/SSL connection. |
|
Y |
Shuts down the SSL connection on a secure connection. |
| Y | Listens for connections on the socket; sets the socket in a listening state. |
| N | Returns |
| N | Returns |
| Y | Sends string or binary data over the socket; string data is converted to the socket's encoding if necessary. |
| Y | Sends string or binary data over the socket; string data is not converted to the socket's encoding, but sent exactly as-is. |
| Y | Sends a 1-byte integer over the socket. |
| Y | Sends a 2-byte (16-bit) integer in big-endian format (network byte order) over the socket. |
| Y | Sends a 4-byte (32-bit) integer in big-endian format (network byte order) over the socket. |
| Y | Sends an 8-byte (64-bit) integer in big-endian format (network byte order) over the socket. |
| Y | Sends a 2-byte (16-bit) integer in little-endian format over the socket. |
| Y | Sends a 4-byte (32-bit) integer in little-endian format over the socket. |
| Y | Sends an 8-byte (64-bit) integer in little-endian format over the socket. |
| Y | Sends an HTTP message with a method and user-defined headers given as a hash and an optional message body. |
| Y | Sends an HTTP response with user-defined headers given as a hash and an optional message body. |
| Y | Receives data from the socket and returns a string. |
| Y | Receives a 1-byte signed integer from the socket. |
| Y | Receives a 2-byte (16-bit) signed integer in big-endian format (network byte order) from the socket. |
| Y | Receives a 4-byte (32-bit) signed integer in big-endian format (network byte order) from the socket. |
| Y | Receives an 8-byte (64-bit) signed integer in big-endian format (network byte order) from the socket. |
| Y | Receives a 2-byte (16-bit) signed integer in little-endian format from the socket. |
| Y | Receives a 4-byte (32-bit) signed integer in little-endian format from the socket. |
| Y | Receives an 8-byte (64-bit) signed integer in little-endian format from the socket. |
| Y | Receives a 1-byte unsigned integer from the socket. |
| Y | Receives a 2-byte (16-bit) unsigned integer in big-endian format (network byte order) from the socket. |
| Y | Receives a 4-byte (32-bit) unsigned integer in big-endian format (network byte order) from the socket. |
| Y | Receives a 2-byte (16-bit) unsigned integer in little-endian format from the socket. |
| Y | Receives a 4-byte (32-bit) unsigned integer in little-endian format from the socket. |
| Y | Receives data on a socket and returns a binary object |
| Y | Retuns a hash representing the data in the HTTP header read, or, if the data cannot be parsed as an HTTP header, the data read is returned as a string. |
| N | Returns the port number of the socket for INET sockets. |
| N | Ensures that a socket will be closed even if shared with other processes. |
| N | Closes the socket. |
| N | Returns the character encoding for the socket. |
| N | Sets the character encoding for the socket. |
| N | Returns the |
| N | Sets the |
| N | Returns the socket file descriptor number. |
|
N |
Returns the name of the cipher for an encrypted connection or NOTHING is a secure connection has not been established. |
|
N |
Returns the version string of the cipher for encrypted connections or NOTHING is a secure connection has not been established. |
|
N |
Returns |
|
N |
Returns |
|
N |
Sets the X.509 certificate to use for negotiating encrypted connections. |
|
N |
Sets the private key to use for negotiating encrypted connections along with the X.509 certificate. |
| N | Returns a string code giving the result of verifying the remote certificate or NOTHING if an encrypted connection is not currently established. |
| N | Sets a Queue object to receive socket events, or clears the queue when called with no argument.. |
Creates the socket object.
my Socket $sock();
Closes the socket if it's open and destroys the object. If the socket was a UNIX domain socket, and was created with Socket::bind(), then the socket file will be deleted as well.
delete $sock;
Creates a new Socket object, not based on the original.
my Socket $new_sock = $sock.copy();
Binds the socket to a port, interface and port (if the $bind_to
string has a format "host:port"), or UNIX domain socket file. If the second parameter is True
, then the socket will set the SO_REUSEADDR
option, which will allow the socket to be bound to a port that is not yet closed (for example, in a TIME_WAIT
state).
Socket::bind(string
$bind_to
, bool $reuseaddr
= False) returns int
Socket::bind(int
$port
, bool $reuseaddr
= False) returns int
# bind to port 80 on all interfaces on the local system and reuse the address
$sock.bind(80, True
);
# bind to interface 192.168.2.23 port 8080 and do not reuse the address $sock.bind("192.168.2.23:8080");
# bind to UNIX domain socket file "/tmp/socket" $sock.bind("/tmp/socket");
Table 4.295. Arguments for Socket::bind(string $bind_to, bool $reuseaddr = False) Variant
Argument | Description |
---|---|
| If a colon appears in the string, the string will be assumed to be a hostname:port specification, and the port on the named IP address will be bound, otherwise, if the string contains no colon, the socket will be bound to a UNIX domain socket file on the local filesystem with the given name. |
| If this optional argument evaluates to |
Table 4.296. Arguments for Socket::bind(int $port, bool $reuseaddr = False) Variant
Argument | Description |
---|---|
The first argument gives the port number on the local machine; all network interfaces will be bound with this port number. | |
| If this optional argument evaluates to |
Table 4.297. Return Values for Socket::bind()
Return Type | Description |
---|---|
Returns 0 for success, -1 for error. |
Accepts connections on a listening socket (see Socket::listen()). As this method does not accept a timeout, use Socket::isDataAvailable() to check if data is available on the socket before calling if necessary.
Socket::accept() returns Socket
my Socket $new_socket = $sock.accept();
Table 4.298. Return Values for Socket::accept()
Return Type | Description |
---|---|
When a new connection has been accepted, a new Socket object is returned for the new connection. |
Accepts a remote connection and attempts to negotiate a TLS/SSL connection. As this method does not accept a timeout, use Socket::isDataAvailable() to check if data is available on the socket before calling if necessary.
Socket::acceptSSL() returns Socket
my Socket $new_sock = $sock.acceptSSL();
Table 4.300. Return Values for Socket::acceptSSL()
Return Type |
Description |
---|---|
A new socket object is returned for the new connection. |
Table 4.301. Exceptions thrown by Socket::acceptSSL()
err |
desc |
---|---|
|
An error occurred establishing the TLS/SSL connection. |
Connects the socket to a remote (or local) port or UNIX domain socket file, for network (INET) connections, accepts an optional timeout value in milliseconds (relative date/time values can be given instead of an integer in milliseconds to make the source more readable; ex: 20s
). If any errors occur, an exception is thrown.
See also Socket::connectUNIX(), Socket::connectUNIX(), Socket::connectSSL(), Socket::connectINETSSL(), and Socket::connectUNIXSSL().
Socket::connect(string
$dest
, softint $timeout_ms
= -1) returns nothing
Socket::connect(string
$dest
, date $timeout
) returns nothing
$sock.connect("192.168.1.45:8080", 30s); # connect to 192.168.1.45 port 8080 with a 30 second timeout
$sock.connect("/tmp/socket"); # connect to UNIX domain socket file "/tmp/socket"
EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED
Table 4.302. Arguments for Socket::connect()
Argument | Description |
---|---|
| If a colon appears in the string, the string will be assumed to be a hostname:port specification to connect to. If the string contains no colon, the socket will try to connect to a UNIX domain socket file on the local filesystem with the given name. |
If a timeout value is passed and the connection takes longer to establish than the timeout, an exception is thrown. |
Table 4.303. Exceptions Thrown by Socket::connect()
err | desc |
---|---|
| An error occured connecting to the remote socket (cannot resolve hostname, no listener, timeout exceeded, etc). |
Connects the socket to a remote (or local) port; accepts an optional timeout value in milliseconds (relative date/time values can be given instead of an integer in milliseconds to make the source more readable; ex: 20s
). If any errors occur, an exception is thrown.
See also Socket::connect(), Socket::connectUNIX(), Socket::connectSSL(), Socket::connectINETSSL(), and Socket::connectUNIXSSL().
Socket::connectINET(string
$host
, softint $port
, softint $timeout_ms
= -1) returns nothing
Socket::connectINET(string
$host
, softint $port
, date $timeout
) returns nothing
# connect to 192.168.1.45 port 8080 with a 30 second timeout $sock.connectINET("192.168.1.45", 8080, 30s);
EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED
Table 4.305. Exceptions Thrown by Socket::connectINET()
err | desc |
---|---|
| An error occured connecting to the remote socket (cannot resolve hostname, no listener, timeout exceeded, etc). |
Connects the socket to a remote (or local) port and attempts to establish a TLS/SSL connection; accepts an optional timeout value in milliseconds (relative date/time values can be given instead of an integer in milliseconds to make the source more readable; ex: 20s
). If any errors occur, an exception is thrown.
See also Socket::connect(), Socket::connectUNIX(), Socket::connectSSL(), Socket::connectINET(), and Socket::connectUNIXSSL().
Socket::connectINETSSL(string
$host
, softint $port
, softint $timeout_ms
= -1) returns nothing
Socket::connectINETSSL(string
$host
, softint $port
, date $timeout
) returns nothing
# connect to 192.168.1.45 port 8080 with a 30 second timeout $sock.connectINETSSL("192.168.1.45", 8080, 30s);
EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED
Table 4.307. Exceptions Thrown by Socket::connectINETSSL()
err | desc |
---|---|
| An error occured connecting to the remote socket (cannot resolve hostname, no listener, timeout exceeded, etc). |
Connects the socket to a UNIX domain socket file. If any errors occur, an exception is thrown.
See also Socket::connect(), Socket::connectINET(), Socket::connectSSL(), Socket::connectINETSSL(), and Socket::connectUNIXSSL().
Socket::connectUNIX(string
$file
) returns nothing
# connect to UNIX domain socket file "/tmp/socket" $sock.connectUNIX("/tmp/socket");
Table 4.308. Arguments for Socket::connectUNIX()
Argument | Description |
---|---|
| The socket will try to connect to a UNIX domain socket file on the local filesystem with the given name. |
Table 4.309. Exceptions Thrown by Socket::connectUNIX()
err | desc |
---|---|
| An error occured connecting to the remote socket. |
Connects the socket to a UNIX domain socket file and attempts to establish a TLS/SSL connection. If any errors occur, an exception is thrown.
See also Socket::connect(), Socket::connectUNIX(), Socket::connectSSL(), Socket::connectINETSSL(), and Socket::connectINET().
Socket::connectUNIXSSL(string
$file
) returns nothing
# connect to UNIX domain socket file "/tmp/socket" $sock.connectUNIXSSL("/tmp/socket");
Table 4.310. Arguments for Socket::connectUNIXSSL()
Argument | Description |
---|---|
| The socket will try to connect to a UNIX domain socket file on the local filesystem with the given name. |
Table 4.311. Exceptions Thrown by Socket::connectUNIXSSL()
err | desc |
---|---|
| An error occured connecting to the remote socket. |
Connects to a remote socket and attempts to establish a TLS/SSL connection, for network (INET) connections, accepts an optional timeout value in milliseconds (relative date/time values can be given instead of an integer in milliseconds to make the source more readable; ex: 20s
). If any errors occur, an exception is thrown.
See also Socket::connect(), Socket::connectUNIX(), Socket::connectUNIXSSL(), Socket::connectINETSSL(), and Socket::connectINET().
Socket::connectSSL(string
$dest
, softint $timeout_ms
= -1) returns nothing
Socket::connectSSL(string
$dest
, date $timeout
) returns nothing
$sock.connectSSL("192.168.1.45:8080", 30s); # connect to 192.168.1.45 port 8080 with a 30-second timeout
$sock.connectSSL("/tmp/socket"); # connect to UNIX domain socket file "/tmp/socket"
EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED
Table 4.312. Arguments for Socket::connectSSL()
Argument | Description |
---|---|
| If a colon appears in the string, the string will be assumed to be a hostname:port specification to connect to. If the string contains no colon, the socket will try to connect to a UNIX domain socket file on the local filesystem with the given name. |
If a timeout value is passed and the connection takes longer to establish than the timeout, an exception is thrown. |
Table 4.313. Exceptions thrown by Socket::connectSSL()
err |
desc |
---|---|
| An error occured connecting to the remote socket (cannot resolve hostname, no listener, timeout exceeded, etc). |
|
An error occurred establishing the TLS/SSL connection. |
Listens for new connections on a bound socket (see Socket::bind())
Socket::listen() returns int
$sock.listen();
Table 4.314. Return Values for Socket::listen()
Return Type | Description |
---|---|
Returns 0 for success, -1 for error. |
Shuts down the SSL connection on a secure connection; if any errors occur, an exception is raised.
Socket::shutdownSSL() returns nothing
$sock.shutdownSSL();
Table 4.316. Exceptions thrown by Socket::shutdownSSL()
err |
desc |
---|---|
|
An error occurred shutting down the TLS/SSL connection. |
Returns the name of the cipher for an encrypted connection or NOTHING if an encrypted connection has not been established.
Socket::getSSLCipherName() returns any
my any $str = $sock.getSSLCipherName();
Returns the version string of the cipher for encrypted connections or NOTHING if an encrypted connection has not been established.
Socket::getSSLCipherVersion() returns any
my any $str = $sock.getSSLCipherVersion();
Returns True
if the connection is a secure TLS/SSL connection.
Socket::isSecure() returns bool
my bool $b = $sock.isSecure();
Table 4.319. Return Values for Socket::isSecure()
Return Type |
Description |
---|---|
True if the connection is encrypted, |
Returns True
if the socket is open.
Socket::isOpen() returns bool
my bool $b = $sock.isOpen();
Table 4.320. Return Values for Socket::isOpen()
Return Type |
Description |
---|---|
True if the socket is open, |
Sets the X.509 certificate to use for negotiating encrypted connections. Requires an SSLCertificate object as the only argument to the method or the PEM or DER-encoded form of the certificate.
Socket::setCertificate(SSLCertificate
$cert
) returns nothing
Socket::setCertificate(string
$cert_pem
) returns nothing
Socket::setCertificate(binary
$cert_der
) returns nothing
$sock.setCertificate($cert);
Table 4.321. Arguments for Socket::setCertificate()
Argument |
Description |
---|---|
| This must be an SSL Certificate object. |
| The PEM-encoded string for the SSL Certificate. |
| The DER-encoded binary for the SSL Certificate. |
Sets the private key to use for negotiating encrypted connections along with the X.509 certificate. Requires an SSLPrivateKey object as the only argument to the method or the PEM or DER-encoded form of the private key.
Socket::setPrivateKey(SSLPrivateKey
$key
) returns nothing
Socket::setPrivateKey(string
$key_pem
, string $pass
) returns nothing
Socket::setPrivateKey(string
$key_pem
) returns nothing
Socket::setPrivateKey(binary
$key_der
) returns nothing
$sock.setPrivateKey($pkey);
Table 4.322. Arguments for Socket::setPrivateKey()
Argument |
Description |
---|---|
| The private key for the certificate. |
The PEM-encoded string for the private key for the certificate and optionally the password if required. | |
| The DER-encoded binary form of the private key for the certificate. |
Returns a string code giving the result of verifying the remote certificate. Return value are the keys described in the X509_VerificationReasons hash constant. This hash can also be used to generate a textual description of the verification result.
Socket::verifyPeerCertificate() returns any
my any $str = $sock.verifyPeerCertificate();
Sets a Queue object to receive socket events. To remove the event queue and stop monitoring socket events; call with no arguments or pass NOTHING
to the method. See Event Handling for more information.
Socket::setEventQueue() returns nothing
Socket::setEventQueue(Queue
$queue
) returns nothing
$sock.setEventQueue($queue);
Returns True
is data is available on the socket, takes an optional timeout. With a timeout of zero this method can be used for non-blocking polling the socket for data (can also be used to poll for new connections before Socket::accept()).
Socket::isDataAvailable(softint
$timeout_ms
= 0) returns bool
Socket::isDataAvailable(date
$timeout
) returns bool
my bool $b = $sock.isDataAvailable(); # returns True
if data is available now
Table 4.326. Return Values for Socket::isDataAvailable()
Return Type | Description |
---|---|
True if data is available on the socket, |
Returns True
if all data has been written to the socket, takes an optional timeout. With a timeout of zero this method returns immediately.
Socket::isWriteFinished(softint
$timeout_ms
= 0) returns bool
Socket::isWriteFinished(date
$timeout
) returns bool
my bool $b = $sock.isWriteFinished(0);
Table 4.328. Return Values for Socket::isWriteFinished()
Return Type | Description |
---|---|
True if the send action is complete, |
Sends string or binary data over a connected socket. String data will be converted to the encoding set for the socket if necessary. If an error occurs, -1 will be returned; in this case check errno() for the error number.
See also Socket::sendBinary().
Socket::send(data
$data
) returns int
if ($sock.send($data) == -1)
printf("error sending data: %s\n", strerror(errno()));
Table 4.331. Exceptions Thrown by Socket::send()
err | desc |
---|---|
| No argument was passed to the method. |
| The socket is not connected. |
Sends string or binary data over a connected socket. String data will not be converted to the encoding set for the socket, but rather will be sent as-is, even if the string's encoding is different from the socket's encoding. If an error occurs, -1 will be returned; in this case check errno() for the error number.
See also Socket::send().
Socket::sendBinary(data
$data
) returns int
if ($sock.sendBinary($data) == -1)
printf("error sending data: %s\n", strerror(errno()));
Table 4.334. Exceptions Thrown by Socket::sendBinary()
err | desc |
---|---|
| No argument was passed to the method. |
| The socket is not connected. |
Sends a 1-byte integer over the socket. If an error occurs, -1 will be returned; in this case check errno() for the error number.
Socket::sendi1(softint
$i
= 0) returns int
if ($sock.sendi1($val) == -1)
printf("error sending data: %s\n", strerror(errno()));
Table 4.335. Arguments for Socket::sendi1()
Argument | Description |
---|---|
| The integer to send; only the least-significant byte will be sent. |
Table 4.337. Exceptions Thrown by Socket::sendi1()
err | desc |
---|---|
| The socket is not connected. |
Sends a 2-byte integer in big-endian format (network byte order) over the socket. If an error occurs, -1 will be returned; in this case check errno() for the error number.
Socket::sendi2(softint
$i
= 0) returns int
if ($sock.sendi2($val) == -1)
printf("error sending data: %s\n", strerror(errno()));
Table 4.338. Arguments for Socket::sendi2()
Argument | Description |
---|---|
| The integer to send; only the least-significant 2-bytes will be sent. |
Table 4.340. Exceptions Thrown by Socket::sendi2()
err | desc |
---|---|
| The socket is not connected. |
Sends a 4-byte integer in big-endian format (network byte order) over the socket. If an error occurs, -1 will be returned; in this case check errno() for the error number.
Socket::sendi4(softint
$i
= 0) returns int
if ($sock.sendi4($val) == -1)
printf("error sending data: %s\n", strerror(errno()));
Table 4.341. Arguments for Socket::sendi4()
Argument | Description |
---|---|
| The integer to send; only the least-significant 4-bytes will be sent. |
Table 4.343. Exceptions Thrown by Socket::sendi4()
err | desc |
---|---|
| The socket is not connected. |
Sends an 8-byte (64-bit) integer in big-endian format (network byte order) over the socket. If an error occurs, -1 will be returned; in this case check errno() for the error number.
Socket::sendi8(softint
$i
= 0) returns int
if ($sock.sendi8($val) == -1)
printf("error sending data: %s\n", strerror(errno()));
Table 4.346. Exceptions Thrown by Socket::sendi8()
err | desc |
---|---|
| The socket is not connected. |
Sends a 2-byte integer in little-endian format over the socket. If an error occurs, -1 will be returned; in this case check errno() for the error number.
Socket::sendi2LSB(softint
$i
= 0) returns int
if ($sock.sendi2LSB($val) == -1)
printf("error sending data: %s\n", strerror(errno()));
Table 4.347. Arguments for Socket::sendi2LSB()
Argument | Description |
---|---|
| The integer to send; only the least-significant 2-bytes will be sent. |
Table 4.349. Exceptions Thrown by Socket::sendi2LSB()
err | desc |
---|---|
| The socket is not connected. |
Sends a 4-byte integer in little-endian format over the socket. If an error occurs, -1 will be returned; in this case check errno() for the error number.
Socket::sendi4LSB(softint
$i
= 0) returns int
if ($sock.sendi4LSB($val) == -1)
printf("error sending data: %s\n", strerror(errno()));
Table 4.350. Arguments for Socket::sendi4LSB()
Argument | Description |
---|---|
| The integer to send; only the least-significant 4-bytes will be sent. |
Table 4.352. Exceptions Thrown by Socket::sendi4LSB()
err | desc |
---|---|
| The socket is not connected. |
Sends an 8-byte (64-bit) integer in little-endian format over the socket. If an error occurs, -1 will be returned; in this case check errno() for the error number.
Socket::sendi8LSB(softint
$i
= 0) returns int
if ($sock.sendi8LSB($val) == -1)
printf("error sending data: %s\n", strerror(errno()));
Table 4.355. Exceptions Thrown by Socket::sendi8LSB()
err | desc |
---|---|
| The socket is not connected. |
Creates a properly-formatted HTTP message and sends it over the Socket.
Socket::sendHTTPMessage(string
$method
, string $path
, string $http_version
, hash $headers
, data $body
= binary()) returns nothing
$sock.sendHTTPMessage("POST", "/RPC2", "1.1", ("Content-Type" : "text/xml"), $xml);
Table 4.356. Arguments for Socket::sendHTTPMessage()
Argument | Description |
---|---|
| The HTTP method name to send (i.e. POST, HEAD, etc) |
| The path component of the URL. |
| The HTTP protocol version (1.0 or 1.1). |
| A hash of additional headers to send (key-value pairs). |
| If present (and does not have a length of zero), the body to be sent with the message (if present, the Content-Length header will be automatically set). |
Table 4.357. Exceptions Thrown by Socket::sendHTTPMessage()
err | desc |
---|---|
| One or more of the required arguments is missing. |
| The socket is not connected. |
| Send failed. |
Creates a properly-formatted HTTP response message and sends it over the Socket.
Socket::sendHTTPResponse(softint
$status_code
, string $desc
, string $http_version
, hash $headers
, data $body
= binary()) returns nothing
$sock.sendHTTPResponse(200, "OK", "1.1", ("Connection":"Keep-Alive"));
Table 4.358. Arguments for Socket::sendHTTPResponse()
Argument | Description |
---|---|
| The HTTP status code to send (i.e. 200, 404, etc) |
| The descriptive text for the status code. |
| The HTTP protocol version (1.0 or 1.1). |
| A hash of additional headers to send (key-value pairs). |
| If present (and does not have a length of zero), the body to be sent with the message (if present, the Content-Length header will be automatically set). |
Table 4.359. Exceptions Thrown by Socket::sendHTTPResponse()
err | desc |
---|---|
| One or more of the required arguments is missing. |
| The socket is not connected. |
| Send failed. |
Receives data from the socket and returns a string. If any errors occur reading from the socket, an exception is raised.
Socket::recv(softint
$size
= 0, softint $timeout_ms
= -1) returns string
Socket::recv(softint
$size
= 0, date $timeout
) returns string
$data = $sock.recv(-1); # read all data available
Table 4.360. Arguments for Socket::recv()
Argument | Description |
---|---|
| The amount of data to read in bytes. To read until the remote closes the connection, use -1. |
The timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. |
Table 4.361. Return Values for Socket::recv()
Return Type | Description |
---|---|
The data read, returned as a string. If any errors occur reading from the socket, an exception is raised. |
Table 4.362. Exceptions Thrown by Socket::recv()
err | desc |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives data from the socket and returns a binary object. If any errors occur reading from the socket, an exception is raised.
Socket::recvBinary(softint
$size
= 0, softint $timeout_ms
= -1) returns binary
Socket::recvBinary(softint
$size
= 0, date $timeout
) returns binary
my binary $bin = $sock.recvBinary(-1); # read all data available
Table 4.363. Arguments for Socket::recvBinary()
Argument | Description |
---|---|
| The amount of data to read in bytes. To read until the remote closes the connection, use -1. |
The timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. |
Table 4.364. Return Values for Socket::recvBinary()
Return Type | Description |
---|---|
The data read, returned as a binary object. If any errors occur reading from the socket, an exception is raised. |
Table 4.365. Exceptions Thrown by Socket::recvBinary()
err | desc |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives a 1-byte signed integer from the socket. If any errors occur reading from the socket, an exception is raised.
Socket::recvi1(softint
$timeout_ms
= -1) returns int
Socket::recvi1(date
$timeout
) returns int
my int $val = $sock.recvi1();
Table 4.367. Return Values for Socket::recvi1()
Return Type | Description |
---|---|
The 1-byte signed integer read. If any errors occur reading from the socket, an exception is raised. |
Table 4.368. Exceptions Thrown by Socket::recvi1()
err | desc |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives a 2-byte signed integer in big-endian format (network byte order) from the socket. If any errors occur reading from the socket, an exception is raised.
Socket::recvi2(softint
$timeout_ms
= -1) returns int
Socket::recvi2(date
$timeout
) returns int
my int $val = $sock.recvi2();
Table 4.370. Return Values for Socket::recvi2()
Return Type | Description |
---|---|
The 2-byte signed integer read. If any errors occur reading from the socket, an exception is raised. |
Table 4.371. Exceptions Thrown by Socket::recvi2()
err | desc |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives a 4-byte signed integer in big-endian format (network byte order) from the socket. If any errors occur reading from the socket, an exception is raised.
Socket::recvi4(softint
$timeout_ms
= -1) returns int
Socket::recvi4(date
$timeout
) returns int
my int $val = $sock.recvi4();
Table 4.373. Return Values for Socket::recvi4()
Return Type | Description |
---|---|
The 4-byte signed integer read. If any errors occur reading from the socket, an exception is raised. |
Table 4.374. Exceptions Thrown by Socket::recvi4()
err | desc |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives an 8-byte (64-bit) signed integer in big-endian format (network byte order) from the socket. If any errors occur reading from the socket, an exception is raised.
Socket::recvi8(softint
$timeout_ms
= -1) returns int
Socket::recvi8(date
$timeout
) returns int
my int $val = $sock.recvi8();
Table 4.375. Arguments for Socket::recvi8()
Argument | Description |
---|---|
The timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. A relative date/time value can be used as well (i.e. |
Table 4.376. Return Values for Socket::recvi8()
Return Type | Description |
---|---|
The 8-byte (64-bit) signed integer read. If any errors occur reading from the socket, an exception is raised. |
Table 4.377. Exceptions Thrown by Socket::recvi8()
err | desc |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives a 2-byte signed integer in little-endian format from the socket. If any errors occur reading from the socket, an exception is raised.
Socket::recvi2LSB(softint
$timeout_ms
= -1) returns int
Socket::recvi2LSB(date
$timeout
) returns int
my int $val = $sock.recvi2LSB();
Table 4.379. Return Values for Socket::recvi2LSB()
Return Type | Description |
---|---|
The 2-byte signed integer read. If any errors occur reading from the socket, an exception is raised. |
Table 4.380. Exceptions Thrown by Socket::recvi2LSB()
err | desc |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives a 4-byte signed integer in little-endian format from the socket. If any errors occur reading from the socket, an exception is raised.
Socket::recvi4LSB(softint
$timeout_ms
= -1) returns int
Socket::recvi4LSB(date
$timeout
) returns int
my int $val = $sock.recvi4LSB(1250ms); # timeout in 1.25 seconds
Table 4.382. Return Values for Socket::recvi4LSB()
Return Type | Description |
---|---|
The 4-byte signed integer read. If any errors occur reading from the socket, an exception is raised. |
Table 4.383. Exceptions Thrown by Socket::recvi4LSB()
err | desc |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives an 8-byte (64-bit) signed integer in little-endian format from the socket. If any errors occur reading from the socket, an exception is raised.
Socket::recvi8LSB(softint
$timeout_ms
= -1) returns int
Socket::recvi8LSB(date
$timeout
) returns int
my int $val = $sock.recvi8LSB();
Table 4.384. Arguments for Socket::recvi8LSB()
Argument | Description |
---|---|
The timeout in milliseconds (1/1000 second). If no timeout is passed, then the call will not time out and will not return until all the data has been read or the remote end closes the connection. A relative date/time value can be used as well (i.e. |
Table 4.385. Return Values for Socket::recvi8LSB()
Return Type | Description |
---|---|
The 8-byte (64-bit) signed integer read. If any errors occur reading from the socket, an exception is raised. |
Table 4.386. Exceptions Thrown by Socket::recvi8LSB()
err | desc |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives a 1-byte unsigned integer from the socket. If any errors occur reading from the socket, an exception is raised.
Socket::recvu1(softint
$timeout_ms
= -1) returns int
Socket::recvu1(date
$timeout
) returns int
my int $val = $sock.recvu1();
Table 4.388. Return Values for Socket::recvu1()
Return Type | Description |
---|---|
The 1-byte unsigned integer read. If any errors occur reading from the socket, an exception is raised. |
Table 4.389. Exceptions Thrown by Socket::recvu1()
err | desc |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives a 2-byte unsigned integer in big-endian format (network byte order) from the socket. If any errors occur reading from the socket, an exception is raised.
Socket::recvu2([timeout_ms]
)
Socket::recvu2(softint
$timeout_ms
= -1) returns int
Socket::recvu2(date
$timeout
) returns int
Table 4.391. Return Values for Socket::recvu2()
Return Type | Description |
---|---|
The 2-byte unsigned integer read. If any errors occur reading from the socket, an exception is raised. |
Table 4.392. Exceptions Thrown by Socket::recvu2()
err | desc |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives a 4-byte unsigned integer in big-endian format (network byte order) from the socket. If any errors occur reading from the socket, an exception is raised.
Socket::recvu4(softint
$timeout_ms
= -1) returns int
Socket::recvu4(date
$timeout
) returns int
my int $val = $sock.recvu4();
Table 4.394. Return Values for Socket::recvu4()
Return Type | Description |
---|---|
The 4-byte unsigned integer read. If any errors occur reading from the socket, an exception is raised. |
Table 4.395. Exceptions Thrown by Socket::recvu4()
err | desc |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives a 2-byte unsigned integer in little-endian format from the socket. If any errors occur reading from the socket, an exception is raised.
Socket::recvu2LSB(softint
$timeout_ms
= -1) returns int
Socket::recvu2LSB(date
$timeout
) returns int
my int $val = $sock.recvu2LSB();
Table 4.397. Return Values for Socket::recvu2LSB()
Return Type | Description |
---|---|
The 2-byte unsigned integer read. If any errors occur reading from the socket, an exception is raised. |
Table 4.398. Exceptions Thrown by Socket::recvu2LSB()
err | desc |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Receives a 4-byte unsigned integer in little-endian format from the socket. If any errors occur reading from the socket, an exception is raised.
Socket::recvu4LSB(softint
$timeout_ms
= -1) returns int
Socket::recvu4LSB(date
$timeout
) returns int
my int $val = $sock.recvu4LSB();
Table 4.400. Return Values for Socket::recvu4LSB()
Return Type | Description |
---|---|
The 4-byte unsigned integer read. If any errors occur reading from the socket, an exception is raised. |
Table 4.401. Exceptions Thrown by Socket::recvu4LSB()
err | desc |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Reads an HTTP header and returns a hash representing the data read. If any errors occur reading from the socket, an exception is raised. Accepts an optional timeout value in milliseconds.
This method sets the keys in the following table in the hash returned as well to give additional information about the HTTP header received.
Table 4.402. Special Keys in Hash Returned By Socket::readHTTPHeader()
Key | Description of Value |
---|---|
| A string giving the HTTP version set in the header |
| An integer giving the status code; this key is only set in HTTP responses |
| If present in an HTTP response, this key will be set to the message after the status code |
| A string giving the HTTP method (i.e. |
| A string giving the path in a request without any decoding; use decode_url() to decode if necessary. |
Socket::readHTTPHeader(softint
$timeout_ms
= -1) returns any
Socket::readHTTPHeader(date
$timeout
) returns any
my hash $hash = $sock.readHTTPHeader();
Table 4.404. Return Values for Socket::readHTTPHeader()
Return Type | Description |
---|---|
The return hash will contain keys for each header, plus an http_version key, giving the HTTP protocol version. For HTTP responses, the following keys will be returned: |
Table 4.405. Exceptions Thrown by Socket::readHTTPHeader()
err | desc |
---|---|
| The socket is not connected. |
| The remote end has closed the connection. |
| There was an error receiving the data. |
Returns the port number of the socket for INET sockets.
Socket::getPort() returns int
$port = $sock.getPort();
Table 4.406. Return Values for Socket::getPort()
Return Type | Description |
---|---|
Returns the port number for an INET connection, -1 if no INET connection has been established. |
Ensures that a socket will be closed even if the file descriptor is shared with other processes (for example, after a call to fork()). Returns 0 for success, -1 for error; in this case check errno() for the error number.
Socket::shutdown() returns int
$sock.shutdown();
Closes an open socket. Also deletes the UNIX domain socket file if it was created by a call to Socket::bind(). Returns 0 for success, -1 for error; in this case check errno() for the error number.
Socket::close() returns int
$sock.close();
Returns the character encoding for the socket.
Socket::getCharset() returns string
$enc = $sock.getCharset();
Table 4.409. Return Value for Socket::getCharset()
Return Type | Description |
---|---|
The character encoding for the socket. |
Sets the character encoding for the socket. If any string data is sent over the socket with Socket::send(), then the character encoding will be automatically converted if needed.
Socket::setCharset(string
$encoding
) returns nothing
$sock.setCharset("ISO-8859-1");
Table 4.410. Arguments for Socket::setCharset()
Argument | Description |
---|---|
| The character encoding for the socket. |
Returns the TCP_NODELAY
setting for the socket. See also Socket::setNoDelay().
Socket::getNoDelay() returns bool
$nodelay = $sock.getNoDelay();
Table 4.411. Return Value for Socket::getNoDelay()
Return Type | Description |
---|---|
The |
Sets the TCP_NODELAY
setting for the socket; when this setting is True
, then data will be immediately sent out over the socket, when it is False
, then data transmission may be delayed to be packaged with other data for the same target.
Delayed data transmissions may cause problems when the sender immediately closes the socket after sending data; in this case the receiver may not get the data even though the send succeeded.
Note that if no value is given to the method, the argument will be assumed to be False
, and output buffering will be turned on for the socket, which may be the opposite of what the programmer intends, therefore it's recommended to always pass an argument to this method.
See also Socket::getNoDelay().
Socket::setNoDelay(bool
$nodelay
= True) returns int
$sock.setNoDelay(True
);
Table 4.412. Arguments for Socket::setNoDelay()
Argument | Description |
---|---|
| The |
Table 4.413. Return Value for Socket::setNoDelay()
Return Type | Description |
---|---|
0 for success, non-zero for errors. To get error information, see errno() and strerror(). |
Returns the file descriptor number associated with the socket.
Socket::getSocket() returns int
$sock = $sock.getSocket();
Table 4.414. Return Values for Socket::getSocket()
Return Type | Description |
---|---|
The file descriptor associated to the socket. |
Note: This class is not available with the PO_NO_NETWORK
parse option.
The HTTPClient class can be used to communicate with HTTP servers using the HTTP or HTTPS (HTTP using an SSL/TLS encrypted connection) protocol.
By default 'Connection: Keep-Alive' is always sent regardless of the HTTP protocol level set for the object, however if a server response contains 'Connection: close', the connection will be closed as soon as the full response (including any message body if present) has been read.
HTTP redirect responses are supported and can be limited with the max_redirects
constructor hash key or by using the HTTPClient::setMaxRedirects() method. The default number of redirects is 5.
HTTP basic authentication is supported; set the username and password in the URL (ex: http://username:password@host:port/path). To change the URL from the one set by the constructor, call HTTPClient::setURL().
HTTP proxies and basic proxy authentication are supported by setting the proxy
constructor hash key to the proxy URL (with a proxy username and password if required) or by calling the HTTPClient::setProxyURL() method.
Objects of this class are thread-safe and support serializing multiple simultaneous requests from many threads. If a request is in progress and another thread attempts to make a request at the same time, the second thread will block until the first is complete. Therefore the total amount of time a thread could wait for a response in a multi-threaded context could be greater than the read timeout value.
This class understands and automatically decodes "deflate", "gzip", and "bzip2" content encodings as well.
The default read timeout value is 300,000 milliseconds (5 minutes). Note that the read timeout value applies to individual packets; for this reason for large transfers the overall read time could exceed the read timeout value.
When an exception is thrown (for example, a response code of < 200 or >= 400 is received from the server), any message body returned will be in the "arg" key of the exception hash.
This class understands the protocols in the following table.
Table 4.415. HTTPClient Class Protocols
Protocol | Default Port | SSL? | Description |
---|---|---|---|
| 80 | No | Unencrypted HTTP protocol |
| 443 | Yes | HTTP protocol with SSL/TLS encryption |
Whenever using an HTTPClient method where a hash of headers can be passed to the method, some headers are generated by default by the class and can be overridden, and some are cannot be overridden and are ignored if passed by the client. See the following tables for details.
Table 4.416. HTTPClient Mandatory Headers
Header | Description |
---|---|
| This header is only sent if a message body is send, and, if so, the length is calculated automatically. |
Table 4.417. HTTPClient Default, but Overridable Headers
Header | Default Value |
---|---|
|
|
|
|
|
|
|
|
|
|
This class supports posting network events to a Queue. See Event Handling for more information.
The events raised by this object are listed in the following table:
Table 4.418. HTTPClient Events
Name | Description |
---|---|
Raised when the HTTP "Content-Length" header is received. | |
Raised when HTTP chunked data is about to be received. | |
Raised when all HTTP chunked data has been received. | |
Raised when an HTTP redirect message is received. | |
Raised when an HTTP message is sent. | |
Raised when an HTTP message is received. | |
Raised when HTTP footers are received. | |
Raised when a block of HTTP chunked data is received. | |
Raised when the next chunk size for HTTP chunked data is known. |
The following table gives an overview of the methods available in the HTTPClient class.
Table 4.419. HTTPClient Class Method Overview
Method |
Except? |
Description |
---|---|---|
|
Y |
Creates the HTTPClient object based on the parameters passed. |
N |
Destroys the HTTPClient object and closes any open connections. | |
Y | Copying objects of this class is not supported, an exception will be thrown. | |
| N | Returns the current URL. |
| Y | Sets a new URL value for the next connection. |
| N | Returns the current proxy URL as a string or NOTHING if no proxy URL is set. |
| Y | Sets or clears (in case called with no argument) a new proxy URL value for the next connection. |
| N | Clears the proxy URL value. |
| N | Sets the SSL/TLS flag for the next connection to the proxy. |
| N | Returns the SSL/TLS flag. |
| N | Returns the current |
| N | Updates the |
|
N |
Connects to the remote socket; SSL/TLS negotiation is performed if required. |
|
N |
Disconnects from the remote socket |
|
Y |
Sends an HTTP GET request and returns the message body received as a string or NOTHING if no message body is received. In order to get the headers and the body, use the HTTPClient::send() method instead. If no connection is established, an internal call to HTTPClient::connect() will be made before sending the message. |
|
Y |
Sends an HTTP HEAD request and returns as hash of the headers received. If no connection is established, an internal call to HTTPClient::connect() will be made before sending the message. |
|
Y |
Sends an HTTP POST request with a message body and returns the message body received as a string or NOTHING if no message body is received. In order to get the headers and the body in the response, use the HTTPClient::send() method instead. If no connection is established, an internal call to HTTPClient::connect() will be made before sending the message. |
|
Y |
Sends an HTTP request with the specified method and optional message body and returns headers and any body received as a response in a hash format. If no connection is established, an internal call to HTTPClient::connect() will be made before sending the message. |
| N | Sets the connect timeout in milliseconds. Negative numbers mean use the default system connect timeout. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. |
| N | Sets the default read timeout in milliseconds. Zero means immediate timeout (will return data only if it is already available), and negative numbers mean never timeout (wait forever for data). Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. |
| N | Returns the connect timeout as an integer in milliseconds. Negative numbers mean the system default timeout is used. |
| N | Returns the default read timeout as an integer in milliseconds. Zero means immediate timeout (only returns data if it is already available), and negative numbers mean never timeout (wait forever for data). |
|
Y |
Sets the HTTP protocol version string for headers in outgoing messages, allowed values are '1.0' and '1.1'. |
|
N |
Returns the HTTP protocol version string used in outgoing messages. |
|
N |
Sets the object to make a secure SSL/TLS connection on the next connect if the passed argument is |
|
N |
Returns |
|
N |
Returns a string code giving the result of verifying the remote certificate or NOTHING if a secure connection is not established. Return value are the keys described in the X509_VerificationReasons hash constant. This hash can also be used to generate a textual description of the verification result. |
|
N |
Returns the name of the cipher as a string for an encrypted connection or NOTHING if a secure connection is not established. |
|
N |
Returns the version of the cipher as a string for an encrypted connection or NOTHING if a secure connection is not established. |
|
Y |
Sets the string encoding for the object; any strings deserialized with this object will be tagged with this character encoding. |
| N | Returns the character encoding used for the object |
| N | Sets a Queue object to receive HTTPClient and Socket events or clears the queue if no argument is passed. |
| N | Returns the |
| N | Sets the |
| N | Returns |
Creates the HTTPClient object based on the parameters passed. To connect, call any method that requires a connection and an implicit connection is established, or call HTTPClient::connect().
HTTPClient::constructor(hash
$opts
)
my HTTPClient $httpclient(("url":"http://hostname:8080/path"));
Table 4.420. Arguments for HTTPClient::constructor()
Argument |
Description |
---|---|
|
sets options and changes default behaviour for the object, etc. See the table below for information on valid keys and their mening. Note that the key names are case-sensitive and therefore must all be in lower-case. |
Table 4.421. HTTPClient::constructor() Option Hash Keys
Key | Description |
---|---|
| A string giving the URL to connect to. |
| The default port number to connect to if none is given in the URL. |
| A hash describing new protocols, the key is the protocol name and the value is either an integer giving the default port number or a hash with 'port' and 'ssl' keys giving the default port number and a boolean value to indicate that an SSL connection should be established. |
| Either '1.0' or '1.1' for the claimed HTTP protocol version compliancy in outgoing message headers. |
| The default path to use for new connections if a path is not otherwise specified in the connection URL. |
| The maximum number of redirects before throwing an exception (the default is 5). |
| The proxy URL for connecting through a proxy. |
| The timeout value in milliseconds (also can be a relative date-time value for clarity, ex: |
| The timeout value in milliseconds for establishing a new socket connection (also can be a relative date-time value for clarity, ex: |
Table 4.422. Exceptions thrown by HTTPClient::constructor()
err | desc |
---|---|
| invalid or unknown option passed in option hash |
| invalid URL string |
| unknown protocol passed in URL |
Destroys the HTTPClient object and closes any open connections.
delete $httpclient;
Copying objects of this class is not supported, an exception will be thrown.
Table 4.423. Exceptions thrown by HTTPClient::copy()
err |
desc |
---|---|
|
objects of this class may not be copied |
Returns the current URL value for the object. To set the URL, use the HTTPClient::setURL() method.
HTTPClient::getURL() returns string
$url = $httpclient.getURL();
Sets the URL value for the object. To retrieve the current URL value, use the HTTPClient::getURL() method.
HTTPClient::setURL(string
$url
) returns nothing
$httpclient.setURL("https://user:password@hostname:8080/path");
Table 4.425. Arguments for HTTPClient::setURL()
Argument | Description |
---|---|
| The new URL for the object. |
Table 4.426. Exceptions thrown by HTTPClient::setURL()
err | desc |
---|---|
| invalid URL string |
| unknown protocol passed in URL |
Returns the current proxy URL value for the object (NOTHING if no proxy URL is set). To set the proxy URL, use the HTTPClient::setProxyURL() method.
HTTPClient::getProxyURL() returns any
$proxy_url = $httpclient.getProxyURL();
Sets the proxy URL value for the object; call with no argument or NOTHING to clear. To retrieve the current URL value, use the HTTPClient::getProxyURL() method.
HTTPClient::setProxyURL() returns nothing
HTTPClient::setProxyURL(string
$url
) returns nothing
$httpclient.setProxyURL("http://user:password@proxy_host:8080/path");
Table 4.429. Exceptions thrown by HTTPClient::setProxyURL()
err | desc |
---|---|
| invalid URL string |
| invalid authorization credentials in proxy URL (username without password or vice-versa) |
| unknown protocol passed in URL |
Clears the current proxy URL
HTTPClient::clearProxyURL() returns nothing
$httpclient.clearProxyURL();
Sets the SSL/TLS flag for the next proxy connection. To check the flag, use the HTTPClient::isProxySecure() method.
HTTPClient::setProxySecure(softbool
$secure
= True) returns nothing
$httpclient.setProxySecure(True
);
Table 4.430. Arguments for HTTPClient::setProxySecure()
Argument | Description |
---|---|
| sets the SSL/TLS flag for the next proxy connection |
Returns the SSL/TLS flag for proxy connection. To set the flag, use the HTTPClient::setProxySecure() method.
HTTPClient::isProxySecure() returns bool
$bool = $httpclient.isProxySecure();
Table 4.431. Return Values for HTTPClient::isProxySecure()
Return Type | Description |
---|---|
The value of the SSL/TLS flag for the proxy connection. |
Returns the maximum number of redirects allowed for the object. To set this value, use the HTTPClient::setMaxRedirects() method.
HTTPClient::getMaxRedirects() returns int
$num = $httpclient.getMaxRedirects();
Table 4.432. Return Values for HTTPClient::getMaxRedirects()
Return Type | Description |
---|---|
The current value of the |
Sets the maximum number of redirects allowed for the object. To retrieve this value, use the HTTPClient::getMaxRedirects() method.
HTTPClient::setMaxRedirects(softint
$max
= 0) returns nothing
$httpclient.setMaxRedirects(0); # disable redirections
Table 4.433. Arguments for HTTPClient::setMaxRedirects()
Argument | Description |
---|---|
| The maximum number of HTTP redirects allowed for the object before an exception is thrown. |
Connects to the remote socket. If the protocol indicates that a secure connection should be established (or HTTPClient::setSecure() was called previsouly), SSL/TLS negotiation will be attempted. Note: For possible exceptions, see the Socket::connect() method (or Socket::connectSSL() for secure connections).
If the TCP_NODELAY
flag has been set (see HTTPClient::setNoDelay()), then after a successful connection to the remote socket, this option will be set on the socket. If an error occurs setting the TCP_NODELAY
option, the internal flag is set to false (use HTTPClient::getNoDelay() to check the flag's state) and the error code can be retrieved with errno().
HTTPClient::connect() returns nothing
$httpclient.connect();
EVENT_CONNECTING, EVENT_CONNECTED,EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED
Table 4.434. Exceptions thrown by HTTPClient::connect()
err | desc |
---|---|
| The attempt to connect exceeeded the maximum number of redirects allowed for the object. |
| There was an error receiving data on the socket |
| The receive attempt timed out. |
Disconnects from the remote socket if a connection is established (otherwise does nothing).
HTTPClient::disconnect() returns nothing
$httpclient.disconnect();
Sends an HTTP GET request and returns the message body received. In order to get the headers and the body, use the HTTPClient::send() method instead. If necessary, a connection will be established via an implicit call to HTTPClient::connect() before sending the message.
HTTPClient::get(string
$path
, hash $headers = hash(), reference $info
) returns any
HTTPClient::get(string
$path
, hash $headers = hash()) returns any
$html = $httpclient.get("/path/file.html");
EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED, EVENT_HTTP_SEND_MESSAGE, EVENT_PACKET_SENT, EVENT_HTTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_HTTP_CONTENT_LENGTH, EVENT_HTTP_CHUNKED_START, EVENT_HTTP_CHUNKED_END, EVENT_HTTP_CHUNKED_DATA_RECEIVED, EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED, EVENT_HTTP_REDIRECT
Table 4.435. Arguments for HTTPClient::get()
Argument |
Description |
---|---|
| The path for the message (i.e. '/path/resource?method¶m=value') |
An optional hash of headers to include in the message. | |
| An optional reference to an lvalue that will be used as an output variable giving a hash of request headers and other information about the HTTP request. |
Table 4.437. Exceptions thrown by HTTPClient::get()
err |
desc |
---|---|
|
timeout on response from HTTP server |
|
error communicating with HTTP server |
Sends an HTTP HEAD request and returns the headers received. If necessary, a connection will be established via an implicit call to HTTPClient::connect() before sending the message.
HTTPClient::head(string
$path
, hash $headers
= hash(), reference $info
) returns hash
HTTPClient::head(string
$path
, hash $headers
= hash()) returns hash
$response = $httpclient.head("/path");
EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED, EVENT_HTTP_SEND_MESSAGE, EVENT_PACKET_SENT, EVENT_HTTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_HTTP_CONTENT_LENGTH, EVENT_HTTP_CHUNKED_START, EVENT_HTTP_CHUNKED_END, EVENT_HTTP_CHUNKED_DATA_RECEIVED, EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED, EVENT_HTTP_REDIRECT
Table 4.438. Arguments for HTTPClient::head()
Argument | Description |
---|---|
| The path for the message (i.e. '/path/resource?method¶m=value') |
An optional hash of headers to include in the message. | |
| An optional reference to an lvalue that will be used as an output variable giving a hash of request headers and other information about the HTTP request. |
Table 4.439. Return Values for HTTPClient::head()
Return Type |
Description |
---|---|
The headers received from the HTTP server with all key names converted to lower-case. |
Table 4.440. Exceptions thrown by HTTPClient::head()
err |
desc |
---|---|
|
timeout on response from HTTP server |
|
error communicating with HTTP server |
Sends an HTTP POST request with a message body and returns the message body received as a response. In order to get the headers and the body, use HTTPClient::send() instead. If necessary, a connection will be established via an implicit call to HTTPClient::connect() before sending the message.
HTTPClient::post(string
$path
, data $body
, hash $headers
= hash(), reference $info
) returns any
HTTPClient::post(string
$path
, data $body
, hash $headers
= hash()) returns any
Table 4.441. Arguments for HTTPClient::post()
Argument | Description |
---|---|
| The path for the message (i.e. '/path/resource?method¶m=value') |
| The message body to send. |
An optional hash of headers to include in the message. | |
| An optional reference to an lvalue that will be used as an output variable giving a hash of request headers and other information about the HTTP request. |
Table 4.443. Exceptions thrown by HTTPClient::post()
err |
desc |
---|---|
|
timeout on response from HTTP server |
|
error communicating with HTTP server |
Sends an HTTP request with the specified method and optional message body and returns headers and optionally the body received as a response in a hash format. If necessary, a connection will be established via an implicit call to HTTPClient::connect() before sending the message.
HTTPClient::send(data
$body
= binary(), string $method
, string $path
= "", hash $headers = hash(), bool $getbody
= False, reference $info
) returns hash
HTTPClient::send(data
$body
= binary(), string $method
, string $path
= "", hash $headers = hash(), bool $getbody
= False) returns hash
$msg = $httpclient.send($body, "POST", "/path", ("Connection":"Keep-Alive"));
EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED, EVENT_HTTP_SEND_MESSAGE, EVENT_PACKET_SENT, EVENT_HTTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_HTTP_CONTENT_LENGTH, EVENT_HTTP_CHUNKED_START, EVENT_HTTP_CHUNKED_END, EVENT_HTTP_CHUNKED_DATA_RECEIVED, EVENT_HTTP_CHUNK_SIZE, EVENT_HTTP_FOOTERS_RECEIVED, EVENT_HTTP_REDIRECT
Table 4.444. Arguments for HTTPClient::send()
Argument | Description |
---|---|
| The message body to send; use NOTHING to send to body. |
| The name of the HTTP method ( |
| The path for the message (i.e. '/path/resource?method¶m=value') |
An optional hash of headers to include in the message. | |
| If this argument is true, then the object will try to receive a message body even if no |
| An optional reference to an lvalue that will be used as an output variable giving a hash of request headers and other information about the HTTP request. |
Table 4.445. Return Values for HTTPClient::send()
Return Type |
Description |
---|---|
The headers received from the HTTP server with all key names converted to lower-case. The message body, if any, will be assigned to the value of the 'body' key. |
Table 4.446. Exceptions thrown by HTTPClient::send()
err |
desc |
---|---|
|
timeout on response from HTTP server |
|
error communicating with HTTP server |
|
invalid HTTP method passed |
Sets the default connect timeout in milliseconds. Negative numbers mean use the default system timeout. Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. 2m
= two minutes, etc.).
HTTPClient::setConnectTimeout(softint
$timeout_ms
= -1) returns nothing
HTTPClient::setConnectTimeout(date
$timeout
) returns nothing
$httpclient.setConnectTimeout(2m); # sets timeout to 2 minutes
Sets the default read timeout in milliseconds. Zero means immediate timeout (will return data only if it is already available), and negative numbers mean never timeout (wait forever for data). Note that like all Qore functions and methods taking timeout values, a relative date/time value can be used to make the units clear (i.e. 2m
= two minutes, etc.).
HTTPClient::setTimeout(softint
$timeout_ms
= -1) returns nothing
HTTPClient::setTimeout(date
$timeout
) returns nothing
$httpclient.setTimeout(2m); # sets timeout to 2 minutes
Returns the connect timeout as an integer in milliseconds. Negative numbers mean the default system timeout is used instead.
HTTPClient::getConnectTimeout() returns int
$timeout = $httpclient.getConnectTimeout();
Table 4.449. Return Values for HTTPClient::getConnectTimeout()
Return Type |
Description |
---|---|
The connect timeout value in milliseconds |
Returns the default read timeout as an integer in milliseconds. Zero means immediate timeout (only returns data if it is already available), and negative numbers mean never timeout (wait forever for data).
HTTPClient::getTimeout() returns int
$timeout = $httpclient.getTimeout();
Table 4.450. Return Values for HTTPClient::getTimeout()
Return Type |
Description |
---|---|
The read timeout value in milliseconds |
Sets the HTTP protocol version string for headers in outgoing messages, allowed values are '1.0' and '1.1'.
HTTPClient::setHTTPVersion(string
$ver
) returns nothing
$httpclient.setHTTPVersion("1.1");
Table 4.451. Arguments for HTTPClient::setHTTPVersion()
Argument |
Description |
---|---|
|
either '1.0' or '1.1' for the HTTP protocol compliance version. |
Table 4.452. Exceptions thrown by HTTPClient::setHTTPVersion()
err |
desc |
---|---|
|
invalid HTTP version passed (allowed values: '1.0', '1.1'). |
Returns the HTTP protocol version string used in outgoing messages.
HTTPClient::getHTTPVersion() returns string
$version = $httpclient.getHTTPVersion();
Table 4.453. Return Values for HTTPClient::getHTTPVersion()
Return Type |
Description |
---|---|
The HTTP protocol version string used in outgoing messages (either '1.0' or '1.1'). |
Sets the object to make a secure SSL/TLS connection on the next connect if the passed argument is True
, or an unencrypted cleartext connection if it is False
. This method overrides the default behaviour for the protocol set for the object.
Note that the behavior of this method when called with no argument changed in version 0.8.0; prior to version 0.8.0 calling this method with no argument would turn off secure mode; the behavior was changed to the current functionality in order to make the usage of this method consistent with other methods of the same name and to make it more logical.
HTTPClient::setSecure(softbool
$secure
= True) returns nothing
$httpclient.setSecure(True
);
Table 4.454. Arguments for HTTPClient::setSecure()
Argument |
Description |
---|---|
|
If |
Returns True
if the current connection is encrypted, False
if not.
HTTPClient::isSecure() returns bool
$bool = $httpclient.isSecure();
Table 4.455. Return Values for HTTPClient::isSecure()
Return Type |
Description |
---|---|
Returns |
Returns a string code giving the result of verifying the remote certificate or NOTHING if an encrypted connection is not established. Return value are the keys described in the X509_VerificationReasons hash constant. This hash can also be used to generate a textual description of the verification result.
HTTPClient::verifyPeerCertificate() returns any
my any $str = $httpclient.verifyPeerCertificate();
Returns the name of the cipher for an encrypted connection.
HTTPClient::getSSLCipherName() returns any
my any $str = $httpclient.getSSLCipherName();
Returns the version of the cipher for an encrypted connection.
HTTPClient::getSSLCipherVersion() returns any
my any $str = $httpclient.getSSLCipherVersion();
Sets the string encoding for the object; any strings deserialized with this object will be tagged with this character encoding.
HTTPClient::setEncoding(string
$encoding
) returns nothing
$httpclient.setEncoding("ISO-8859-1");
Table 4.459. Arguments for HTTPClient::setEncoding()
Argument |
Description |
---|---|
|
The string encoding to use for this object. |
Table 4.460. Exceptions thrown by HTTPClient::setEncoding()
err |
desc |
---|---|
|
missing encoding parameter from method call |
Returns the character encoding used for the object
HTTPClient::getEncoding() returns string
$str = $httpclient.getEncoding();
Table 4.461. Return Values for HTTPClient::getEncoding()
Return Type |
Description |
---|---|
The character encoding used for the object. |
Sets a Queue object to receive HTTPClient and Socket events. To remove the event queue and stop monitoring events, pass NOTHING
to the method. See Event Handling for more information.
HTTPClient::setEventQueue() returns nothing
HTTPClient::setEventQueue(Queue
$queue
) returns nothing
$httpclient.setEventQueue($queue);
Returns the TCP_NODELAY
setting for the HTTPClient object. See also HTTPClient::setNoDelay().
HTTPClient::getNoDelay() returns bool
$nodelay = $httpclient.getNoDelay();
Table 4.463. Return Value for HTTPClient::getNoDelay()
Return Type | Description |
---|---|
The |
Sets the TCP_NODELAY
setting for the HTTPClient object; when this setting is True
, then data will be immediately sent out over the HTTPClient object's socket, when it is False
, then data transmission may be delayed to be packaged with other data for the same target.
Delayed data transmissions may cause problems when the sender immediately closes the socket after sending data; in this case the receiver may not get the data even though the send succeeded.
Note that if no value is given to the method, the argument will be assumed to be False
, and output buffering will be turned on for the HTTPClient object, which may be the opposite of what the programmer intends, therefore it's recommended to always pass an argument to this method.
If the socket is not connected when this call is made, then an internal flag is set and the TCP_NODELAY
option is enabled when the next connection is established. If the socket is connected, then if an error occurs setting the TCP_NODELAY
option on the socket, this method will return a non-zero error code; the actual error can be checked with the errno() function.
See also HTTPClient::getNoDelay().
HTTPClient::setNoDelay(softbool
$nodelay
= True) returns int
$httpclient.setNoDelay(True
);
Table 4.464. Arguments for HTTPClient::setNoDelay()
Argument | Description |
---|---|
| The |
Table 4.465. Return Value for HTTPClient::setNoDelay()
Return Type | Description |
---|---|
0 for success, non-zero for errors. To get error information, see errno() and strerror(). |
Returns the connection state of the HTTPClient object. Connections are implicitly established whenever a method is callde requiring a connection; to explicitly establish a connection, see HTTPClient::connect().
HTTPClient::isConnected() returns bool
my bool $connected = $httpclient.isConnected();
Table 4.466. Return Value for HTTPClient::isConnected()
Return Type | Description |
---|---|
The connection state of the HTTPClient object. |
Note: This class is not available with the PO_NO_NETWORK
parse option.
The XmlRpcClient class provides easy access to XML-RPC web services. This class inherits all public methods of the HTTPClient class. The inherited HTTPClient methods are not listed in this section, see the section on the HTTPClient class for more information on methods provided by the parent class. For low-level XML-RPC functions, see the XML-RPC functions in XML Functions.
The XmlRpcClient class understands the following protocols in addition to the protocols supported by the HTTPClient class:
Table 4.467. XmlRpcClient Class Protocols
Protocol | Default Port | SSL? | Description |
---|---|---|---|
| 80 | No | Unencrypted XML-RPC protocol over HTTP |
| 443 | Yes | XML-RPC protocol over HTTP with SSL/TLS encryption |
The XmlRpcClient supplies default values for HTTP headers as follows:
Table 4.468. XmlRpcClient Default, but Overridable Headers
Header | Default Value |
---|---|
|
|
|
|
|
|
|
|
Table 4.469. XmlRpcClient Class Method Overview
Method |
Except? |
Description |
---|---|---|
|
Y |
Creates the XmlRpcClient object based on the parameters passed. |
N |
Destroys the XmlRpcClient object and closes any open connections. | |
Y |
Copying objects of this class is not supported, an exception will be thrown. | |
| Y | Calls a remote method using a variable number of arguments for the method arguments and returns the response as qore data structure. |
| Y | Calls a remote method using a single value after the method name for the method arguments and returns the response as qore data structure. |
| Y | Same as the XmlRpcClient::call() except the first argument must be an lvalue reference, which is used as an output variable, where information about the HTTP request and response is written. |
| Y | Same as the XmlRpcClient::callArgs() except the first argument must be an lvalue reference, which is used as an output variable, where information about the HTTP request and response is written. |
| N | Sets a Queue object to receive HTTPClient and Socket events or clears the queue if no argument is passed. |
Creates the XmlRpcClient object based on the parameters passed and by default immediately attempts to establish a connection to the server (pass a boolean True
value as the second argument to establish a connection on demand). See HTTPClient::constructor() and HTTPClient::connect() for information on possible exceptions.
XmlRpcClient::constructor(softbool
$no_connect
= False)
XmlRpcClient::constructor(hash
$opts
, softbool $no_connect
= False)
my XmlRpcClient $xrc(("url":"http://hostname/RPC2"));
Table 4.470. Arguments for XmlRpcClient::constructor()
Argument | Description |
---|---|
| an option hash, see HTTPClient::constructor() Option Hash Keys for valid keys in this hash. |
| If this optional argument is passed with a value of |
Destroys the XmlRpcClient object and closes any open connections.
delete $xrc;
Copying objects of this class is not supported, an exception will be thrown.
Table 4.471. Exceptions thrown by XmlRpcClient::copy()
err |
desc |
---|---|
|
objects of this class may not be copied |
Calls a remote method using a variable number of arguments for the method arguments and returns the response as qore data structure. See HTTPClient::send(), makeXMLRPCCallString(), and parseXMLRPCResponse() for information on possible exceptions.
XmlRpcClient::call(string
$method
, ...) returns hash
$result = $xrc.call("method.name", $arg1, $arg2);
Table 4.472. Arguments for XmlRpcClient::call()
Argument | Description |
---|---|
| The XML-RPC method name to call |
| Optional arguments for the method. |
Table 4.473. Return Values for XmlRpcClient::call()
Return Type |
Description |
---|---|
If the call was successful, the response information will be found in the key 'params'. If an error occurred then the error information can be found under the 'fault' key. |
Calls a remote method using a single value after the method name for the method arguments and returns the response as qore data structure. See HTTPClient::send(), makeXMLRPCCallString(), and parseXMLRPCResponse() for information on possible exceptions.
XmlRpcClient::callArgs(string
$method
, any $args
) returns hash
$result = $xrc.callArgs("method.name", $arg_list);
Table 4.475. Return Values for XmlRpcClient::callArgs()
Return Type |
Description |
---|---|
If the call was successful, the response information will be found in the key 'params'. If an error occurred then the error information can be found under the 'fault' key. |
Like the XmlRpcClient::call() method, except requires an lvalue reference as the first argument that will be used as an output variable providing information about the HTTP request and response made to effect the XML-RPC call.
XmlRpcClient::callWithInfo(reference
$info
, string $method
, ...) returns hash
$result = $xrc.callWithInfo(\$info, "method.name", $arg1, $arg2);
Table 4.477. Return Values for XmlRpcClient::callWithInfo()
Return Type |
Description |
---|---|
If the call was successful, the response information will be found in the key 'params'. If an error occurred then the error information can be found under the 'fault' key. |
Like the XmlRpcClient::callArgs() method, except requires an lvalue reference as the first argument that will be used as an output variable providing information about the HTTP request and response made to effect the XML-RPC call.
XmlRpcClient::callArgsWithInfo(reference
$info
, string $method
, any $args
) returns hash
$result = $xrc.callArgsWithInfo(\$info, "method.name", $arg_list);
Table 4.478. Arguments for XmlRpcClient::callArgsWithInfo()
Argument | Description |
---|---|
| A reference to an lvalue that will be used as an output variable providing information about the HTTP request and response made to effect the XML-RPC call. |
| The XML-RPC method name to call |
| An optional list of arguments (or single argument) for the method. |
Table 4.479. Return Values for XmlRpcClient::callArgswithInfo()
Return Type |
Description |
---|---|
If the call was successful, the response information will be found in the key 'params'. If an error occurred then the error information can be found under the 'fault' key. |
Sets a Queue object to receive HTTPClient and Socket events. To remove the event queue and stop monitoring events, pass NOTHING
to the method. See Event Handling for more information.
XmlRpcClient::setEventQueue() returns nothing
XmlRpcClient::setEventQueue(Queue
$queue
) returns nothing
$xrc.setEventQueue($queue);
Note: This class is not available with the PO_NO_NETWORK
parse option.
The JsonRpcClient class provides easy access to JSON-RPC web services. This class inherits all public methods of the HTTPClient class. The inherited HTTPClient methods are not listed in this section, see the section on the HTTPClient class for more information on methods provided by the parent class. For low-level JSON-RPC functions, see the JSON-RPC functions in JSON Functions.
The JsonRpcClient class understands the following protocols in addition to the protocols supported by the HTTPClient class:
Table 4.481. JsonRpcClient Class Protocols
Protocol | Default Port | SSL? | Description |
---|---|---|---|
| 80 | No | Unencrypted JSON-RPC protocol over HTTP |
| 443 | Yes | JSON-RPC protocol over HTTP with SSL/TLS encryption |
The JsonRpcClient supplies default values for HTTP headers as follows:
Table 4.482. JsonRpcClient Default, but Overridable Headers
Header | Default Value |
---|---|
|
|
|
|
|
|
|
|
Table 4.483. JsonRpcClient Class Method Overview
Method |
Except? |
Description |
---|---|---|
|
N |
Creates the JsonRpcClient object based on the parameters passed. |
N |
Destroys the JsonRpcClient object and closes any open connections. | |
Y |
Copying objects of this class is not supported, an exception will be thrown. | |
|
Y |
Calls a remote method using a variable number of arguments for the method arguments and returns the response as qore data structure. |
|
Y |
Calls a remote method using a single value after the method name for the method arguments and returns the response as qore data structure. |
| Y | Same as the JsonRpcClient::call() except the first argument must be an lvalue reference, which is used as an output variable, where information about the HTTP request and response is written. |
| Y | Same as the JsonRpcClient::callArgs() except the first argument must be an lvalue reference, which is used as an output variable, where information about the HTTP request and response is written. |
| N | Sets a Queue object to receive HTTPClient and Socket events or clears the queue if no argument is passed. |
Creates the JsonRpcClient object based on the parameters passed and by default immediately attempts to establish a connection to the server (pass a boolean True
value as the second argument to establish a connection on demand). See HTTPClient::constructor() and HTTPClient::connect() for information on possible exceptions.
JsonRpcClient::constructor(softbool
$no_connect
= False)
JsonRpcClient::constructor(hash
$opts
, bool $no_connect
= False)
my JsonRpcClient $jrc(("url":"http://hostname/json"));
Table 4.484. Arguments for JsonRpcClient::constructor()
Argument | Description |
---|---|
| an option hash, see HTTPClient::constructor() Option Hash Keys for valid keys in this hash. |
| If this optional argument is passed with a value of |
Destroys the JsonRpcClient object and closes any open connections.
delete $jrc;
Copying objects of this class is not supported, an exception will be thrown.
Table 4.485. Exceptions thrown by JsonRpcClient::copy()
err |
desc |
---|---|
|
objects of this class may not be copied |
Calls a remote method using a variable number of arguments for the method arguments and returns the response as qore data structure. See HTTPClient::send(), makeJSONRPCRequestString(), and parseJSON() for information on possible exceptions.
JsonRpcClient::call(string
$method
, ...) returns any
$result = $jrc.call("method_name", $arg1, $arg2);
Table 4.486. Arguments for JsonRpcClient::call()
Argument | Description |
---|---|
| The JSON-RPC method name to call |
| Optional arguments for the method. |
Table 4.487. Return Values for JsonRpcClient::call()
Return Type |
Description |
---|---|
The information returned by the JSON-RPC method. |
Calls a remote method using a single value after the method name for the method arguments and returns the response as qore data structure. See HTTPClient::send(), makeJSONRPCRequestString(), and parseJSON() for information on possible exceptions.
JsonRpcClient::callArgs(string
$method
, any $args
) returns any
$result = $jrc.callArgs("method_name", $arg_list);
Table 4.489. Return Values for JsonRpcClient::callArgs()
Return Type |
Description |
---|---|
The information returned by the JSON-RPC method. |
Like the JsonRpcClient::call() method, except requires an lvalue reference as the first argument that will be used as an output variable providing information about the HTTP request and response made to effect the JSON-RPC call.
JsonRpcClient::callWithInfo(reference
$info
, string $method
, ...) returns any
$result = $jrc.callWithInfo(\$info, "method_name", $arg1, $arg2);
Table 4.491. Return Values for JsonRpcClient::callWithInfo()
Return Type |
Description |
---|---|
The information returned by the JSON-RPC method. |
Like the JsonRpcClient::callArgs() method, except requires an lvalue reference as the first argument that will be used as an output variable providing information about the HTTP request and response made to effect the JSON-RPC call.
JsonRpcClient::callArgsWithInfo(reference
$info
, string $method
, any $args
) returns any
$result = $jrc.callArgsWithInfo(\$info, "method_name", $arg_list);
Table 4.492. Arguments for JsonRpcClient::callArgsWithInfo()
Argument | Description |
---|---|
| A reference to an lvalue that will be used as an output variable providing information about the HTTP request and response made to effect the JSON-RPC call. |
| The JSON-RPC method name to call |
| An optional list of arguments (or single argument) for the method. |
Table 4.493. Return Values for JsonRpcClient::callArgsWithInfo()
Return Type |
Description |
---|---|
The information returned by the JSON-RPC method. |
Sets a Queue object to receive HTTPClient and Socket events. To remove the event queue and stop monitoring events, pass NOTHING
to the method. See Event Handling for more information.
JsonRpcClient::setEventQueue() returns nothing
JsonRpcClient::setEventQueue(Queue
$queue
) returns nothing
$jrc.setEventQueue($queue);
SSLPrivateKey objects are containers for private key data.
Table 4.495. SSLPrivateKey Class Method Overview
Method |
Except? |
Description |
---|---|---|
|
Y |
Creates the SSLPrivateKey object from the data argument passed; as a deprecated, backwards-compatibilty extension, if the string variant is used and a string less then 120 bytes long is passed, it is taken as a filename to use to load the private key data from in PEM format. In this case |
N |
Destroys the SSLPrivateKey object. | |
Y |
Copying objects of this class is not supported, an exception will be thrown. | |
|
N |
Returns the algorithm used for the private key. |
|
N |
Returns the version of the private key. |
|
N |
Returns the bit length of the private key. |
|
N |
Returns a hash of all information for the private key. |
Creates the SSLPrivateKey object from the data argument passed.
As a deprecated, backwards-compatibilty extension, if the string variant is used and a string less then 120 bytes long is passed, it is taken as a filename to use to load the private key data from in PEM format. In this case PO_NO_FILESYSTEM
is checked at run-time; if set, and exception is thrown. Do not use this feature; load the file first and pass the data to the constructor instead. This functionality will be removed in a future release of Qore.
SSLPrivateKey::constructor(string
$key_pem
, string $pass
= "")
SSLPrivateKey::constructor(binary
$key_der
)
my SSLPrivateKey $pkey($data);
Table 4.497. Exceptions thrown by SSLPrivateKey::constructor()
err |
desc |
---|---|
|
invalid format, invalid or missing password, etc |
Copying objects of this class is not supported, an exception will be thrown.
Table 4.498. Exceptions thrown by SSLPrivateKey::copy()
err |
desc |
---|---|
|
objects of this class may not be copied |
Returns a string giving the algorithm used for the private key.
SSLPrivateKey::getType() returns string
$str = $pkey.getType();
Table 4.499. Return Values for SSLPrivateKey::getType()
Return Type |
Description |
---|---|
Returns values include: RSA, RSA2, DSA, DSA1, DSA2, DSA3, DSA4, DH, and unknown |
Returns the version of the private key as an integer.
SSLPrivateKey::getVersion() returns int
$int = $pkey.getVersion();
Table 4.500. Return Values for SSLPrivateKey::getVersion()
Return Type |
Description |
---|---|
The version of the private key. |
Returns the bit length of the private key.
SSLPrivateKey::getBitLength() returns int
$int = $pkey.getBitLength();
Table 4.501. Return Values for SSLPrivateKey::getBitLength()
Return Type |
Description |
---|---|
The bit length of the private key. |
SSLPrivateKey::getInfo() returns hash
SSLPrivateKey::getInfo()
$hash = $pkey.getInfo();
Table 4.502. Return Values for SSLPrivateKey::getInfo()
Return Type |
Description |
---|---|
Keys are 'type', 'version', and 'bitLength' corresponding to the algorithm type, the version, and the bit length of the key respectively. |
SSLCertificate objects are designed to work with X.509 certificate data.
Table 4.503. SSLCertificate Class Method Overview
Method |
Except? |
Description |
---|---|---|
|
Y |
Creates the SSLCertificate object from the filename argument passed; as a deprecated, backwards-compatibilty extension, if the string variant is used and a string less then 200 bytes long is passed, it is taken as a filename to use to load the private key data from in PEM format. In this case |
N |
Destroys the SSLCertificate object. | |
Y |
Copying objects of this class is not supported, an exception will be thrown. | |
|
N |
Returns a string in PEM format representing the certificate. |
|
N |
Returns the version of the certificate. |
|
N |
Returns the signature type of the certificate. |
|
N |
Returns a binary object representing the signature of the certificate. |
|
N |
Returns name of the public key algorithm of the certificate. |
|
N |
Returns a binary object representing the public key of the certificate in DER (Distinguished Encoding Rules) format or NOTHING if the public key cannot be retrieved. |
|
N |
Returns a hash of strings representing the subject information of the certificate. |
|
N |
Returns a hash of strings representing the issuer information of the certificate. |
|
N |
Returns the integer serial number of the certificate. |
|
N |
Returns a hash of booleans representing the allowed purposes of the certificate. |
|
N |
Returns a date/time value representing the start date of the certificate. |
|
N |
Returns a date/time value representing the end date of the certificate. |
|
N |
Returns a hash of all information for the certificate. |
Creates the SSLCertificate object from the argument passed. If a string is passed, the value is assumed to be the PEM representation of the certificate; if a binary is passed, the value is assumed to be the DER-encoded form of the certificate.
DEPRECATED: If a string is passed that is less than 200 bytes long, the string is assumed to be a file name; in which case the PO_NO_FILESYSTEM
parse option is checked at run-time; if this restriction is not set, then the certificate is loaded from the filename (in this case, the certificate must be in PEM format). Do not use this feature; load the file first and pass the data to the constructor instead. This functionality will be removed in a future release of Qore.
SSLCertificate::constructor(string
$cert_pem
)
SSLCertificate::constructor(binary
$cert_der
)
my SSLCertificate $cert($pem_cert_string);
Table 4.505. Exceptions thrown by SSLCertificate::constructor()
err |
desc |
---|---|
|
missing or invalid argument, unable to parse file, etc |
Copying objects of this class is not supported, an exception will be thrown.
Table 4.506. Exceptions thrown by SSLCertificate::copy()
err |
desc |
---|---|
|
objects of this class may not be copied |
Returns a string in PEM format representing the certificate.
SSLCertificate::getPEM() returns string
$pem_str = $cert.getPEM();
Table 4.507. Return Values for SSLCertificate::getPEM()
Return Type |
Description |
---|---|
A string in PEM format representing the certificate. |
Returns the version of the certificate as an integer.
SSLCertificate::getVersion() returns int
$int = $cert.getVersion();
Table 4.508. Return Values for SSLCertificate::getVersion()
Return Type |
Description |
---|---|
The version of the certificate. |
Returns the signature type of the certificate.
SSLCertificate::getSignatureType() returns string
$str = $cert.getSignatureType();
Table 4.509. Return Values for SSLCertificate::getSignatureType()
Return Type |
Description |
---|---|
The signature type of the certificate. |
Returns a binary object representing the signature of the certificate.
SSLCertificate::getSignature() returns binary
$bin = $cert.getSignature();
Table 4.510. Return Values for SSLCertificate::getSignature()
Return Type |
Description |
---|---|
The signature data for the certificate. |
Returns name of the public key algorithm of the certificate.
SSLCertificate::getPublicKeyAlgorithm() returns string
$str = $cert.getPublicKeyAlgorithm();
Table 4.511. Return Values for SSLCertificate::getPublicKeyAlgorithm()
Return Type |
Description |
---|---|
The name of the public key algorithm of the certificate. |
Returns a binary object representing the public key of the certificate in DER (Distinguished Encoding Rules) format.
SSLCertificate::getPublicKey() returns any
$bin = $cert.getPublicKey();
Table 4.512. Return Values for SSLCertificate::getPublicKey()
Return Type |
Description |
---|---|
The public key of the certificate in DER format. |
Returns a hash of strings representing the subject information of the certificate.
SSLCertificate::getSubjectHash() returns hash
$hash = $cert.getSubjectHash();
Table 4.513. Return Values for SSLCertificate::getSubjectHash()
Return Type |
Description |
---|---|
Key-value pairs representing the subject information of the certificate. |
Returns a hash of strings representing the issuer information of the certificate.
SSLCertificate::getIssuerHash() returns hash
$hash = $cert.getIssuerHash();
Table 4.514. Return Values for SSLCertificate::getIssuerHash()
Return Type |
Description |
---|---|
Key-value pairs representing the issuer information of the certificate. |
Returns the integer serial number of the certificate.
SSLCertificate::getSerialNumber() returns int
$hash = $cert.getIssuerHash();
Table 4.515. Return Values for SSLCertificate::getSerialNumber()
Return Type |
Description |
---|---|
The serial number of the certificate. |
Returns a hash of booleans representing the allowed purposes of the certificate.
SSLCertificate::getPurposeHash() returns hash
$hash = $cert.getPurposeHash();
Table 4.516. Return Values for SSLCertificate::getPurposeHash()
Return Type |
Description |
---|---|
Key-value pairs representing the allowed purposes of the certificate. |
Returns a date/time value representing the start date of the certificate.
SSLCertificate::getNotBeforeDate() returns date
$date = $cert.getNotBeforeDate();
Table 4.517. Return Values for SSLCertificate::getNotBeforeDate()
Return Type |
Description |
---|---|
The start date of the certificate. |
Returns a date/time value representing the end date of the certificate.
SSLCertificate::getNotAfterDate() returns date
$date = $cert.getNotAfterDate();
Table 4.518. Return Values for SSLCertificate::getNotAfterDate()
Return Type |
Description |
---|---|
The end date of the certificate. |
Returns a hash of all information for the certificate.
SSLCertificate::getInfo() returns hash
$hash = $cert.getInfo();
Table 4.519. Return Values for SSLCertificate::getInfo()
Return Type |
Description |
---|---|
Keys are 'version', 'serialNumber', 'subject', 'issuer', 'purposes', 'notBefore', 'notAfter', 'signatureType', 'signature', and 'publicKey' corresponding to the respective attributes of the certificate. |
The TimeZone class provides access to time zone functionality.
TimeZone objects based on zoneinfo region files can have daylight savings time information; those based on UTC offsets have none.
Table 4.520. TimeZone Method Overview
Method | Except? | Description |
---|---|---|
| Y | Creates the TimeZone object based on the region name (ex: "America/Chicago") or the number of seconds east of UTC (3600 = UTC +01). |
N | Destroys the TimeZone object. | |
N | Creates a copy of the TimeZone object. | |
| N | Returns the number of seconds east of UTC for the zone; negative numbers indicate a zone west of UTC. |
| N | Returns |
| N | Returns the region name as a string; if the current zone is based on a UTC offset, then the UTC offset is returned as a string like "+01:00". |
| N | Returns the equivalent date in the current time zone; when using integer arguments, offsets are in seconds and microseconds from 1970-01-01Z. |
| N | Returns a date in the object's zone based on an offset in milliseconds from 1970-01-01Z. |
| N | Returns a date in the object's zone based on an offset in microseconds from 1970-01-01Z. |
| N | Returns the default time zone for the current execution context. |
| N | Sets the default time zone for the current execution context. |
| N | Sets the default time zone for the current execution context based on the number of seconds east of UTC; for zones west of UTC, use negative numbers. |
| Y | Sets the default time zone for the current execution context from a zoneinfo region file; if there are errors reading or parsing the file, an exception is thrown. |
Creates the TimeZone object based on the region name (ex: "America/Chicago") or the UTC offset passed as the number of seconds east of UTC for the zone.
TimeZone::constructor(string
$region
)
TimeZone::constructor(softint
$secs_east
)
my TimeZone $tz("Europe/Prague");
Table 4.522. Exceptions Thrown by TimeZone::constructor()
err | desc |
---|---|
| Unable to read zoneinfo file; invalid file magic; error parsing zoneinfo file, etc |
Creates a copy of the TimeZone object.
my TimeZone $newzone = $tz.copy();
Returns the number of seconds east of UTC for the zone; negative numbers indicate a zone west of UTC.
TimeZone::UTCOffset() returns int
my int $offset = $tz.UTCOffset();
Table 4.523. Return Values for TimeZone::UTCOffset()
Return Type |
Description |
---|---|
Returns the number of seconds east of UTC for the zone; negative numbers indicate a zone west of UTC. |
Returns True
if the current zone has daylight saving's time rules, False
if not. TimeZone objects based on zoneinfo region files can have (but do not necessarily have) daylight savings time information; those based on UTC offsets have none.
TimeZone::hasDST() returns bool
my bool $hasdst = $tz.hasDST();
Table 4.524. Return Values for TimeZone::hasDST()
Return Type |
Description |
---|---|
Returns |
Returns the region name as a string; if the current zone is based on a UTC offset, then the UTC offset is returned as a string like "+01:00".
TimeZone::region() returns string
my string $region = $tz.region();
Table 4.525. Return Values for TimeZone::region()
Return Type |
Description |
---|---|
Returns the region name as a string; if the current zone is based on a UTC offset, then the UTC offset is returned as a string like "+01:00". |
Returns the equivalent date in the current time zone; when using integer arguments, offsets are in seconds and microseconds from 1970-01-01Z.
TimeZone::date(softint
$secs
, softint $us
= 0) returns date
TimeZone::date(date
$date
) returns date
my date $dt = $tz.date($other);
Table 4.527. Return Values for TimeZone::date()
Return Type |
Description |
---|---|
Returns the equivalent date in the current time zone; when using integer arguments, offsets are in seconds and microseconds from 1970-01-01Z. |
Returns a date in the object's zone based on an offsets in milliseconds from 1970-01-01Z.
TimeZone::dateMs(softint
$ms
) returns date
my date $dt = $tz.dateMs($ms);
Table 4.528. Return Values for TimeZone::dateMs()
Return Type |
Description |
---|---|
Returns a date in the object's zone based on an offsets in milliseconds from 1970-01-01Z. |
Returns a date in the object's zone based on an offset in microseconds from 1970-01-01Z.
TimeZone::dateUs(softint
$us
) returns date
my date $dt = $tz.dateUs($us);
Table 4.529. Return Values for TimeZone::dateUs()
Return Type |
Description |
---|---|
Returns a date in the object's zone based on an offset in microseconds from 1970-01-01Z. |
Returns the default time zone for the current execution context.
static TimeZone::get() returns TimeZone
my TimeZone $tz = TimeZone::get();
Table 4.530. Return Values for TimeZone::get()
Return Type |
Description |
---|---|
Returns the default time zone for the current execution context. |
Sets the default time zone for the current execution context.
See also Program::setTimeZone().
static TimeZone::set(TimeZone
$zone
) returns nothing
TimeZone::set($zone);
Table 4.531. Arguments for TimeZone::set()
Argument | Description |
---|---|
| The default time zone to set for the current execution context. |
Sets the default time zone for the current execution context 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 TimeZone::setRegion() instead.
See also Program::setTimeZoneUTCOffset().
static TimeZone::setUTCOffset(softint
$secs_east
) returns nothing
The following examples are all equivalent, setting the time zone to +02 UTC:
TimeZone::setUTCOffset(7200);
TimeZone::setUTCOffset(2h);
TimeZone::setUTCOffset(PT2H);
Table 4.532. Arguments for TimeZone::setUTCOffset()
Argument | Description |
---|---|
| The number of seconds east of UTC; for zones west of UTC, use negative numbers |
Sets the default time zone for the current execution context from a zoneinfo region file; if there are errors reading or parsing the file, an exception is thrown.
See also Program::setTimeZoneRegion().
static TimeZone::setRegion(string
$region
) returns nothing
TimeZone::setRegion("Europe/Prague");
Not available with PO_NO_LOCALE_CONTROL
Table 4.533. Arguments for TimeZone::setRegion()
Argument | Description |
---|---|
| The region name for the time zone (ex: "America/Chicago"); if the zoneinfo file for the region cannot be found or parsed, then an exception is thrown. |
Table 4.534. Exceptions Thrown by TimeZone::setRegion()
err | desc |
---|---|
| Unable to read zoneinfo file; invalid file magic; error parsing zoneinfo file, etc |
Table 4.535. Database Driver Constants in the SQL Namespace
Constant | Value | Description |
---|---|---|
|
| Indicates that the |
|
| Indicates that the |
|
| Indicates that the |
|
| Indicates that the |
|
| Indicates that the |
|
| Indicates that the |
|
| Indicates that the |
Table 4.536. Placeholder Bind Constants in the SQL Namespace
Constant | Description |
---|---|
SQL::VARCHAR | Indicates that the placeholder buffer should be a string buffer |
SQL::CLOB | Indicates that the placeholder buffer should be a CLOB string buffer. |
SQL::BLOB | Indicates that the placeholder buffer should be a binary buffer. |
SQL::DATE | Indicates that the placeholder buffer should be a date-time buffer. |
Table 4.537. DBI Capability Constant Codes in the SQL Namespace
Constant | Description |
---|---|
SQL::DBI_CAP_CHARSET_SUPPORT | Indicates that the DBI driver supports proper character encoding conversions. |
SQL::DBI_CAP_TRANSACTION_MANAGEMENT | Indicates that the DBI driver supports transaction management. |
SQL::DBI_CAP_STORED_PROCEDURES | Indicates that the DBI driver supports stored procedure execution. |
SQL::DBI_CAP_LOB_SUPPORT | Indicates that the DBI driver supports *LOB columns. |
SQL::DBI_CAP_BIND_BY_VALUE | Indicates that the DBI driver supports directly binding qore values into queries using the %v placeholder in the query string. |
SQL::DBI_CAP_BIND_BY_PLACEHOLDER | Indicates that the DBI driver supports binding placeholder buffers when executing SQL to retrieve data from queries and procedures, etc. |
Note: This class is not available with the PO_NO_DATABASE
parse option.
The Datasource class is the high-level Qore interface to Qore's DBI layer, and as such, Datasource objects allow Qore programs to access databases that have a Qore DBI driver. The Datasource class will attempt to load any DBI driver that is not currently loaded in the constructor. For connection pooling support, see the DatasourcePool class.
Datasource objects will implicitly call Datasource::open() if no connection has yet been established and a method is called requiring a connection to the database server. Therefore any method that requires communication with the database server can also throw any exception that the open method can throw.
Some Qore DBI drivers allow "select" queries to be executed through the Datasource::exec() method, and allow SQL commands (procedure calls, etc) to be executed through the Datasource::select() method, and some DBI drivers do not (depends on the underlying DB API). At any rate, the transaction lock is set when auto-commit is disabled and when the Datasource::exec() or Datasource::beginTransaction() methods are executed as documented above. Therefore executing a transaction relevant command through the Datasource::select() method while auto-commit mode is disabled and a transaction has not yet started will not result in the transaction lock being allocated to the current thread and therefore could cause transaction errors when sharing the Datasource object between multiple threads.
Only databases with an existing Qore DBI driver can be accessed through the Qore Datasource class.
All Qore DBI drivers set new connections to use transaction isolation level "read committed".
The Datasource class provides consistent, high-level, per-connection locking on requests at a level above the DBI drivers to ensure that the communication between clients and servers is properly serialized.
All Datasource methods accepting SQL strings to execute understand a special syntax used in the query string to bind Qore data by value and to specify placeholders for output variables (for example, when executing a stored procedure or database function). Placeholder binding is DBI driver specific, but binding by value is supported with the same syntax in all drivers. Additionally, the %d
numeric specifier is supported equally in all Qore DBI drivers.
Table 4.538. Datasource Format Specifiers
Format Specification | Description |
---|---|
| If any value other than NOTHING or NULL is given, then the value is converted to an integer and this value is substituted in the string at this position; if the value is NOTHING or NULL, then a literal 'null' is substituted instead. |
| The argument is converted to a string and the string is inserted literally without any conversion or escape sequences in the string; this is useful for table or schema prefixes, etc |
| The argument is bound by value according to the DBI driver's implementation. |
To bind qore data values directly in a binary format in an SQL command, use %v
in the command string, and include the value as an argument after the string. Binding by value means that Qore's DBI driver will take care of formatting the data properly for use in the query with the database server. That means that strings do not need to be quoted, date/time values do not need special formatting, binary object (with BLOB columns, for example) can be used directly in queries, etc.
Here is an example:
$rows = $pool.exec("insert into table (varchar_col, timestamp_col, blob_col, numeric_col) values (%v, %v, %v, %d)", $string, now(), $binary, 100);
To insert a numeric value or a literal 'null' in a query, use %d
in the command string, and include the value as an argument after the string. If the value is NOTHING or NULL, a literal 'null' will be written to the string; otherwise the argument is converted to a floating-point value or integer if necessary and written to the string. This is useful for working with DECIMAL (NUMERIC, NUMBER) types in a database-independent way; for example PostgreSQL servers do not do type conversions to DECIMAL types when a string, integer, or float is bound by value, therefore to ensure that integral decimal values can be used in a database-independent way (with 'null' substitution when no value is bound), it's best to use the %d
code in the command string instead of %v
.
For binding placeholders for output variables, write a unique name in the string and prefix it with a colon (ex: :code
). In this case the method will return a hash of the output variables using the placeholder names as keys, but without the colon prefix. By default, a string type will be bound to the position. To bind other variable types to placeholder positions, include the type constant (see Type Constants) as an argument after the command string. For BLOBs, use Binary, for CLOBs, use the string "clob" (constants will be provided in a future release). Not all DBI drivers require placeholder buffer specifications; see the documentation for the DBI driver in question for more information and examples regarding placeholder buffer specifications.
Datasource objects have an internal transaction lock which will be grabbed when the Datasource::exec(), Datasource::vexec() Datasource::execRaw(), or Datasource::beginTransaction() methods are executed and autocommit is not enabled. This enables a single datasource to be safely used for transaction management by several threads simultaneously. Note that an exception in a Datasource method that would acquire the lock (such as the Datasource::exec() method) when it's not already held, will have the effect that the transaction lock is not acquired.
Any thread attempting to do transaction-relevant actions on a Datasource with auto-commit disabled while a transaction is in progress by another thread will block until the thread currently executing a transaction executes the Datasource::commit() or Datasource::rollback() methods (or the Datasource is deleted, reset, or closed, in which case the lock is released and an exception is raised as well).
There is a timeout associated with the transaction lock; if a thread waits for the transaction lock for more than the timeout period, then an exception will be raised in the waiting thread. The timeout value can be read and changed with the Datasource::getTransactionLockTimeout() and Datasource::setTransactionLockTimeout() methods, respectively. The default transaction lock timeout value is 120 seconds.
Table 4.539. SQL::Datasource Method Overview
Method | Except? | Description |
---|---|---|
| Y | Creates the Datasource object; attempts to load a DBI driver if the driver is not already present in Qore. |
Y | Destroys the object. | |
N | Creates a new Datasource object with the same driver as the original and copies of all the connection parameters. | |
| Y | Opens a connection to a database; an exception is thrown if any errors occur. |
| N | Closes the connection to the database; an exception is thrown if any errors occur. |
| Y | Commits the transaction and releases the transaction lock; an exception is thrown if any errors occur. |
| Y | Rolls back the transaction and releases the transaction lock; an exception is thrown if any errors occur. |
| N | Turns autocommit on or off for this object. |
| Y | Executes SQL code on the DB connection. |
| Y | Executes SQL code (like Datasource::exec()) on the DB connection without any variable binding. |
| Y | Executes SQL code on the DB connection, taking a list for all bind arguments. |
| Y | Executes a select statement on the server and returns the results in a hash (column names) of lists (rows). |
| Y | Executes a select statement on the server and returns the results in a hash (column names) of lists (rows), taking a list for all bind arguments. |
| Y | Executes a select statement on the server and returns the first row as a hash (column names and values). |
| Y | Executes a select statement on the server and returns the first row as a hash (column names and values), taking a list for all bind arguments. |
| Y | Executes a select statement on the server and returns the results in a list (rows) of hashes (column names and values). |
| Y | Executes a select statement on the server and returns the results in a list (rows) of hashes (column names and values), taking a list for all bind arguments. |
| Y | Manually grabs the transaction lock |
| N | Sets the username parameter for the next open. |
| N | Returns the username parameter as a string or NOTHING if none is set. |
| N | Sets the password parameter for the next open. |
| N | Returns the password parameter as a string or NOTHING if none is set. |
| N | Sets the DB name parameter for the next open. |
| N | Returns the dbname parameter as a string or NOTHING if none is set. |
| N | Sets the charset (encoding) parameter for the next open. |
| N | Returns the DBI driver specific charset name for the current connection as a string or NOTHING if none is set. |
| N | Returns the Qore charset name for the current connection as a string or |
| N | Sets the hostname parameter for the next open. |
| N | Returns the hostname parameter as a string or NOTHING if none is set. |
| N | Sets the port parameter for the next open. |
| N | Returns the port parameter as an int or NOTHING if none is set. |
| N | Returns the name of the driver used for the object. |
| N | Sets the transaction lock timeout value in milliseconds. Set to 0 for no timeout. |
| N | Retrieves the transaction lock timeout value as an integer in milliseconds. |
| Y | Returns the driver-specific server version data for the current connection. |
| Y | Returns the driver-specific client library version data. Not implemented by all drivers. |
| N | Returns |
Creates a Datasource object. The constructor variant taking separate arguments requires the datasource type as the first argument, while most other parameters are optional.
Datasource::constructor(string
$driver
, string $user
= "", string $pass
= "", string $dbname
= "", string $encoding
= "", string $host
= "", softint $port
= 0)
Datasource::constructor(hash
$params
)
my Datasource $db(DSPGSQL, "user", "pass", "database", "utf8", "localhost", 5432);
Table 4.540. Arguments for Datasource::constructor(string $driver, string $user = "", string $pass = "", $dbname = "", string $encoding = "", string $host = "", softint $port = 0) Variant
Argument | Description |
---|---|
| The name of the DBI driver for the Datasource. See SQL Constants for builtin constants for DBI drivers shipped with Qore, or see the DBI driver documentation to use an add-on driver. |
| The user name for the new connection. Also see Datasource::setUserName() for a method that allows this parameter to be set after the constructor. |
| The password for the new connection. Also see Datasource::setPassword() for a method that allows this parameter to be set after the constructor. |
| The database name for the new connection. Also see Datasource::setDBName() for a method that allows this parameter to be set after the constructor. |
| The database-specific name of the character encoding to use for the new connection. Also see Datasource::setDBCharset() for a method that allows this parameter to be set after the constructor. If no value is passed for this parameter, then the database character encoding corresponding to the default character encoding for the Qore process will be used instead. |
| The host name for the new connection. Also see Datasource::setHostName() for a method that allows this parameter to be set after the constructor. |
| The port number for the new connection. Also see Datasource::setPort() for a method that allows this parameter to be set after the constructor. |
Table 4.541. Arguments for Datasource::constructor(hash $params) Variant
Argument | Description |
---|---|
| A hash of parameters for the Datasource; see Datasource Constructor Hash for more information. |
Table 4.542. Datasource Constructor Hash
Key | Type | Description |
---|---|---|
| The name of the database driver to use; this key is mandatory; if not present, an exception will be raised. See SQL Constants for builtin constants for DBI drivers shipped with Qore, or see the DBI driver documentation to use an add-on driver. | |
| The user name for the new connection. Also see Datasource::setUserName() for a method that allows this parameter to be set after the constructor. | |
| The password for the new connection. Also see Datasource::setPassword() for a method that allows this parameter to be set after the constructor. | |
| The database name for the new connection. Also see Datasource::setDBName() for a method that allows this parameter to be set after the constructor. | |
| The database-specific name of the character encoding to use for the new connection. Also see Datasource::setDBCharset() for a method that allows this parameter to be set after the constructor. If no value is passed for this parameter, then the database character encoding corresponding to the default character encoding for the Qore process will be used instead. | |
| The host name for the new connection. Also see Datasource::setHostName() for a method that allows this parameter to be set after the constructor. | |
| The port number for the new connection. Also see Datasource::setPort() for a method that allows this parameter to be set after the constructor. If this key is present and is 0 then an exception will be raised. |
Table 4.543. Exceptions Thrown by Datasource::constructor()
err | desc |
---|---|
| Missing DBI driver identifier as first argument. |
| Could not load a driver for the database identified. |
Closes the datasource if it's open (if any operations are in progress, will block until the operations complete) and destroys the object.
delete $db;
Table 4.544. Exceptions Thrown by Datasource::destructor()
err | desc |
---|---|
| The Datasource was destroyed while a transaction was still in progress; the transaction will be automatically rolled back. |
Creates a new Datasource object with the same driver as the original and copies of all the connection parameters.
my Datasource $new_ds = $ds.copy();
Manually grabs the transaction lock. This method should be called when the Datasource object will be shared between more than 1 thread, and a transaction will be started with a Datasource::select() method.
Datasource::beginTransaction() returns nothing
$db.beginTransaction();
Table 4.545. Exceptions Thrown by Datasource::beginTransaction()
err | desc |
---|---|
| Cannot start a transaction when autocommit is enabled. |
| Timeout trying to acquire the transaction lock. |
Opens a connection to the datasouce, using the connection parameters already set. If any errors are encountered, an exception is raised.
Datasource::open() returns nothing
$db.open();
Table 4.546. Exceptions Thrown by Datasource::open()
err | desc |
---|---|
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Closes the connection to the database. If any actions are in progress on the database, the close call will block until the actions complete. If any errors are encountered, an exception is raised.
Datasource::close() returns nothing
$db.close();
Commits the current transaction and releases the transaction lock.
Datasource::commit() returns nothing
$db.commit();
Table 4.547. Exceptions Thrown by Datasource::commit()
err | desc |
---|---|
| Timeout trying to acquire the transaction lock. |
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Returns True
if the Datasource is currently in a transaction (has the transaction lock allocated to the calling thread), False
if not.
Datasource::inTransaction() returns bool
my bool $is_trans = $db.inTransaction();
Table 4.548. Return Value for Datasource::inTransaction()
Return Type | Description |
---|---|
Returns |
Rolls back the current transaction and releases the transaction lock.
Datasource::rollback() returns nothing
$db.rollback();
Table 4.549. Exceptions Thrown by Datasource::rollback()
err | desc |
---|---|
| Timeout trying to acquire the transaction lock. |
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Turns autocommit on or off for this object.
Datasource::setAutoCommit(softbool
$b
= True) returns nothing
$db.setAutoCommit(False
);
Table 4.550. Arguments for Datasource::setAutoCommit()
Argument | Description |
---|---|
| True to turn on autocommit (a commit will be executed after every Datasource::exec()), |
Grabs the transaction lock (if autocommit is disabled) and executes an SQL command on the server and returns either the row count (for example, for updates and inserts) or the data retrieved (for example, if a stored procedure is executed that returns values).
Datasource::exec(string
$sql
, ...) returns any
Datasource::exec() returns nothing (RT_NOOP)
$rows = $db.exec("insert into table (varchar_col, timestamp_col, blob_col, numeric_col) values (%v, %v, %v, %d)", $string, now(), $binary, 100);
Table 4.551. Arguments for Datasource::exec()
Argument | Description |
---|---|
| The SQL command to execute on the server. |
| Include any values to be bound (using |
Table 4.552. Return Values for Datasource::exec()
Return Type | Description |
---|---|
The return value depends on the DBI driver; normally, for commands with placeholders, a hash is returned holding the values acquired from executing the SQL statement. For all other commands, normally an int row count is returned. However, some DBI drivers also allow select statements to be executed through this interface, which would also return a hash of list. |
Table 4.553. Exceptions Thrown by Datasource::exec()
err | desc |
---|---|
| Timeout trying to acquire the transaction lock. |
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Grabs the transaction lock (if autocommit is disabled) and executes an SQL command on the server and returns either the row count (for example, for updates and inserts) or the data retrieved (for example, if a stored procedure is executed that returns values).
This method does not do any variable binding, so it's useful for example for DDL statements etc.
Using this method for OLTP statements can affect the application performance. See used DB server documentation for variable binding.
Datasource::execRaw(string
$sql
) returns any
$rows = $db.exec("create table my_tab (id number, some_text varchar2(30))");
Table 4.554. Arguments for Datasource::execRaw()
Argument | Description |
---|---|
| The SQL command to execute on the server. |
Table 4.556. Exceptions Thrown by Datasource::execRaw()
err | desc |
---|---|
| Timeout trying to acquire the transaction lock. |
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Same as the Datasource::exec() method, except this method takes a single argument after the SQL command giving the list of bind parameters.
Datasource::vexec(string
$sql
, list $args
) returns any
Datasource::vexec(string
$sql
) returns any
Datasource::vexec() returns nothing (RT_NOOP)
$rows = $db.vexec("insert into example_table value (%v, %v, %v)", $arg_list);
Table 4.558. Return Values for Datasource::vexec()
Return Type | Description |
---|---|
The return value depends on the DBI driver; normally, for commands with placeholders, a hash is returned holding the values acquired from executing the SQL statement. For all other commands, normally an int row count is returned. However, some DBI drivers also allow select statements to be executed through this interface, which would also return a hash of list. |
Table 4.559. Exceptions Thrown by Datasource::vexec()
err | desc |
---|---|
| Timeout trying to acquire the transaction lock. |
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Executes an SQL select statement on the server and returns the result as a hash (column names) of lists (rows). This format is suitable for use with context Statements, for easy iteration and processing of query results. Additionally, this format is more efficient format than that returned by the Datasource::selectRows() method, because the column names are not repeated for each row returned. Therefore, for retrieving anything greater than small amounts of data, it is recommended to use this method instead of Datasource::selectRows().
Datasource::select(string
$sql
, ...) returns any
Datasource::select() returns nothing (RT_NOOP)
# bind a string and a date/time value by value in a query $query = $db.select("select * from table where varchar_column = %v and timestamp_column > %v", $string, 2007-10-11T15:31:26.289);
Table 4.560. Arguments for Datasource::select()
Argument | Description |
---|---|
| The SQL select command to execute on the server. |
| Include any values to be bound (using |
Table 4.562. Exceptions Thrown by Datasource::select()
err | desc |
---|---|
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Same as the Datasource::select() method, except this method takes a single argument after the SQL command giving the list of bind value parameters.
Datasource::vselect(string
$sql
, list $args
) returns any
Datasource::vselect(string
$sql
) returns any
Datasource::vselect() returns nothing (RT_NOOP)
$query = $db.vselect("select * from example_table where id = %v and name = %v", $arg_list);
Table 4.565. Exceptions Thrown by Datasource::vselect()
err | desc |
---|---|
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Executes an SQL select statement on the server and returns the first row as a hash (the column values). If more than one row is returned, then all but the first row are discarded. For a similar method taking a list for all bind arguments, see Datasource::vselectRow().
This method also accepts all bind parameters (%d, %v, etc) as documented in Datasource Binding.
Datasource::selectRow(string
$sql
, ...) returns any
Datasource::selectRow() returns nothing (RT_NOOP)
$list = $db.selectRow("select * from example_table");
Table 4.566. Arguments for Datasource::selectRow()
Argument | Description |
---|---|
| The SQL select command to execute on the server. |
| Include any values to be bound (using |
Table 4.568. Exceptions Thrown by Datasource::selectRow()
err | desc |
---|---|
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Same as the Datasource::selectRow() method, except this method takes a single argument after the SQL command giving the list of bind value parameters.
Datasource::vselectRow(string
$sql
, list $args
) returns any
Datasource::vselectRow(string
$sql
) returns any
Datasource::vselectRow() returns nothing (RT_NOOP)
$list = $db.vselectRow("select * from example_table where id = %v and name = %v", $arg_list);
Table 4.571. Exceptions Thrown by Datasource::vselectRow()
err | desc |
---|---|
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Executes an SQL select statement on the server and returns the result as a list (rows) of hashes (the column values). This format is not as efficient as that returned by the Datasource::select() method, therefore for larger amounts of data, it is recommended to use Datasource::select().
This method also accepts all bind parameters (%d, %v, etc) as documented in Datasource Binding.
Datasource::selectRows(string
$sql
, ...) returns any
Datasource::selectRows() returns nothing (RT_NOOP)
$list = $db.selectRows("select * from example_table");
Table 4.572. Arguments for Datasource::selectRows()
Argument | Description |
---|---|
| The SQL select command to execute on the server. |
| Include any values to be bound (using |
Table 4.573. Return Values for Datasource::selectRows()
Return Type | Description |
---|---|
Normally returns a list (rows) of hash (where the keys are the column names of each row) or nothing if no rows are found for the query. However, DBI could return other types; for DBI drivers that allow executing generic SQL through this method, any result sets returns should also be in the format list (rows) of hash. |
Table 4.574. Exceptions Thrown by Datasource::selectRows()
err | desc |
---|---|
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Same as the Datasource::selectRows() method, except this method takes a single argument after the SQL command giving the list of bind value parameters.
Datasource::vselectRows(string
$sql
, list $args
) returns any
Datasource::vselectRows(string
$sql
) returns any
Datasource::vselectRows() returns nothing (RT_NOOP)
$list = $db.vselectRows("select * from example_table where id = %v and name = %v", $arg_list);
Table 4.576. Return Values for Datasource::vselectRows()
Return Type | Description |
---|---|
Normally returns a list (rows) of hash (where the keys are the column names of each row) or nothing if no rows are found for the query. However, DBI could return other types; for DBI drivers that allow executing generic SQL through this method, any result sets returns should also be in the format list (rows) of hash. |
Table 4.577. Exceptions Thrown by Datasource::vselectRows()
err | desc |
---|---|
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Sets the transaction lock timeout value in milliseconds; set to 0 for no timeout. Like all Qore functions and methods taking timeout values, a relative time value may be passed instead of an integer to make the timeout units clear (ex: 2500ms
for 2.5 seconds).
Datasource::setTransactionLockTimeout(softint
$timeout_ms
= 0) returns nothing
Datasource::setTransactionLockTimeout(date
$timeout
) returns nothing
$db.setTransactionLockTimeout(5m); # transaction lock timeout set to 5 minutes
Table 4.578. Arguments for Datasource::setTransactionLockTimeout()
Argument | Description |
---|---|
The timeout value to set in seconds. For no timeout, set to 0. Like all Qore functions and methods taking timeout values, a relative time value may be passed instead of an integer to make the timeout units clear (ex: |
Retrieves the transaction lock timeout value as an integer in milliseconds.
Datasource::getTransactionLockTimeout() returns int
$int = $db.getTransactionLockTimeout();
Table 4.579. Return Values for Datasource::getTransactionLockTimeout()
Return Type | Description |
---|---|
The transaction lock timeout value in milliseconds. |
Sets the username to use for the connection. Invalid usernames will cause an exception to be thrown when the connection is opened.
Datasource::setUserName(string
$user
) returns nothing
Datasource::setUserName() returns nothing (RT_NOOP)
$db.setUserName("user");
Table 4.580. Arguments for Datasource::setUserName()
Argument | Description |
---|---|
| The username to be used for the connection. |
Retrieves the username parameter for connections to the database.
Datasource::getUserName() returns any
$str = $db.getUserName();
Sets the password to use for the connection. Invalid passwords will cause an exception to be thrown when the connection is opened.
Datasource::setPassword(string
$pass
) returns nothing
Datasource::setPassword() returns nothing (RT_NOOP)
$db.setPassword("pass");
Table 4.582. Arguments for Datasource::setPassword()
Argument | Description |
---|---|
| The password name to be used for the connection. |
Retrieves the password connection parameter.
Datasource::getPassword() returns any
$str = $db.getPassword();
Sets the database name to use for the connection. Invalid database names will cause an exception to be thrown when the connection is opened.
Datasource::setDBName(string
$db
) returns nothing
Datasource::setDBName() returns nothing (RT_NOOP)
$db.setDBName("database");
Table 4.584. Arguments for Datasource::setDBName()
Argument | Description |
---|---|
| The database name to be used for the connection. |
Retrieves the dbname connection parameter.
Datasource::getDBName() returns any
$str = $db.getDBName();
Sets the database-specific character encoding to use for the connection. Invalid character encoding names will cause an exception to be thrown when the connection is opened.
Datasource::setDBCharset(string
$encoding
) returns nothing
Datasource::setDBCharset() returns nothing (RT_NOOP)
$db.setDBCharset("ALU32UTF8"); # Oracle UTF-8 encoding equivalent
Table 4.586. Arguments for Datasource::setDBCharset()
Argument | Description |
---|---|
| The database-specific name for the encoding to be used for the connection. |
Sets the hostname to use for the connection (for DBI drivers that support this parameter, such as the mysql
and pgsql
, for example). Invalid hostnames will cause an exception to be thrown when the connection is opened.
Datasource::setHostName(string
$host
) returns nothing
Datasource::setHostName() returns nothing (RT_NOOP)
$db.setHostName("localhost");
Table 4.587. Arguments for Datasource::setHostName()
Argument | Description |
---|---|
| The hostname to be used for the connection. |
Sets the port number to use for the connection (for DBI drivers that support this parameter, such as the mysql
, pgsql
, and oracle
drivers, for example). Invalid port numbers will cause an exception to be thrown when the connection is opened.
Datasource::setPort(softint
$port
= 0) returns nothing
$db.setPort(5432);
Table 4.588. Arguments for Datasource::setPort()
Argument | Description |
---|---|
| The port number to be used for the connection. |
Retrieves the database-specific charset set encoding for the current connection.
Datasource::getDBCharset() returns any
$str = $db.getDBCharset();
Retrieves the Qore charset set encoding for the current connection.
Datasource::getOSCharset() returns string
$str = $db.getOSCharset();
Table 4.590. Return Values for Datasource::getOSCharset()
Return Type | Description |
---|---|
Retrieves the Qore charset set encoding for the current connection or |
Retrieves the hostname connection parameter.
Datasource::getHostName() returns any
$str = $db.getHostName();
Retrieves the port connection parameter or NOTHING if none is set.
Datasource::getPort() returns any
$port = $db.getPort();
Returns the name of the DBI driver used for this object.
Datasource::getDriverName() returns string
$name = $db.getDriverName();
Table 4.593. Return Values for Datasource::getDriverName()
Return Type | Description |
---|---|
The name of the database driver used for this object. |
Retrieves the driver-specific server version information for the current connection.
Datasource::getServerVersion() returns any
$data = $db.getServerVersion();
Table 4.594. Return Values for Datasource::getServerVersion()
Return Type | Description |
---|---|
The return type and value depends on the driver; see the documentation for the DBI driver used for the connection. |
Retrieves the driver-specific client library version information. Not implemented for all drivers.
Datasource::getClientVersion() returns any
$data = $db.getClientVersion();
Table 4.595. Return Values for Datasource::getClientVersion()
Return Type | Description |
---|---|
The return type and value depends on the driver; see the documentation for the DBI driver used for the connection. |
Note: This class is not available with the PO_NO_DATABASE
parse option.
The DatasourcePool class provides transparent per-thread, per-transaction Datasource connection pooling.
In most cases, the DatasourcePool class can be used as a drop-in replacement for the Datasource class with autocommit disabled; when a transaction begins, a datasource will be automatically assigned to the calling thread, and it will only be released when a commit or rollback is called on the object. If no Datasource is available, the calling thread will block until a Datasource comes available.
Note that the same principles apply to SQL and database driver usage as with the Datasource class, see the Datasource class documentation for more information.
The DatasourcePool class uses Qore's thread resource tracking infrastructure to raise an exception if a thread terminates while a connection is allocated to it. If Qore user code enters a transaction with a DatasourcePool object and the thread terminates without closing the transaction (via DatasourcePool::commit() or DatasourcePool::rollback()), an exception will automatically be raised, the transaction will be rolled back, and the Datasource connection will be freed to the pool.
The following methods allocate a persistent connection to the calling thread: DatasourcePool::exec(), DatasourcePool::vexec(), DatasourcePool::execRaw(), and DatasourcePool::beginTransaction(). The connection is released to the pool when DatasourcePool::commit() or DatasourcePool::rollback() are called (or in the case the thread terminates, in which case an exception is raised as well).
To begin a transaction with one of the select methods (for example, with "select for update"), call DatasourcePool::beginTransaction() first to manually dedicate a Datasource to the thread before calling the select method. Otherwise statements that should be in the same transaction may be executed in different connections.
Executing a DatasourcePool method while not in a transaction is realized by allocating a temporary connection to the calling thread which is re-released when the method returns. No explicit commits are executed by the class, therefore it is an error to execute transaction-relevant commands without first calling DatasourcePool::exec(), DatasourcePool::vexec(), DatasourcePool::execRaw(), or DatasourcePool::beginTransaction().
Table 4.596. DatasourcePool Method Overview
Method | Except? | Description |
---|---|---|
| Y | Creates the DatasourcePool object; attempts to load a DBI driver if the driver is not already present in Qore. |
Y | Destroys the object. | |
Y | Throws an exception; currently DatasourcePool objects may not be copied. | |
| Y | Commits the transaction and releases the connection to the pool. |
| Y | Rolls back the transaction and releases the connection to the pool. |
| Y | Executes SQL code on the DB connection and dedicates a connection to the calling thread. |
| Y | Executes SQL code (like DatasourcePool::exec()) on the DB connection without any variable binding and dedicates a connection to the calling thread. |
| Y | Executes SQL code on the DB connection, taking a list for all bind arguments. Dedicates a connection to the calling thread. |
| Y | Executes a select statement on the server and returns the results in a hash (column names) of lists (rows). |
| Y | Executes a select statement on the server and returns the results in a hash (column names) of lists (rows), taking a list for all bind arguments. |
| Y | Executes a select statement on the server and returns the first row as a hash (column names and values). |
| Y | Executes a select statement on the server and returns the first row as a hash (column names and values), taking a list for all bind arguments. |
| Y | Executes a select statement on the server and returns the results in a list (rows) of hashes (column names and values). |
| Y | Executes a select statement on the server and returns the results in a list (rows) of hashes (column names and values), taking a list for all bind arguments. |
| Y | Manually allocates a persistent connection to the calling thread. |
| N | Returns the username parameter as a string or NOTHING if none is set. |
| N | Returns the password parameter as a string or NOTHING if none is set. |
| N | Returns the dbname parameter as a string or NOTHING if none is set. |
| N | Returns the DBI driver specific charset name for the current connection as a string or NOTHING if none is set. |
| N | Returns the Qore charset name for the current connection as a string or NOTHING if none is set. |
| N | Returns the hostname parameter as a string or NOTHING if none is set. |
| N | Returns the port parameter as an integer or NOTHING if none is set. |
| N | Returns the name of the database driver used for this object as a string. |
| Y | Returns the driver-specific server version data for the current connection. |
| Y | Returns the driver-specific client library version data. Not implemented by all drivers. |
| N | Returns |
Creates a DatasourcePool object. The constructor taking separate arguments requires the database driver name as the first argument, and normally the dbname; the port number is supplied as the final parameter because support for the port number as a connection parameter was added after this class was already present in Qore. The constructor variant taking a hash accepts a hash as produced from parseDatasource().
DatasourcePool::constructor(string
$driver
, string $user
= "", string $pass
= "", string $dbname
= "", string $encoding
= "", string $host
= "", softint $min
= DP_MIN, softint $max
= DP_MAX, softint $port
= 0)
# open a Datasource pool to a PostgreSQL database, username="user", password="pass", dbname="database"
# use "utf8" for the character encoding for the connection, hostname="localhost", port=5432
# minimum 5 connections (opened immediately), with a maximum of 20
my DatasourcePool $pool(DSPGSQL, "user", "pass", "database", "utf8", "localhost", 5, 20, 5432);
# same as above but using a hash argument with parseDatasource() my DatasourcePool $pool(parseDatasource("pgsql:user/pass@database(utf8)%localhost:5432{min=5,max=20}"));
Table 4.597. Arguments for DatasourcePool::constructor(string $driver, string $user = "", string $pass = "", $dbname = "", string $encoding = "", string $host = "", softint $min = DP_MIN, softint $max = DP_MAX, softint $port = 0) Variant
Argument | Description |
---|---|
| The name of the DBI driver for the DatasourcePool. See SQL Constants for builtin constants for DBI drivers shipped with Qore, or see the DBI driver documentation to use an add-on driver. |
| The user name for the new pool. |
| The password for the new pool. |
| The database name for the new pool. |
| The database-specific name of the character encoding to use for the new pool. If no value is passed for this parameter, then the database character encoding corresponding to the default character encoding for the Qore process will be used instead. |
| The host name for the new pool. |
| The minimum number of connections for the new pool; this number of connections will be opened immediately when the pool is created. |
| The maximum number of connections for the new pool; must be greater than or equal to |
| The port number for the new pool. |
Table 4.598. Arguments for DatasourcePool::constructor(hash $params) Variant
Argument | Description |
---|---|
| A hash of parameters for the DatasourcePool; see DatasourcePool Constructor Hash for more information. |
Table 4.599. DatasourcePool Constructor Hash
Key | Type | Description |
---|---|---|
| The name of the database driver to use; this key is mandatory; if not present, an exception will be raised. See SQL Constants for builtin constants for DBI drivers shipped with Qore, or see the DBI driver documentation to use an add-on driver. | |
| The user name for the new connection. Also see Datasource::setUserName() for a method that allows this parameter to be set after the constructor. | |
| The password for the new connection. Also see Datasource::setPassword() for a method that allows this parameter to be set after the constructor. | |
| The database name for the new connection. Also see Datasource::setDBName() for a method that allows this parameter to be set after the constructor. | |
| The database-specific name of the character encoding to use for the new connection. Also see Datasource::setDBCharset() for a method that allows this parameter to be set after the constructor. If no value is passed for this parameter, then the database character encoding corresponding to the default character encoding for the Qore process will be used instead. | |
| The host name for the new connection. Also see Datasource::setHostName() for a method that allows this parameter to be set after the constructor. | |
| The port number for the new connection. Also see Datasource::setPort() for a method that allows this parameter to be set after the constructor. If this key is present and is 0 then an exception will be raised. | |
| A hash where the |
Table 4.600. Exceptions Thrown by DatasourcePool::constructor()
err | desc |
---|---|
| Missing DBI driver, negative number of connections specified, or max < min. |
| Could not load a driver for the database identified. |
Throws an exception if any transactions are in progress and returns immediately. The object is destroyed after any in-progress requests are completed.
delete $pool;
Table 4.601. Exceptions Thrown by DatasourcePool::destructor()
err | desc |
---|---|
| The destructor was called while a transaction was still in progress. |
Thows an exception; DatasourcePool objects cannot be copied at the moment.
Manually allocates a persistent connection from the pool to the calling thread. This method should be called when a transaction will be started with a DatasourcePool::select() method (or vselect*, etc).
DatasourcePool::beginTransaction() returns nothing
$pool.beginTransaction();
Commits the current transaction and releases the connection to the pool.
DatasourcePool::commit() returns nothing
$pool.commit();
Table 4.602. Exceptions Thrown by DatasourcePool::commit()
err | desc |
---|---|
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Returns True
if there is a Datasource from the pool currently allocated to the calling thread, False
if not.
DatasourcePool::inTransaction() returns bool
my bool $in_trans = $pool.inTransaction();
Table 4.603. Return Value for DatasourcePool::inTransaction()
Return Type | Description |
---|---|
Returns |
Rolls back the current transaction and releases the connection to the pool.
DatasourcePool::rollback() returns nothing
$pool.rollback();
Table 4.604. Exceptions Thrown by DatasourcePool::rollback()
err | desc |
---|---|
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Allocates a persistent connection to the calling thread, executes an SQL command on the server and returns either the row count (for example, for updates and inserts) or the data retrieved (for example, if a stored procedure is executed that returns values). This method takes a special syntax for binding values and placeholders; see the Datasource::exec() method for more information.
DatasourcePool::exec(string
$sql
, ...) returns any
DatasourcePool::exec() returns nothing (RT_NOOP)
$rows = $pool.exec("insert into table (varchar_col, timestamp_col, blob_col, numeric_col) values (%v, %v, %v, %d)", $string, now(), $binary, 100);
Table 4.605. Arguments for DatasourcePool::exec()
Argument | Description |
---|---|
| The SQL command to execute on the server. |
| Include any values to be bound (using |
Table 4.606. Return Values for DatasourcePool::exec()
Return Type | Description |
---|---|
The return value depends on the DBI driver; normally, for commands with placeholders, a hash is returned holding the values acquired from executing the SQL statement. For all other commands, normally an int row count is returned. However, some DBI drivers also allow select statements to be executed through this interface, which would also return a hash of list. |
Table 4.607. Exceptions Thrown by DatasourcePool::exec()
err | desc |
---|---|
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Grabs the transaction lock (if autocommit is disabled) and executes an SQL command on the server and returns either the row count (for example, for updates and inserts) or the data retrieved (for example, if a stored procedure is executed that returns values).
This method does not do any variable binding, so it's useful for example for DDL statements etc.
Using this method for OLTP statements can affect the application performance. See used DB server documentation for variable binding.
DatasourcePool::execRaw(string
$sql
) returns any
$rows = $pool.execRaw("create table my_tab (id number, some_text varchar2(30))");
Table 4.608. Arguments for DatasourcePool::execRaw()
Argument | Description |
---|---|
| The SQL command to execute on the server. |
Table 4.610. Exceptions Thrown by DatasourcePool::execRaw()
err | desc |
---|---|
| Timeout trying to acquire the transaction lock. |
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Same as the DatasourcePool::exec() method, except this method takes a single argument after the SQL command giving the list of bind parameters.
This method allocates a persistent connection from the pool to the calling thread.
DatasourcePool::vexec(string
$sql
, list $args
) returns any
DatasourcePool::vexec(string
$sql
) returns any
DatasourcePool::vexec() returns nothing (RT_NOOP)
$rows = $pool.vexec("insert into example_table value (%v, %v, %v)", $arg_list);
Table 4.612. Return Values for DatasourcePool::vexec()
Return Type | Description |
---|---|
Integer or Hash | For commands with placeholders, a hash is returned holding the values acquired from executing the SQL statement. For all other commands, a row count is returned. |
Table 4.613. Exceptions Thrown by DatasourcePool::vexec()
err | desc |
---|---|
The return value depends on the DBI driver; normally, for commands with placeholders, a hash is returned holding the values acquired from executing the SQL statement. For all other commands, normally an int row count is returned. However, some DBI drivers also allow select statements to be executed through this interface, which would also return a hash of list. |
Executes an SQL select statement on the server and returns the result as a hash (column names) of lists (rows). See Datasource::select() for more information.
Note that this method does not allocate a persistent connection to the calling thread; if the calling thread does not already have a connection allocated to it, a temporary connection will be allocated for executing the select query and returning the results; the temporary connection will be immediately returned to the pool when this method returns. It is an error to execute transaction relevant commands with this method without first allocating a persistent connection with DatasourcePool::exec(), DatasourcePool::vexec(), DatasourcePool::execRaw(), or DatasourcePool::beginTransaction().
DatasourcePool::select(string
$sql
, ...) returns any
DatasourcePool::select() returns nothing (RT_NOOP)
# bind a string and a date/time value by value in a query $query = $pool.select("select * from table where varchar_column = %v and timestamp_column > %v", $string, 2007-10-11T15:31:26.289);
Table 4.614. Arguments for DatasourcePool::select()
Argument | Description |
---|---|
| The SQL select command to execute on the server. |
| Include any values to be bound (using |
Table 4.616. Exceptions Thrown by DatasourcePool::select()
err | desc |
---|---|
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Same as the DatasourcePool::select() method, except this method takes a single argument after the SQL command giving the list of bind value parameters.
Note that this method does not allocate a persistent connection to the calling thread; if the calling thread does not already have a connection allocated to it, a temporary connection will be allocated for executing the select query and returning the results; the temporary connection will be immediately returned to the pool when this method returns. It is an error to execute transaction relevant commands with this method without first allocating a persistent connection with DatasourcePool::exec(), DatasourcePool::vexec(), DatasourcePool::execRaw(), or DatasourcePool::beginTransaction().
DatasourcePool::vselect(string
$sql
, list $args
) returns any
DatasourcePool::vselect(string
$sql
) returns any
DatasourcePool::vselect() returns nothing (RT_NOOP)
$query = $pool.vselect("select * from example_table where id = %v and name = %v", $arg_list);
Table 4.619. Exceptions Thrown by DatasourcePool::vselect()
err | desc |
---|---|
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Executes an SQL select statement on the server and returns the first row as a hash (the column values). If more than one row is returned, then all but the first row are discarded. For a similar method taking a list for all bind arguments, see DatasourcePool::vselectRow().
This method also accepts all bind parameters (%d, %v, etc) as documented in Datasource Binding.
Note that this method does not allocate a persistent connection to the calling thread; if the calling thread does not already have a connection allocated to it, a temporary connection will be allocated for executing the select query and returning the results; the temporary connection will be immediately returned to the pool when this method returns. It is an error to execute transaction relevant commands with this method without first allocating a persistent connection with DatasourcePool::exec(), DatasourcePool::vexec(), DatasourcePool::execRaw(), or DatasourcePool::beginTransaction().
DatasourcePool::selectRow(string
$sql
, ...) returns any
DatasourcePool::selectRow() returns nothing (RT_NOOP)
$list = $pool.selectRow("select * from example_table");
Table 4.620. Arguments for DatasourcePool::selectRow()
Argument | Description |
---|---|
| The SQL select command to execute on the server. |
| Include any values to be bound (using |
Table 4.622. Exceptions Thrown by DatasourcePool::selectRow()
err | desc |
---|---|
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Same as the DatasourcePool::selectRow() method, except this method takes a single argument after the SQL command giving the list of bind value parameters.
Note that this method does not allocate a persistent connection to the calling thread; if the calling thread does not already have a connection allocated to it, a temporary connection will be allocated for executing the select query and returning the results; the temporary connection will be immediately returned to the pool when this method returns. It is an error to execute transaction relevant commands with this method without first allocating a persistent connection with DatasourcePool::exec(), DatasourcePool::vexec(), DatasourcePool::execRaw(), or DatasourcePool::beginTransaction().
DatasourcePool::vselectRow(string
$sql
, list $args
) returns any
DatasourcePool::vselectRow(string
$sql
) returns any
DatasourcePool::vselectRow() returns nothing (RT_NOOP)
$list = $pool.vselectRow("select * from example_table where id = %v and name = %v", $arg_list);
Executes an SQL select statement on the server and returns the result as a list (rows) of hashes (the column values). This format is not as efficient as that returned by the DatasourcePool::select() method, therefore for larger amounts of data, it is recommended to use DatasourcePool::select().
This method also accepts all bind parameters (%d, %v, etc) as documented in Datasource Binding.
Note that this method does not allocate a persistent connection to the calling thread; if the calling thread does not already have a connection allocated to it, a temporary connection will be allocated for executing the select query and returning the results; the temporary connection will be immediately returned to the pool when this method returns. It is an error to execute transaction relevant commands with this method without first allocating a persistent connection with DatasourcePool::exec(), DatasourcePool::vexec(), DatasourcePool::execRaw(), or DatasourcePool::beginTransaction().
DatasourcePool::selectRows(string
$sql
, ...) returns any
DatasourcePool::selectRows() returns nothing (RT_NOOP)
$list = $pool.selectRows("select * from example_table");
Table 4.625. Arguments for DatasourcePool::selectRows()
Argument | Description |
---|---|
| The SQL select command to execute on the server. |
| Include any values to be bound (using |
Table 4.626. Return Values for DatasourcePool::selectRows()
Return Type | Description |
---|---|
Normally returns a list (rows) of hash (where the keys are the column names of each row) or nothing if no rows are found for the query. However, DBI could return other types; for DBI drivers that allow executing generic SQL through this method, any result sets returns should also be in the format list (rows) of hash. |
Table 4.627. Exceptions Thrown by DatasourcePool::selectRows()
err | desc |
---|---|
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Same as the DatasourcePool::selectRows() method, except this method takes a single argument after the SQL command giving the list of bind value parameters.
Note that this method does not allocate a persistent connection to the calling thread; if the calling thread does not already have a connection allocated to it, a temporary connection will be allocated for executing the select query and returning the results; the temporary connection will be immediately returned to the pool when this method returns. It is an error to execute transaction relevant commands with this method without first allocating a persistent connection with DatasourcePool::exec(), DatasourcePool::vexec(), DatasourcePool::execRaw(), or DatasourcePool::beginTransaction().
DatasourcePool::vselectRows(string
$sql
, list $args
) returns any
DatasourcePool::vselectRows(string
$sql
) returns any
DatasourcePool::vselectRows() returns nothing (RT_NOOP)
$list = $pool.vselectRows("select * from example_table where id = %v and name = %v", $arg_list);
Table 4.629. Return Values for DatasourcePool::vselectRows()
Return Type | Description |
---|---|
Normally returns a list (rows) of hash (where the keys are the column names of each row) or nothing if no rows are found for the query. However, DBI could return other types; for DBI drivers that allow executing generic SQL through this method, any result sets returns should also be in the format list (rows) of hash. |
Table 4.630. Exceptions Thrown by DatasourcePool::vselectRows()
err | desc |
---|---|
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Retrieves the username parameter for all connections in this pool.
DatasourcePool::getUserName() returns any
$str = $pool.getUserName();
Retrieves the password connection parameter.
DatasourcePool::getPassword() returns any
$str = $pool.getPassword();
DatasourcePool::getDBName() returns any
DatasourcePool::getDBName()
$str = $pool.getDBName();
Retrieves the database-specific charset set encoding for the current connection.
DatasourcePool::getDBCharset() returns any
$str = $pool.getDBCharset();
Retrieves the Qore charset set encoding for the current connection.
DatasourcePool::getOSCharset() returns any
$str = $pool.getOSCharset();
Table 4.635. Return Values for DatasourcePool::getOSCharset()
Return Type | Description |
---|---|
Retrieves the Qore charset set encoding for the current connection or |
Retrieves the hostname connection parameter.
DatasourcePool::getHostName() returns any
$str = $pool.getHostName();
Retrieves the port connection parameter.
DatasourcePool::getPort() returns any
$port = $pool.getPort();
Returns the name of the DBI driver used for this object.
DatasourcePool::getDriverName() returns string
$name = $pool.getDriverName();
Table 4.638. Return Values for DatasourcePool::getDriverName()
Return Type | Description |
---|---|
The name of the database driver used for this object. |
Retrieves the driver-specific server version information for the current connection.
DatasourcePool::getServerVersion() returns any
$data = $pool.getServerVersion();
Table 4.639. Return Values for DatasourcePool::getServerVersion()
Return Type | Description |
---|---|
The return type and value depends on the driver; see the documentation for the DBI driver used for the connection. |
Retrieves the driver-specific client library version information. Not implemented for all drivers.
DatasourcePool::getClientVersion() returns any
$data = $pool.getClientVersion();
Table 4.640. Return Values for DatasourcePool::getClientVersion()
Return Type | Description |
---|---|
The return type and value depends on the driver; see the documentation for the DBI driver used for the connection. |
Note: This class is not available with the PO_NO_THREAD_CLASSES
parse option.
This is an abstract class to be inherited by builtin classes that implement the internal Qore API that allows them to be used by the Condition class. Currently the RWLock and Mutex classes inherit this class.
This class cannot be instantiated directly and also cannot be directly inherited by user-defined classes.
Table 4.641. AbstractSmartLock Method Overview
Method | Except? | Description |
---|---|---|
Y | Throws an exception if called directly; this class can only be instantiated by builtin subclasses. | |
N | Performs no action. | |
N | Performs no action. | |
| N | Returns the name of the threading class directly inheriting this class. |
Throws an exception if called directly or if inherited by a user-defined class; this class can only be instantiated by builtin subclasses.
Table 4.642. Exceptions Thrown by AbstractSmartLock::constructor()
err | desc |
---|---|
| This class cannot be instantiated directly or inherited by user code. |
Returns the name of the threading class directly inheriting this class.
AbstractSmartLock::getName() returns string
my $name = $lock.getName();
Table 4.643. Return Values for AbstractSmartLock::getName()
Return Type | Description |
---|---|
Returns the name of the threading class directly inheriting this class. |
Note: This class is not available with the PO_NO_THREAD_CLASSES
parse option.
AutoGate objects, when used along with a Gate object, allow Qore programmers to safely enter and exit a gate lock, even if exceptions are thrown or return statements are executed in the block where the AutoGate object is created. AutoGate objects enter the gate lock for the lifetime of the AutoGate object. For this reason, it is only appropriate to assign an AutoGate object to a local variable, so when the local variable goes out of scope, the AutoGate object will be deleted and the gate automatically exited.
For example:
our Gate $gate(); sub check_error($error) { # note that the Gate is entered in the AutoGate constructor, and # the Gate will be exited as soon as the block is exited below. # (with either the throw statement or the return statement) my AutoGate $ag($gate); if ($error) throw "ERROR", "sorry, an error happened"; return "OK"; }
Table 4.644. AutoGate Method Overview
Method | Except? | Description |
---|---|---|
| Y | Creates the AutoGate object based on the Gate argument passed and immediately calls Gate::enter(). |
Y | Calls Gate::exit() and destroys the AutoGate object. | |
Y | Throws an exception; objects of this class cannot be copied. |
Creates the AutoGate object based on the Gate argument passed and immediately calls Gate::enter().
AutoGate::constructor(Gate
$gate
)
my AutoGate $gate($gate);
Table 4.645. Arguments for AutoGate::constructor()
Argument | Description |
---|---|
| The Gate object to enter for the lifetime of the AutoGate object. |
Calls Gate::exit() on the saved Gate object and destroys the AutoGate object.
delete $ag;
Note: This class is not available with the PO_NO_THREAD_CLASSES
parse option.
AutoLock objects, when used along with a Mutex object, allow Qore programmers to safely acquire and release a Mutex lock, even if exceptions are thrown or return statements are executed in the block where the AutoLock object is created. AutoLock objects are helper objects that acquire a Mutex for the lifetime of the object. For this reason, it is only appropriate to assign an AutoLock object to a local variable, so when the local variable goes out of scope, the AutoLock object will be deleted and the Mutex will be automatically released.
For example:
our Mutex $mutex(); sub check_error($error) { # note that the Mutex is acquired in the AutoLock constructor, and # the Mutex will be released as soon as the block is exited below. # (with either the throw statement or the return statement) my AutoLock $al($mutex); if ($error) throw "ERROR", "sorry, an error happened"; return "OK"; }
Table 4.647. AutoLock Method Overview
Method | Except? | Description |
---|---|---|
| Y | Creates the AutoLock object based on the Mutex argument passed and immediately calls Mutex::lock(). |
Y | Calls Mutex::unlock() on the saved Mutex and destroys the AutoLock object. | |
Y | Throws an exception; objects of this class cannot be copied. |
Creates the AutoLock object based on the Mutex argument passed. The AutoLock object immediately calls Mutex::lock() on the Mutex object passed, and saves it so it can be released when the AutoLock object is destroyed.
AutoLock::constructor(Mutex
$mutex
)
my AutoLock $al($mutex);
Table 4.648. Arguments for AutoLock::constructor()
Argument | Description |
---|---|
| The Mutex object to manage for the lifetime of this object. |
Calls Mutex::unlock() on the saved Mutex and destroys the AutoLock object.
delete $al;
Note: This class is not available with the PO_NO_THREAD_CLASSES
parse option.
AutoReadLock objects, when used along with a RWLock object, allow Qore programmers to safely acquire and release a read lock, even if exceptions are thrown or return statements are executed in the block where the AutoReadLock object is created. AutoReadLock objects are helper objects that acquire a read lock for the lifetime of the AutoReadLock object. For this reason, it is only appropriate to assign an AutoReadLock object to a local variable, so when the local variable goes out of scope, the AutoReadLock object will be deleted and the read lock will be automatically released.
For example:
our RWLock $rwl(); sub check_error($error) { # note that the read lock is acquired in the AutoReadLock constructor, and # the read lock will be released as soon as the block is exited below. # (with either the throw statement or the return statement) my AutoReadLock $arl($rwl); if ($error) throw "ERROR", "sorry, an error happened"; return "OK"; }
Table 4.650. AutoReadLock Method Overview
Method | Except? | Description |
---|---|---|
| Y | Creates the AutoReadLock object based on the RWLock argument passed and immediately calls RWLock::readLock(). |
Y | Calls RWLock::readUnlock() on the saved RWLock and destroys the AutoReadLock object. | |
Y | Throws an exception; objects of this class cannot be copied. |
Creates the AutoReadLock object based on the RWLock argument passed. The AutoReadLock object immediately calls RWLock::readLock() on the RWLock object passed, and saves it so it can be released when the AutoReadLock object is destroyed.
AutoReadLock::constructor(RWLock
$rwlock
)
my AutoReadLock $arl($rwlock);
Calls RWLock::readUnlock() on the saved RWLock and destroys the AutoReadLock object.
delete $arl;
Note: This class is not available with the PO_NO_THREAD_CLASSES
parse option.
AutoWriteLock objects, when used along with a RWLock object, allow Qore programmers to safely acquire and release a write lock, even if exceptions are thrown or return statements are executed in the block where the AutoWriteLock object is created. AutoWriteLock objects are helper objects that acquire a write lock for the lifetime of the AutoWriteLock object. For this reason, it is only appropriate to assign an AutoWriteLock object to a local variable, so when the local variable goes out of scope, the AutoWriteLock object will be deleted and the write lock will be automatically released.
For example:
our RWLock $rwl(); sub check_error($error) { # note that the write lock is acquired in the AutoWriteLock constructor, and # the write lock will be released as soon as the block is exited below. # (with either the throw statement or the return statement) my AutoWriteLock $arl($rwl); if ($error) throw "ERROR", "sorry, an error happened"; return "OK"; }
Table 4.653. AutoWriteLock Method Overview
Method | Except? | Description |
---|---|---|
| Y | Creates the AutoWriteLock object based on the RWLock argument passed and immediately calls RWLock::writeLock(). |
Y | Calls RWLock::writeUnlock() on the saved RWLock and destroys the AutoWriteLock object. | |
Y | Throws an exception; objects of this class cannot be copied. |
Creates the AutoWriteLock object based on the RWLock argument passed. The AutoWriteLock object immediately calls RWLock::writeLock() on the RWLock object passed, and saves it so it can be released when the AutoWriteLock object is destroyed.
AutoWriteLock::constructor(RWLock
$rwlock
)
my AutoWriteLock $awl($rwlock);
Table 4.654. Arguments for AutoWriteLock::constructor()
Argument | Description |
---|---|
| The RWLock object to manage for the lifetime of this object. |
Calls RWLock::writeUnlock() on the saved RWLock and destroys the AutoWriteLock object.
delete $awl;
Note: This class is not available with the PO_NO_THREAD_CLASSES
parse option.
Condition objects, when used along with an AbstractSmartLock object (such as RWLock and Mutex objects), allow Qore threads to sleep until a certain condition becomes true.
Table 4.656. Condition Method Overview
Method | Except? | Description |
---|---|---|
N | Creates the Condition object. | |
N | Destroys the Condition object. | |
N | Creates a new Condition object, not based on the original. | |
| Y | Signals a single blocked thread to wake up. |
| Y | Signals all threads blocked on this Condition object to wake up. |
| Y | Blocks a thread until signaled; accepts an optional timeout value. |
| N | Returns the number of threads currently blocked on this object. |
Creates the Condition object.
my Condition $cond();
Creates a new Condition object, not based on the original.
my Condition $new_cond = $cond.copy();
Signals a single blocked thread to wake up. Normally this method call will be made while the same AbstractSmartLock object used for Condition::wait() calls is locked. Then, when the thread calling this method unlocks the AbstractSmartLock object, the thread(s) woken up by this call can continue executing.
Condition::signal() returns nothing
$cond.signal();
Table 4.657. Exceptions Thrown by Condition::signal()
err | desc |
---|---|
| This exception should never be thrown - it indicates a low-level error in executing the method. |
Wakes up all threads waiting on the Condition object. Normally this method call will be made while the same AbstractSmartLock object used for Condition::wait() calls is locked. Then, when the thread calling this method unlocks the AbstractSmartLock object, the thread(s) woken up by this call can continue executing.
Condition::broadcast() returns nothing
$cond.broadcast();
Table 4.658. Exceptions Thrown by Condition::broadcast()
err | desc |
---|---|
| This exception should never be thrown - it indicates a low-level error in executing the method. |
Blocks a thread on the Condition object. Must be called with an AbstractSmartLock argument, and the AbstractSmartLock must be locked before the call. This method will atomically unlock the AbstractSmartLock object and wait on this Condition object to be woken up with a Condition::signal() or Condition::broadcast() method call in another thread. At this point, the AbstractSmartLock will be reacquired with the same state as it was acquired previously before control returns to the blocked thread. The wait condition should always be tested again when the thread is unblocked.
Also accepts an optional timeout value in milliseconds. Like all Qore functions and methods taking timeout values, a relative time value may be passed instead of an integer to make the timeout units clear (ex: 2500ms
for 2.5 seconds). Also if the call times out, the AbstractSmartLock will also be acquired when the Condition::wait() call returns and ETIMEDOUT
will be returned.
Condition::wait(AbstractSmartLock
$lock
) returns int
Condition::wait(AbstractSmartLock
$lock
, softint $timeout_ms
) returns int
Condition::wait(AbstractSmartLock
$lock
, date $timeout
) returns int
{ $mutex.lock(); on_exit $mutex.unlock(); while ($num > 0) $cond.wait($mutex); # ... do something }
Table 4.659. Arguments for Condition::wait()
Argument | Description |
---|---|
| The AbstractSmartLock object to use for synchronization on this Condition object. The AbstractSmartLock must be locked before calling this method. |
An optional timeout value; integers are interpreted as milliseconds; relative date/time values are interpreted literally. |
Table 4.660. Return Values for Condition::wait()
Return Type | Description |
---|---|
0 for success, |
Table 4.661. Exceptions Thrown by Condition::wait()
err | desc |
---|---|
| This exception should never be thrown - it indicates a low-level error in executing the method. |
Returns the number of threads currently blocked on this object using the AbstractSmartLock passed; the AbstractSmartLock can be in any state (locked or unlocked) for this call (does not necessarily have to be locked).
Condition::wait_count(AbstractSmartLock
$lock
) returns int
$num_threads = $cond.wait_count();
Table 4.662. Arguments for Condition::wait()
Argument | Description |
---|---|
| The AbstractSmartLock to check for waiting threads. The AbstractSmartLock can be in any state (locked or unlocked) for this call (does not necessarily have to be locked). |
Table 4.663. Return Values for Condition::wait_count()
Return Type | Description |
---|---|
The number of threads currently blocked on this object. |
Note: This class is not available with the PO_NO_THREAD_CLASSES
parse option.
Counter objects allow Qore threads to sleep until a counter reaches zero.
Table 4.664. Counter Method Overview
Method | Except? | Description |
---|---|---|
| N | Creates the Counter object. |
Y | Destroys the Counter object. | |
N | Creates a new Counter object, not based on the original. | |
| N | Atomically increments the counter value. |
| Y | Atomically decrements the counter value. |
| Y | Blocks a thread until the counter reaches zero; returns zero on sucess, or non-zero if a timeout occurred. |
| N | Returns the current counter value. |
| N | Returns the number of threads currently blocked on this object. |
Creates the Counter object; an optional integer argument may be given giving the intial value of the Counter. If no value is given, then the Counter is initialized with 0.
Counter::constructor(softint
$count
= 0)
my Counter $counter();
Table 4.665. Arguments for Counter::constructor()
Argument | Description |
---|---|
| If an argument is supplied here, then the Counter will be initialized with this value, otherwise the Counter is initialized with 0. |
Destroys the object. Note that it is a programming error to delete this object while other threads are blocked on it; in this case an exception is thrown in the deleting thread, and in each thread blocked on this object when it is deleted.
delete $counter;
Table 4.666. Exceptions Thrown by Counter::destructor()
err | desc |
---|---|
| Object deleted while other threads blocked on it. |
Creates a new Counter object, not based on the original.
my Counter $new_counter = $counter.copy();
Atomically increments the counter value.
Counter::inc() returns nothing
$counter.inc();
Atomically decrements the counter value. An exception can only be thrown if the object is deleted in another thread while this call is in progress; this is a race condition caused by a user programming error and should not occur in practise with correct code.
Counter::dec() returns nothing
$counter.dec();
Table 4.667. Exceptions Thrown by Counter::dec()
err | desc |
---|---|
| Object deleted in another thread. |
Blocks a thread until the counter reaches zero. Takes an optional timeout value in milliseconds. Like all Qore functions and methods taking timeout values, a relative date/time value may be passed instead of an integer to make the timeout units clear (ex: 2500ms
for 2.5 seconds).
Returns -1 if the call times out (only if a timeout value is passed), 0 if the counter reached zero.
Counter::waitForZero() returns nothing
Counter::waitForZero(softint
$timeout_ms
) returns int
Counter::waitForZero(date
$timeout
) returns int
$counter.waitForZero();
Table 4.668. Arguments for Counter::waitForZero()
Argument | Description |
---|---|
An optional timeout value to wait for the Counter to reach zero; integers are interpreted as milliseconds; relative date/time values are interpreted literally. |
Table 4.669. Return Values for Counter::waitForZero()
Return Type | Description |
---|---|
If a timeout value was passed, -1 means that the call timed out, 0 means that the counter reached zero. |
Table 4.670. Exceptions Thrown by Counter::dec()
err | desc |
---|---|
| Object deleted in another thread. |
Returns the current counter value.
Counter::getCount() returns int
my int $count = $counter.getCount();
Returns the number of threads currently blocked on this object.
Counter::getWaiting() returns int
my int $threads = $counter.getWaiting();
Table 4.672. Return Values for Counter::getWaiting()
Return Type | Description |
---|---|
The number of threads currently blocked on this object. |
Note: This class is not available with the PO_NO_THREAD_CLASSES
parse option.
Queue objects provide a blocking, thread-safe message-passing object to Qore programs.
Table 4.673. Queue Method Overview
Method | Except? | Description |
---|---|---|
N | Creates the Queue object. | |
Y | Destroys the Queue object. | |
N | Creates a new Queue object with the same elements as the original. | |
| Y | Blocks until at least one entry is available on the queue, then returns the first entry in the queue. If a timeout occurs, an exception is thrown. |
| Y | Blocks until at least one entry is available on the queue, then returns the last entry in the queue. If a timeout occurs, an exception is thrown. |
| N | Puts a value on the end of the queue. |
| N | Returns the number of elements in the queue. |
| N | Returns the number of threads currently blocked on this queue. |
Creates the Queue object.
my Queue $queue();
Destroys the object. Note that it is a programming error to delete this object while other threads are blocked on it; in this case an exception is thrown in the deleting thread, and in each thread blocked on this object when it is deleted.
delete $queue;
Table 4.674. Exceptions Thrown by Queue::destructor()
err | desc |
---|---|
| The queue was deleted while other threads were blocked on it. |
Creates a new Queue object with the same elements as the original.
my Queue $new_queue = $queue.copy();
Blocks until at least one entry is available on the queue, then returns the first entry in the queue. Accepts an optional timeout value in milliseconds (1/1000 second). Like all Qore functions and methods taking timeout values, a relative date/time value may be passed instead of an integer to make the timeout units clear (ex: 2500ms
for 2.5 seconds). If no value or a value that converts to integer 0 is passed as the argument, then the call does not timeout until data is available on the queue.
Note that this function will throw an exception on timeout, in order to enable the case where NOTHING was pushed on the queue to be differentiated from a timeout.
Queue::get() returns any
Queue::get(softint
$timeout_ms
) returns any
Queue::get(date
$timeout
) returns any
$data = $queue.get();
Table 4.675. Arguments for Queue::get()
Argument | Description |
---|---|
An optional timeout value to wait for data to become available on the queue; integers are interpreted as milliseconds; relative date/time values are interpreted literally. If no value or a value that converts to integer 0 is passed as the argument, then the call does not timeout until data is available on the queue. If a non-zero timeout argument is passed, and no data is available in the timeout period, a QUEUE-TIMEOUT exception is thrown. |
Table 4.677. Exceptions Thrown by Queue::get()
err | desc |
---|---|
| The timeout value was exceeded. |
| The queue was deleted in another thread while this thread was blocked on it. |
Blocks until at least one entry is available on the queue, then returns the last entry in the queue. Accepts an optional timeout value in ms (1/1000 second). Like all Qore functions and methods taking timeout values, a relative date/time value may be passed instead of an integer to make the timeout units clear (ex: 2500ms
for 2.5 seconds). If no value or a value that converts to integer 0 is passed as the argument, then the call does not timeout until data is available on the queue.
Note that this function will throw an exception on timeout, in order to enable the case where NOTHING was pushed on the queue to be differentiated from a timeout.
Queue::pop() returns any
Queue::pop(softint
$timeout_ms
) returns any
Queue::pop(date
$timeout
) returns any
$data = $queue.pop();
Table 4.678. Arguments for Queue::pop()
Argument | Description |
---|---|
An optional timeout value to wait for data to become available on the queue; integers are interpreted as milliseconds; relative date/time values are interpreted literally. If no value or a value that converts to integer 0 is passed as the argument, then the call does not timeout until data is available on the queue. If a non-zero timeout argument is passed, and no data is available in the timeout period, a QUEUE-TIMEOUT exception is thrown. |
Table 4.679. Return Values for Queue::pop()
Return Type | Description |
---|---|
Depends on the value put on the queue. |
Table 4.680. Exceptions Thrown by Queue::pop()
err | desc |
---|---|
| The timeout value was exceeded. |
| The queue was deleted in another thread while this thread was blocked on it. |
Adds a value to the end of the queue.
Queue::push(any
$val
) returns nothing
$queue.push($value);
Returns the number of elements in the queue.
Queue::size() returns int
my int $size = $queue.size();
Table 4.682. Return Values for Queue::size()
Return Type | Description |
---|---|
The number of elements in the queue. |
Returns the number of threads currently blocked on this queue.
Queue::getWaiting() returns int
my int $num = $queue.getWaiting();
Table 4.683. Return Values for Queue::getWaiting()
Return Type | Description |
---|---|
The number of threads currently blocked on this queue. |
Note: This class is not available with the PO_NO_THREAD_CLASSES
parse option.
This class inherits AbstractSmartLock, so it can be used by Condition objects, while using either the read lock or the write lock.
The RWLock class implements a read-write lock for efficient thread locking when write actions must be atomic and reads can be made in parallel if no write is in progress. When a thread holds the write lock, no other thread can grab the read or write lock. Multiple threads can hold the read lock at one time.
As with all Qore threading primitives, this class supports deadlock detection and throws exceptions when threading errors are encountered (for example, trying to free the read lock while holding the write lock, etc).
This read-write lock favors readers, so the read lock can be safely acquired recursively.
See the AutoReadLock and the AutoWriteLock classes for classes that assist in exception-safe RWLock locking.
Additionally, the on_exit statement can provide exception-safe RWLock handling at the lexical block level as in the following example:
{
$rwl.writeLock();
on_exit
$rwl.writeUnlock();
# ... when this block exits the lock will be released, even in the
# case of return
statements or exceptions
}
Table 4.684. RWLock Method Overview
Method | Except? | Description |
---|---|---|
N | Creates the RWLock object. | |
Y | Destroys the RWLock object. | |
N | Creates a new RWLock object, not based on the original. | |
| Y | Acquires the read lock with an optional timeout value; blocks if the write lock is already acquired. Returns 0 for success, non-zero for timeout; exceptions are thrown for other errors. |
| Y | Decrements the read lock counter and releases the read lock if the counter is zero. If at least one thread is blocked trying to acquire the write lock and the read counter reaches zero, then one thread waiting on the write lock is woken up. |
| Y | Acquires the write lock with an optional timeout; blocks if either the read lock or write lock is already acquired. Returns 0 for success, non-zero for timeout; exceptions are thrown for other errors. |
| Y | Releases the write lock, if any writers are waiting, then wakes one up, otherwise if any readers are waiting, wakes up all readers. |
| N | Acquires the read lock only if it can be acquired immediately. Returns 0 for success (read lock acquired, read lock count incremented) or -1 if the call would block. |
| N | Acquires the write lock only if it can be acquired immediately. Returns 0 for success (write lock acquired) or -1 if the call would block. |
| N | Returns the read lock count. |
| N | Returns the number of threads waiting on the read lock. |
| N | Returns the number of threads waiting on the write lock. |
Creates the RWLock object.
my RWLock $rwl();
Destroys the object. Note that it is a programming error to delete this object while other threads are blocked on it; in this case an exception is thrown in the deleting thread, and in each thread blocked on this object when it is deleted.
delete $rwl;
Table 4.685. Exceptions Thrown by RWLock::destructor()
err | desc |
---|---|
| Object deleted while other threads blocked on it. |
Creates a new RWLock object, not based on the original.
my RWLock $new_rwl = $rwl.copy();
Acquires the read lock with an optional timeout value; blocks if the write lock is already acquired. The read lock may be acquired recursively, however, each call to RWLock::readLock() requires a corresponding call to RWLock::readUnlock(). An optional timeout value may be passed to this method, giving a time in milliseconds to wait for the lock to become free. Like all Qore functions and methods taking timeout values, a relative date/time value may be passed instead of an integer to make the timeout units clear.
RWLock::readLock() returns nothing
RWLock::readLock(softint
$timeout_ms
) returns int
RWLock::readLock(date
$timeout
) returns int
$rwl.readLock();
Table 4.686. Arguments for RWLock::readLock()
Argument | Description |
---|---|
An optional timeout value to wait to acquire the read lock; integers are interpreted as milliseconds; relative date/time values are interpreted literally. |
Table 4.688. Exceptions Thrown by RWLock::readLock()
err | desc |
---|---|
| A deadlock was detected while trying to acquire the lock. |
| readLock() called while already holding the write lock, object deleted in another thread, etc. |
Decrements the read lock counter and releases the read lock if the counter is zero. If at least one thread is blocked trying to acquire the write lock and the read counter reaches zero, then one thread waiting on the write lock is woken up.
RWLock::readUnlock() returns nothing
$rwl.readUnlock();
Table 4.689. Exceptions Thrown by RWLock::readUnlock()
err | desc |
---|---|
| readUnlock() called while not holding the read lock, object deleted in another thread, etc. |
Acquires the write lock; blocks if either the read lock or write lock is already acquired. An optional timeout value may be passed to this method, giving a time in milliseconds to wait for the lock to become free. Like all Qore functions and methods taking timeout values, a relative date/time value may be passed instead of an integer to make the timeout units clear.
To release the write lock, use RWLock::readUnlock().
RWLock::writeLock() returns nothing
RWLock::writeLock(softint
$timeout_ms
) returns int
RWLock::writeLock(date
$timeout
) returns int
$rwl.writeLock();
Table 4.690. Arguments for RWLock::writeLock()
Argument | Description |
---|---|
An optional timeout value to wait to acquire the write lock; integers are interpreted as milliseconds; relative date/time values are interpreted literally. |
Table 4.692. Exceptions Thrown by RWLock::writeLock()
err | desc |
---|---|
| A deadlock was detected while trying to acquire the lock. |
| writeLock() called while holding the read lock, writeLock() called while already holding the write lock in the same thread, object deleted in another thread, etc. |
Releases the write lock, if any writers are waiting, then wakes one up, otherwise if any readers are waiting, wakes up all readers.
RWLock::writeUnlock() returns nothing
$rwl.writeUnlock();
Table 4.693. Exceptions Thrown by RWLock::writeUnlock()
err | desc |
---|---|
| writeUnlock() called while not holding the write lock, object deleted in another thread, etc. |
Acquires the read lock only if it can be acquired immediately, returns 0 for success, -1 if it would block.
RWLock::tryReadLock() returns int
my int $i = $rwl.tryReadLock();
Table 4.694. Return Values for RWLock::writeUnlock()
Return Type | Description |
---|---|
Returns 0 for success (read lock acquired, read lock count incremented) or -1 if the call would block. |
Acquires the write lock only if it can be acquired immediately, returns 0 for success, -1 if it would block.
RWLock::tryWriteLock() returns int
my int $i = $rwl.tryWriteLock();
Table 4.695. Return Values for RWLock::tryWriteLock()
Return Type | Description |
---|---|
Returns 0 for success (write lock acquired) or -1 if the call would block. |
Returns the read lock count.
RWLock::numReaders() returns int
$num = $rwl.numReaders();
Returns the number of threads blocked on the read lock (only non-zero while the write lock is held).
RWLock::getReadWaiting() returns int
$num = $rwl.getReadWaiting();
Table 4.697. Return Values for RWLock::getReadWaiting()
Return Type | Description |
---|---|
The number of threads blocked on the read lock. |
Returns the number of threads blocked on the write lock.
RWLock::getWriteWaiting() returns int
$num = $rwl.getWriteWaiting();
Table 4.698. Return Values for RWLock::getWriteWaiting()
Return Type | Description |
---|---|
The number of threads blocked on the write lock. |
Note: This class is not available with the PO_NO_THREAD_CLASSES
parse option.
This class inherits AbstractSmartLock, so it can be used by Condition objects.
The Mutex class implements a mutual-exclusion lock for thread locking. Like all Qore thread primitives, objects of this class participate in deadlock detection and throw exceptions when threading errors occur (ex: unlocking a Mutex object locked by another thread, etc). See individual methods for more information on exceptions thrown.
See the AutoLock class for a class that assists in exception-safe Mutex locking.
Additionally, the on_exit statement can provide exception-safe unlocking at the lexical block level for Mutex objects as in the following example:
{
$m.lock();
on_exit
$m.unlock();
# ... when this block exits the lock will be released, even in the
# case of return
statements or exceptions
}
Table 4.699. Mutex Method Overview
Method | Except? | Description |
---|---|---|
N | Creates the Mutex object. | |
Y | Destroys the Mutex object. | |
N | Creates a new Mutex object, not based on the original. | |
| Y | Locks the Mutex object. Blocks if the lock is already held. |
| Y | Unlocks the Mutex object. Wakes up one thread if any threads are blocked on this lock. |
| Y | Acquires the lock only if it is not already held. Returns 0 for success (lock acquired) or -1 if the call would block. |
Creates the Mutex object.
my Mutex $mutex();
Destroys the object. Note that it is a programming error to delete this object while other threads are blocked on it; in this case an exception is thrown in the deleting thread, and in each thread blocked on this object when it is deleted.
delete $mutex;
Table 4.700. Exceptions Thrown by Mutex::destructor()
err | desc |
---|---|
| Object deleted while other threads blocked on it. |
Creates a new Mutex object, not based on the original.
my Mutex $new_mutex = $mutex.copy();
Locks the Mutex object. Blocks if the lock is already held. An optional timeout value may be passed to this method, giving a time in milliseconds to wait for the lock to become free. Like all Qore functions and methods taking timeout values, a relative time value may be passed instead of an integer to make the timeout units clear.
To release the Mutex, use Mutex::unlock().
Mutex::lock() returns nothing
Mutex::lock(softint
$timeout_ms
) returns int
Mutex::lock(date
$timeout
) returns int
$mutex.lock();
Table 4.701. Arguments for Mutex::lock()
Argument | Description |
---|---|
An optional timeout value to wait to acquire the lock; integers are interpreted as milliseconds; relative date/time values are interpreted literally. |
Table 4.703. Exceptions Thrown by Mutex::lock()
err | desc |
---|---|
| A deadlock was detected while trying to acquire the lock. |
| lock called twice in the same thread, object deleted in another thread, etc. |
Unlocks the Mutex object. Wakes up one thread if any threads are blocked on this lock.
Mutex::unlock() returns nothing
$mutex.unlock();
Table 4.704. Exceptions Thrown by Mutex::unlock()
err | desc |
---|---|
| lock not held, lock held by another thread, object deleted in another thread, etc. |
Acquires the lock only if it is not already held; the return value indicates success (0, lock acquired) or failure (-1, lock already held).
Mutex::trylock() returns int
my int $i = $mutex.trylock();
Table 4.705. Return Values for Mutex::trylock()
Return Type | Description |
---|---|
Returns 0 for success (lock acquired) or -1 if the call would block. |
DEPRECATED: use the Gate class instead.
Note: This class is not available with the PO_NO_THREAD_CLASSES
parse option.
The Sequence class implements a thread-safe increment-only object.
Table 4.706. Sequence Method Overview
Method | Except? | Description |
---|---|---|
| N | Creates a new Sequence object. |
N | Destroys the Sequence object. | |
N | Creates a new Sequence object, not based on the original. | |
| N | Atomically increments the counter and returns the last value. |
| N | Returns the current value of the counter. |
Creates a new Sequence object.
Sequence::constructor(softint
$start
)
my Sequence $seq();
Table 4.707. Arguments for Sequence::constructor()
Argument | Description |
---|---|
| Optional start number for the sequence (default with no argument = 0). |
Creates a new Sequence object, not based on the original.
my Sequence $new_seq = $seq.copy();
Atomically increments the counter and returns the last value.
Sequence::next() returns int
$seq.next();
Table 4.708. Return Values for Sequence::next()
Return Type | Description |
---|---|
The last value of the sequence. |
Returns the current value of the counter.
Sequence::getCurrent() returns int
my int $num = $seq.getCurrent();
Table 4.709. Return Values for Sequence::getCurrent()
Return Type | Description |
---|---|
The current value of the counter. |
Note: This class is not available with the PO_NO_THREAD_CLASSES
parse option.
The Gate class implements a reentrant thread lock. Once a thread grabs the lock, it can call the Gate::enter() method again without blocking. Other threads that try to enter the lock will block until the thread holding the lock calls Gate::exit() an equal number of times to Gate::enter() calls.
See the AutoGate class for a class that assists in exception-safe Gate locking.
Additionally, the on_exit statement can provide exception-safe Gate handling at the lexical block level as in the following example:
{
$g.enter();
on_exit
$g.exit();
# ... when this block exits the gate lock counter will be decremented,
# even in the case of return
statements or exceptions
}
Table 4.710. Gate Method Overview
Method | Except? | Description |
---|---|---|
N | Create a new Gate object. | |
Y | Destroys the Gate object. | |
N | Creates a new Gate object, not based on the original. | |
| Y | Acquires the lock if it is unlocked or locked by the same thread, otherwise blocks until the lock counter reaches zero. For variants taking a timeout; returns 0 if no timeout occurred, non-zero if a timeout occurred. |
| N | Acquires the lock if it is unlocked or locked by the same thread, otherwise returns immediately with -1. |
| Y | Decrements the lock counter; if it reaches zero then the lock is unlocked and any blocked threads are awoken; in this case 0 is returns; in all other cases, non-zero is returned. |
| N | Returns the current lock count. |
| N | Returns the number of threads blocked on the Gate. |
Creates a new Gate object.
my Gate $gate();
Destroys the object. Note that it is a programming error to delete this object while other threads are blocked on it; in this case an exception is thrown in the deleting thread, and in each thread blocked on this object when it is deleted.
delete $gate;
Table 4.711. Exceptions Thrown by Gate::destructor()
err | desc |
---|---|
| Object deleted while other threads blocked on it. |
Creates a new Gate object, not based on the original.
my Gate $new_gate = $gate.copy();
Acquires the lock if it is unlocked or locked by the same thread, otherwise blocks until the lock counter reaches zero. An optional timeout value may be passed to this method, giving a time in milliseconds to wait for the lock to become free. Like all Qore functions and methods taking timeout values, a relative time value may be passed instead of an integer to make the timeout units clear.
Gate::enter() returns nothing
Gate::enter(softint
$timeout_ms
) returns int
Gate::enter(date
$timeout
) returns int
$gate.enter();
Table 4.712. Arguments for Gate::enter()
Argument | Description |
---|---|
An optional timeout value to wait to acquire the lock; integers are interpreted as milliseconds; relative date/time values are interpreted literally. |
Table 4.714. Exceptions Thrown by Gate::enter()
err | desc |
---|---|
| A deadlock was detected while trying to acquire the lock. |
| object deleted in another thread |
Acquires the lock if it is unlocked or locked by the same thread, otherwise returns immediately.
Gate::tryEnter() return int
$gate.tryEnter();
Table 4.715. Return Values for Gate::tryEnter()
Return Type | Description |
---|---|
Returns 0 for success (acquired the lock) or -1 for failure (would block). |
Decrements the lock counter; if it reaches zero then the lock is unlocked and any blocked threads are awoken.
Gate::exit() returns int
$gate.exit();
Table 4.716. Exceptions Thrown by Gate::exit()
err | desc |
---|---|
| lock not held by this thread, object deleted in another thread |
Returns the current lock count.
Gate::numInside() returns int
my int $num = $gate.numInside();
Table 4.717. Return Values for Gate::numInside()
Return Type | Description |
---|---|
Returns the current lock count. |
Returns the number of threads blocked on this object.
Gate::numWaiting() returns int
my int $num = $gate.numWaiting();
Table 4.718. Return Values for Gate::numWaiting()
Return Type | Description |
---|---|
Returns the number of threads blocked on this object. |
The following constants are defined in the Qore namespace.
Table 4.719. XML Element Type Constants
Constant | Value | Description |
---|---|---|
|
| Indicates an element |
|
| Indicates an attribute |
|
| Indicates text |
|
| Indicates CDATA: unparsed character data |
|
| Indicates an entity reference |
|
| Indicates an entity |
|
| Indicates a processing instruction |
|
| Indicates a comment |
|
| Indicates a document |
|
| Indicates a document type |
|
| Indicates a document fragment |
|
| Indicates a DTD notation |
|
| Indicates an HTML document |
|
| Indicates a DTD |
|
| Indicates an element declaration |
|
| Indicates an attribute declaration |
|
| Indicates an entity declaration |
|
| Indicates a namespace declaration |
|
| Indicates an XML xinlude start element |
|
| Indicates an XML xinlude end element |
|
| Indicates a docbook document element |
The ElementTypeMap
constant in Xml namespace provides a mapping between element codes and the corresponding string code as defined in the following table.
Table 4.720. ElementTypeMap Constant Hash
Key | Value |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Table 4.721. XML Node Type Constants
Constant | Value | Description |
---|---|---|
|
| Indicates no node is available |
|
| Indicates an XML element |
|
| Indicates an attribute node |
|
| Indicates a text node |
|
| Indicates a CDATA node: unparsed character data |
|
| Indicates an entity reference node |
|
| Indicates an entity node |
|
| Indicates an XML processing instruction |
|
| Indicates an XML comment |
|
| Indicates a document node |
|
| Indicates a document type node |
|
| Indicates a document fragment node |
|
| Indicates a notation node |
|
| Indicates a whitespace node |
|
| Indicates a significant whitespace node |
|
| Indicates an end element node |
|
| Indicates an end entity node |
|
| Indicates an XML declaration node |
The NodeTypeMap
constant in Xml namespace provides a mapping between node type codes and the corresponding string code as defined in the following table.
Table 4.722. NodeTypeMap Constant Hash
Key | Value |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Additionally, the classes in the following table are included in the Xml namespace.
The XmlDoc class provides access to a parsed XML document by wrapping a C xmlDocPtr
from libxml2. Currently this class provides read-only access to XML documents; it is possible that this restriction will be removed in future versions of Qore.
Table 4.724. XmlDoc Method Overview
Method | Except? | Description |
---|---|---|
| Y | Creates a new XmlDoc object from an XML string or a Qore hash. |
N | Destroys the XmlDoc object. | |
N | Creates a copy of the XmlDoc object. | |
| Y | Evaluates an XPath expression and returns a list of matching XmlNode objects; an empty list is returned if there are no matches. |
| N | Returns an XmlNode object representing the root element of the document, if any exists, otherwise returns NOTHING. |
| N | Returns the XML version of the document (normally 1.0). |
| N | Returns a Qore hash corresponding to the XML data; multiple out-of-order keys are created in order in the returned hash by appending a suffix to the key names. |
| N | Returns a Qore hash corresponding to the XML data; key order is not guaranteed to be maintained as multiple out-or-order keys are merged into the same Qore list. |
| N | Returns the XML string for the XML document. |
| Y | Validates the XML document against a RelaxNG schema; if any errors occur, exceptions are thrown. Not available if |
| Y | Validates the XML document against an XSD schema; if any errors occur, exceptions are thrown. Not available if |
Creates a new XmlDoc object from the XML string or Qore hash valus passed. If a Qore hash value is passed, it must have only one top-level key, as the XML string will be created from the hash.
XmlDoc::constructor(string
$xml
)
XmlDoc::constructor(hash
$data
)
my XmlDoc $xd($xml);
Table 4.725. Arguments for XmlDoc::constructor()
Argument | Description |
---|---|
| The XML string to use to create the XmlDoc object. |
| The Qore hash will be used to generate the XML string to use to create the XmlDoc object; the Qore hash must have only one top-level key. The XML will be generated according to the rules documented in XML Integration. |
Table 4.726. Exceptions Thrown by XmlDoc::constructor()
err | desc |
---|---|
| Missing argument or invalid XML string passed. |
Note that if a hash is passed as the argument to the constructor, then the method can throw any of the exceptions documented in makeXMLString().
Destroys the object.
delete $xd;
This method does not throw any exceptions.
Creates a new XmlDoc object, not based on the original.
my XmlDoc $new_doc = $doc.copy();
Evaluates an XPath expression and returns a list of matching XmlNode objects.
XmlDoc::evalXPath(string
$xpath
) returns list
my $list = $xd.evalXPath("//list[2]");
Table 4.727. Arguments for XmlDoc::evalXPath()
Argument | Description |
---|---|
| The XPath expression to evaluate on the XmlDoc object. |
Table 4.729. Exceptions Thrown by XmlDoc::evalXPath()
err | desc |
---|---|
| Missing XPath expression. |
| Cannot create XPath context from the XmlDoc object |
| An error occured evaluating the XPath expression |
Returns an XmlNode object representing the root element of the document, if any exists, otherwise returns NOTHING.
XmlDoc::getRootElement() returns any
my any $node = $xd.getRootElement();
This method does not throw any exceptions.
Returns the XML version of the contained XML document.
XmlDoc::getVersion() returns string
my string $xmlver = $xd.getVersion();
Table 4.731. Return Values for XmlDoc::getVersion()
Return Type | Description |
---|---|
The XML version of the contained document (normally "1.0"). |
This method does not throw any exceptions.
Returns a Qore hash structure correponding to the XML data contained by the XmlDoc object. If duplicate, out-of-order XML elements are found in the input string, they are deserialized to Qore hash elements with the same name as the XML element but including a caret "^" and a numeric prefix to maintain the same key order in the Qore hash as in the input XML string.
For a similar method not preserving the order of keys in the XML in the resulting Qore hash by collapsing all elements at the same level with the same name to the same Qore list, see XmlDoc::toQoreData(). See also parseXMLAsData() and parseXML().
XmlDoc::toQore() returns hash
my hash $h = $xd.toQore();
Table 4.732. Return Values for XmlDoc::toQore()
Return Type | Description |
---|---|
The Qore hash corresponding to the data contained in the XML document with out-of-order keys preserved by appending a suffix to hash keys. |
This method does not throw any exceptions.
Returns a Qore hash structure corresponding to the XML data contained by the XmlDoc object; does not preserve hash order with out-of-order duplicate keys: collapses all to the same list.
Note that data deserialized with this function may not be reserialized to the same input XML string due to the fact that duplicate, out-of-order XML elements are collapsed into lists in the resulting Qore hash, thereby losing the order in the original XML string.
For a similar method preserving the order of keys in the XML in the resulting Qore hash by generating Qore hash element names with numeric suffixes, see XmlDoc::toQore(). See also parseXMLAsData() and parseXML().
XmlDoc::toQoreData() returns hash
my hash $h = $xd.toQoreData();
Table 4.733. Return Values for XmlDoc::toQoreData()
Return Type | Description |
---|---|
The Qore hash corresponding to the data contained in the XML document; out-of-order keys are not preserved but are instead collapsed to the same Qore list. |
This method does not throw any exceptions.
Returns the XML string for the XML document
XmlDoc::toString() returns string
my string $xmlstr = $xd.toString();
Table 4.734. Return Values for XmlDoc::toString()
Return Type | Description |
---|---|
The XML string contained by the XmlDoc object. |
This method does not throw any exceptions.
Validates the XML document against a RelaxNG schema; if any errors occur, exceptions are thrown.
The availability of this function depends on the presence of libxml2's xmlTextReaderRelaxNGSetSchema()
function when Qore was compiled; for maximum portability check the constant HAVE_PARSEXMLWITHRELAXNG
before running this method. See Library Option Constants for a list of all option constants.
XmlDoc::validateRelaxNG(string
$relaxng
) returns nothing
$xd.validateRelaxNG($relaxng);
Table 4.735. Arguments for XmlDoc::validateRelaxNG()
Argument | Description |
---|---|
| The RelaxNG schema to use to validate the XmlDoc object. |
Table 4.736. Exceptions Thrown by XmlDoc::validateRelaxNG()
err | desc |
---|---|
| Missing RelaxNG schema string. |
| The RelaxNG schema could not be parsed. |
| The XML document failed RelaxNG validation. |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Validates the XML document against an XSD schema; if any errors occur, exceptions are thrown.
The availability of this function depends on the presence of libxml2's xmlTextReaderSetSchema()
function when Qore was compiled; for maximum portability check the constant HAVE_PARSEXMLWITHSCHEMA
before running this function. See Library Option Constants for a list of all option constants.
XmlDoc::validateSchema(string
$xsd
) returns nothing
$xd.validateSchema($xsd);
Table 4.737. Arguments for XmlDoc::validateSchema()
Argument | Description |
---|---|
| The XSD schema to use to validate the XmlDoc object. |
Table 4.738. Exceptions Thrown by XmlDoc::validateSchema()
err | desc |
---|---|
| Missing XSD schema string. |
| The XSD schema could not be parsed. |
| The XML document failed XSD schema validation. |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
The XmlNode class provides information about the components of an XML document. This class currently cannot be constructed manually, but rather can only be returned by the XmlDoc class. It is possible that future versions of Qore will remove this restriction.
Table 4.739. XmlNode Class Method Overview
Method |
Except? |
Description |
---|---|---|
Y |
Cannot be called manually; throws an exception. | |
N |
Destroys the XmlNode object. | |
N |
Creates an independent copy of the XmlNode object. | |
|
N |
Returns the number of child elements of the XmlNode. |
|
N |
Returns the space-preserving behavior of the XmlNode object. |
|
N | Returns the type of the XmlNode object; for possible values see XML Element Type Constants. |
|
N | Returns the name of the type of the XmlNode object if possible, NOTHING if not; for possible values see the ElementTypeMap constant. |
|
N | Returns an XmlNode object for the first child of the current XmlNode object that is an XML element, or NOTHING if there is none. |
|
N |
Returns an XmlNode object for the last child of the current XmlNode object, or NOTHING if there is none. |
|
N |
Returns an XmlNode object for the last child of the current XmlNode object that is an XML element, or NOTHING if there is none. |
|
N |
Returns an XmlNode object for the next element at the same level of the current XmlNode object, or NOTHING if there is none. |
|
N |
Returns an XmlNode object for the previous element at the same level of the current XmlNode object, or NOTHING if there is none. |
|
Y |
Returns a string representing a structured path for the current node. |
|
Y |
Returns the value of the given property anchored in the given namespace as a string, or NOTHING if no such property exists in the current XmlNode. |
|
Y |
Returns the value of the given property as a string, or NOTHING if no such property exists in the current XmlNode. |
|
N |
Returns a string of the content of the current node or NOTHING if no content is available. |
|
N |
Returns the name of the current node or NOTHING if no name is available. |
|
N |
Returns the language of the current node, determined by the value of the |
|
N |
Returns |
|
N |
Returns |
|
N |
Returns XML corresponding to the current node and all its children or NOTHING if no data is available. |
Cannot be called manually; throws an exception.
Table 4.740. Exceptions thrown by XmlNode::constructor()
err |
desc |
---|---|
|
XmlNode objects cannot be constructed manually |
Creates an independent copy of the XmlNode object.
my XmlNode $value = $xmlnode.copy();
Returns the number of child elements of the XmlNode.
XmlNode::childElementCount() returns int
$value = $xmlnode.childElementCount();
Table 4.741. Return Values for XmlNode::childElementCount()
Return Type |
Description |
---|---|
the number of child elements of the XmlNode |
Returns the space-preserving behavior of the XmlNode object.
XmlNode::getSpacePreserve() returns int
$value = $xmlnode.getSpacePreserve();
Table 4.742. Return Values for XmlNode::getSpacePreserve()
Return Type |
Description |
---|---|
The space-preserving behavior of the XmlNode: -1 = xml:space is not inherited, 0 = default, 1 = preserve |
Returns the type of the XmlNode object; for possible values see XML Element Type Constants.
XmlNode::getElementType() returns int
$value = $xmlnode.getElementType();
Table 4.743. Return Values for XmlNode::getElementType()
Return Type |
Description |
---|---|
the type of the XmlNode object; for possible values see XML Element Type Constants |
Returns the name of the type of the XmlNode object; for possible values see the ElementTypeMap constant.
XmlNode::getElementTypeName() returns any
$value = $xmlnode.getElementTypeName();
Table 4.744. Return Values for XmlNode::getElementTypeName()
Return Type |
Description |
---|---|
the name of the type of the XmlNode object; for possible values see the ElementTypeMap constant |
Returns an XmlNode object for the first child of the current XmlNode object that is an XML element, or NOTHING if there is none.
XmlNode::firstElementChild() returns any
$value = $xmlnode.firstElementChild();
Returns an XmlNode object for the last child of the current XmlNode object, or NOTHING if there is none.
XmlNode::getLastChild() returns any
$value = $xmlnode.getLastChild();
Returns an XmlNode object for the last child of the current XmlNode object that is an XML element, or NOTHING if there is none.
XmlNode::lastElementChild() returns any
$value = $xmlnode.lastElementChild();
Returns an XmlNode object for the next element at the same level of the current XmlNode object, or NOTHING if there is none.
XmlNode::nextElementSibling() returns any
$value = $xmlnode.nextElementSibling();
Returns an XmlNode object for the previous element at the same level of the current XmlNode object, or NOTHING if there is none.
XmlNode::previousElementSibling() returns any
$value = $xmlnode.previousElementSibling();
Returns a string representing a structured path for the current node.
XmlNode::getPath() returns string
$value = $xmlnode.getPath();
Table 4.750. Return Values for XmlNode::getPath()
Return Type |
Description |
---|---|
a string representing a structured path for the current node |
Returns the value of the given property anchored in the given namespace, or NOTHING if no such property exists in the current XmlNode.
XmlNode::getNsProp(string
$prop
, string $ns
) returns any
$value = $xmlnode.getNsProp($prop, $namespace);
Table 4.753. Exceptions thrown by XmlNode::getNsProp()
err |
desc |
---|---|
|
missing or invalid argument |
Returns the value of the given property, or NOTHING if no such property exists in the current XmlNode.
XmlNode::getProp(string
$prop
) returns any
$value = $xmlnode.getProp($prop);
Table 4.754. Arguments for XmlNode::getProp()
Argument | Description |
---|---|
| The name of the property to retrieve |
Table 4.756. Exceptions thrown by XmlNode::getProp()
err |
desc |
---|---|
|
missing or invalid argument |
Returns a string of the content of the current node or NOTHING if there is none.
XmlNode::getContent() returns any
$value = $xmlnode.getContent();
Returns the name of the current node or NOTHING if no name is available.
XmlNode::getName() returns any
$value = $xmlnode.getName();
Returns the language of the current node, determined by the value of the xml:lang
attribute of this node or of the nearest ancestor. If no such property is available, then NOTHING is returned.
XmlNode::getLang() returns any
$value = $xmlnode.getLang();
Returns True
if the node is a text node, False
if not.
XmlNode::isText() returns bool
$value = $xmlnode.isText();
Table 4.760. Return Values for XmlNode::isText()
Return Type |
Description |
---|---|
True if the node is a text node, |
Returns True
if the node is empty or whitespace only, False
if not.
XmlNode::isBlank() returns bool
$value = $xmlnode.isBlank();
Table 4.761. Return Values for XmlNode::isBlank()
Return Type |
Description |
---|---|
True if the node is empty or whitespace only, |
Returns a string containing XML corresponding to the current node and all its children or NOTHING if no information is available.
XmlNode::getXML() returns any
$value = $xmlnode.getXML();
The XmlReader class allows XML strings to be iterated and parsed piecewise.
Table 4.763. XmlReader Class Method Overview
Method |
Except? |
Description |
---|---|---|
|
Y |
Creates the XmlReader object based on the XmlDoc object or XML string passed. |
N |
Destroys the XmlReader object. | |
N |
Creates an independent copy of the XmlReader object. | |
|
Y |
Moves the position of the current instance to the next node in the stream. |
|
Y |
Moves the position of the current instance to the next node in the stream, skipping any whitespace nodes. |
|
N |
Returns the node type of the current node; for return values, see XML Node Type Constants. |
|
N |
Returns a string giving the node type of the current node or NOTHING if the node type name cannot be determined; for possible return values, see the values of the NodeTypeMap constant. |
|
N |
Returns the depth of the node in the tree. |
|
N |
Returns the qualified name of the node (prefix:LocalName) or NOTHING if no name is available. |
|
N |
Returns the text value of the node or NOTHING if not available. |
|
N |
Returns |
|
N |
Returns |
|
N |
Returns |
|
N |
Returns |
|
N |
Returns |
|
N |
Returns |
|
Y |
Returns a hash corresponding to the XML string from the current node position, including all its children, or a string if the reader is on an element with no children, or NOTHING if there is no more data to read. |
|
Y |
Returns a hash corresponding to the XML string from the current node position, including all its children, or a string if the reader is on an element with no children, or NOTHING if there is no more data to read. |
|
N |
Returns the number of attributes of the current node |
|
N |
Returns the base URI of the node if known, NOTHING if not. |
|
N |
Returns the encoding string given in the XML string or NOTHING if none is given. |
|
N |
Returns the local name of the node or NOTHING if no name is available. |
|
N |
Returns the URI defining the namespace associated with the node, or NOTHING if not available. |
|
N |
Returns the shorthand reference to the namespace associated with the node, or NOTHING if not available. |
|
N |
Returns the xml:lang scope within which the node resides or NOTHING if there is none. |
|
N |
Returns a string giving the XML version of the source document (normally "1.0") |
|
Y |
Returns the value of the attribute matching the qualified name passed, or NOTHING if no such attribute exists in the current XmlReader. |
|
Y |
Returns the value of the given attribute anchored in the given namespace, or NOTHING if no such attribute exists in the current XmlReader. |
|
N |
Returns the string value of the attribute with the specified index relative to the containing element, or NOTHING if no such attribute exists in the current XmlReader. |
|
N |
Returns the namespace corresponding to the given prefix in the scope of the current element as a string or NOTHING if none is found. Called with no argument this function returns the default namespace. |
|
Y |
Moves the position of the current instance to the attribute with the specified qualified name. |
|
Y |
Moves the position of the current instance to the attribute with the specified local name and namespace URI. |
|
Y |
Moves the position of the current instance to the attribute with the specified index relative to the containing element. |
|
Y |
Moves the position of the current instance to the element node containing the current attribute node. |
|
Y |
Moves the position of the current instance to the first attribute of the current node. |
|
Y |
Moves the position of the current instance to the next attribute of the current node. |
|
Y |
Moves the position of the current instance to the next node in the tree at the same level, skipping any subtree. |
|
N |
Returns an XML string of the contents of the all current node's child nodes and markup, or NOTHING if the current node is neither an element nor an attribute or has no child nodes. |
|
N |
Returns an XML string of the contents of the current node and all child nodes and markup, or NOTHING if the current node is neither an element nor an attribute or has no child nodes. |
|
Y |
Set a RelaxNG schema for schema validation while parsing the XML document. This method must be called before the first call to XmlReader::read(). Not available if |
|
Y |
Set an XSD schema for schema validation while parsing the XML document. This method must be called before the first call to XmlReader::read(). Not available if |
Creates the XmlReader object based on the XmlDoc object or XML string passed.
XmlReader::constructor(XmlDoc
$doc
)
XmlReader::constructor(string
$xml
)
my XmlReader $xmlreader($xml);
Table 4.765. Exceptions thrown by XmlReader::constructor()
err |
desc |
---|---|
|
invalid argument, error in XML string, etc |
Creates an independent copy of the XmlReader object.
my XmlReader $xr = $xmlreader.copy();
Moves the position of the current instance to the next node in the stream. Returns True
if the read was successful, False
if there are no more nodes to read. If an error occurs parsing the XML string, an exception is raised (see below).
See also XmlReader::readSkipWhitespace().
XmlReader::read() returns bool
if (!$xmlreader.read())
break;
Table 4.766. Return Values for XmlReader::read()
Return Type |
Description |
---|---|
True if the read was successful, |
Table 4.767. Exceptions thrown by XmlReader::read()
err |
desc |
---|---|
|
cannot move to next node due to an error parsing the XML string (exception description string contains details about the error) |
Moves the position of the current instance to the next node in the stream, skipping any whitespace nodes. Returns True
if the read was successful, False
if there are no more nodes to read. If an error occurs parsing the XML string, an exception is raised (see below).
See also XmlReader::read().
XmlReader::readSkipWhitespace() returns bool
if (!$xmlreader.readSkipWhitespace())
break;
Table 4.768. Return Values for XmlReader::readSkipWhitespace()
Return Type |
Description |
---|---|
True if the read was successful, |
Table 4.769. Exceptions thrown by XmlReader::readSkipWhitespace()
err |
desc |
---|---|
|
cannot move to next node due to an error parsing the XML string (exception description string contains details about the error) |
Returns the node type of the current node; for return values, see XML Node Type Constants.
See also NodeTypeMap.
See also XmlReader::nodeTypeName()
XmlReader::nodeType() returns int
$value = $xmlreader.nodeType();
Table 4.770. Return Values for XmlReader::nodeType()
Return Type |
Description |
---|---|
the node type of the current node; for return values, see XML Node Type Constants |
Returns a string giving the node type of the current node or NOTHING if no current node is available; for possible return values, see the values of the NodeTypeMap constant.
See also XmlReader::nodeType()
XmlReader::nodeTypeName() returns any
$value = $xmlreader.nodeTypeName();
Table 4.771. Return Values for XmlReader::nodeTypeName()
Return Type |
Description |
---|---|
a string giving the node type of the current node or NOTHING if no current node is available; for possible return values, see the values of the NodeTypeMap constant |
Returns the depth of the node in the tree.
XmlReader::depth() returns int
$value = $xmlreader.depth();
Table 4.772. Return Values for XmlReader::depth()
Return Type |
Description |
---|---|
the depth of the node in the tree |
Returns the qualified name of the node (prefix:LocalName) or NOTHING if no name is available.
See also XmlReader::localName().
XmlReader::name() returns any
$value = $xmlreader.name();
Returns the text value of the node or NOTHING if not available.
XmlReader::value() returns any
$value = $xmlreader.value();
Returns True
if the node has attributes or False
if not.
XmlReader::hasAttributes() returns bool
$value = $xmlreader.hasAttributes();
Table 4.775. Return Values for XmlReader::hasAttributes()
Return Type |
Description |
---|---|
True if the node has attributes, |
Returns True
if the node has a text value or False
if not.
XmlReader::hasValue() returns bool
$value = $xmlreader.hasValue();
Table 4.776. Return Values for XmlReader::hasValue()
Return Type |
Description |
---|---|
True if the node has a text value, |
Returns True
if an attribute node was generated from the default value defined in the DTD or schema, False
if not.
XmlReader::isDefault() returns bool
$value = $xmlreader.isDefault();
Table 4.777. Return Values for XmlReader::isDefault()
Return Type |
Description |
---|---|
True if the node an attribute node was generated from the default value defined in the DTD or schema, |
Returns True
if the current node is empty or False
if not.
XmlReader::isEmptyElement() returns bool
$value = $xmlreader.isEmptyElement();
Table 4.778. Return Values for XmlReader::isEmptyElement()
Return Type |
Description |
---|---|
True if the current node is empty, |
Returns True
if the current node is a namespace declaration rather than a regular attribute or False
if not.
XmlReader::isNamespaceDecl() returns bool
$value = $xmlreader.isNamespaceDecl();
Table 4.779. Return Values for XmlReader::isNamespaceDecl()
Return Type |
Description |
---|---|
True if the current node is a namespace declaration rather than a regular attribute, |
Returns True
if the current reader parser context is valid, False
if not
XmlReader::isValid() returns bool
$value = $xmlreader.isValid();
Table 4.780. Return Values for XmlReader::isValid()
Return Type |
Description |
---|---|
True if the current reader parser context is valid, |
Returns Qore data corresponding to the XML starting at the current node position. If there are sub elements, a hash of the XML is returned, the sub elements representing the current node's children. If duplicate, out-of-order XML elements are found in the input string, they are deserialized to Qore hash elements with the same name as the XML element but including a caret "^" and a numeric prefix to maintain the same key order in the Qore hash as in the input XML string.
If only text is present at the current element, a string is returned. If no information is available, then NOTHING is returned.
See also XmlReader::toQoreData().
Functionally similar to parseXML()
XmlReader::toQore() returns any
$value = $xmlreader.toQore();
Table 4.781. Return Values for XmlReader::toQore()
Return Type |
Description |
---|---|
Returns Qore data corresponding to the XML starting at the current node position. If there are sub elements, a hash of the XML is returned, the sub elements representing the current node's children; XML element order is maintained by appending a suffix to key names. If only text is present at the current element, a string is returned. If no information is available, then NOTHING is returned. |
Table 4.782. Exceptions thrown by XmlReader::toQore()
err |
desc |
---|---|
|
error parsing the XML string (exception description string contains details about the error) |
Returns Qore data corresponding to the XML starting at the current node position. If there are sub elements, a hash of the XML is returned, the sub elements representing the current node's children. Note that data deserialized with this method may not be reserialized to an identical XML string due to the fact that XML elements with the same name are collapsed into Qore lists in the resulting Qore hash irrespective of the order in the original XML string.
If only text is present at the current element, a string is returned. If no information is available, then NOTHING is returned.
See also XmlReader::toQore().
Functionally similar to parseXMLAsData()
XmlReader::toQoreData() returns any
$value = $xmlreader.toQoreData();
Table 4.783. Return Values for XmlReader::toQoreData()
Return Type |
Description |
---|---|
Returns Qore data corresponding to the XML starting at the current node position. If there are sub elements, a hash of the XML is returned, the sub elements representing the current node's children; does not guarantee to maintain XML element order in the hash as elements at the same level with the same name are collapsed to a Qore list. If only text is present at the current element, a string is returned. If no information is available, then NOTHING is returned. |
Table 4.784. Exceptions thrown by XmlReader::toQoreData()
err |
desc |
---|---|
|
error parsing the XML string (exception description string contains details about the error) |
Returns the number of attributes of the current node
XmlReader::attributeCount() returns int
$value = $xmlreader.attributeCount();
Table 4.785. Return Values for XmlReader::attributeCount()
Return Type |
Description |
---|---|
the number of attributes of the current node |
Returns the base URI of the node if known, NOTHING if not.
XmlReader::baseUri() returns any
$value = $xmlreader.baseUri();
Returns the encoding string given in the XML string or NOTHING if none is given.
XmlReader::encoding() returns any
$value = $xmlreader.encoding();
Returns the local name of the node or NOTHING if no name is available.
XmlReader::localName() returns any
$value = $xmlreader.localName();
Returns the URI defining the namespace associated with the node, or NOTHING if not available.
XmlReader::namespaceUri() returns any
$value = $xmlreader.namespaceUri();
Returns the shorthand reference to the namespace associated with the node, or NOTHING if not available.
XmlReader::prefix() returns any
$value = $xmlreader.prefix();
Returns the xml:lang scope within which the node resides or NOTHING if there is none.
XmlReader::xmlLang() returns any
$value = $xmlreader.xmlLang();
Returns a string giving the XML version of the source document (normally "1.0") or NOTHING if none is present.
XmlReader::xmlVersion() returns any
$value = $xmlreader.xmlVersion();
Returns the value of the attribute matching the qualified name passed, or NOTHING if no such attribute exists in the current XmlReader.
See also XmlReader::getAttributeNs()
XmlReader::getAttribute(string
$attr
) returns any
$value = $xmlreader.getAttribute($name);
Table 4.793. Arguments for XmlReader::getAttribute()
Argument | Description |
---|---|
| The name of the attribute to retrieve |
Table 4.795. Exceptions thrown by XmlReader::getAttribute()
err |
desc |
---|---|
|
missing or invalid argument |
Returns the value of the given attribute anchored in the given namespace, or NOTHING if no such attribute exists in the current XmlReader.
See also XmlReader::getAttribute()
XmlReader::getAttributeNs(string
$attr
, string $ns
) returns any
$value = $xmlreader.getAttributeNs($localname, $namespaceuri);
Table 4.798. Exceptions thrown by XmlReader::getAttributeNs()
err |
desc |
---|---|
|
missing or invalid argument |
Returns the value of the attribute with the specified index relative to the containing element, or NOTHING if no such attribute exists in the current XmlReader.
See also XmlReader::getAttribute()
XmlReader::getAttributeOffset(softint
$offset
= 0) returns any
$value = $xmlreader.getAttributeOffset($offset);
Table 4.799. Arguments for XmlReader::getAttributeOffset()
Argument | Description |
---|---|
|
the index of the attribute relative to the containing element |
returns the namespace corresponding to the given prefix in the scope of the current element. If no prefix is given, the default namespace is returned.
XmlReader::lookupNamespace() returns any
XmlReader::lookupNamespace(string
$ns
) returns any
$value = $xmlreader.lookupNamespace($prefix);
Table 4.801. Arguments for XmlReader::lookupNamespace()
Argument |
Description |
---|---|
|
The namespace prefix to resolve; if no value is sent for this argument, the default namespace is returned. |
Moves the position of the current instance to the attribute with the specified qualified name.
See also XmlReader::moveToAttributeNs()
XmlReader::moveToAttribute(string
$attr
) returns bool
$value = $xmlreader.moveToAttribute($name);
Table 4.803. Arguments for XmlReader::moveToAttribute()
Argument |
Description |
---|---|
|
The qualified name of the attribute to move to |
Table 4.804. Return Values for XmlReader::moveToAttribute()
Return Type |
Description |
---|---|
True in case of success, |
Table 4.805. Exceptions thrown by XmlReader::moveToAttribute()
err |
desc |
---|---|
| missing or invalid argument |
| error parsing XML |
Moves the position of the current instance to the attribute with the specified local name and namespace URI.
See also XmlReader::moveToAttribute()
XmlReader::moveToAttributeNs(string
$attr
, string $ns
) returns bool
$value = $xmlreader.moveToAttributeNs($localname, $namespaceuri);
Table 4.807. Return Values for XmlReader::moveToAttributeNs()
Return Type |
Description |
---|---|
True in case of success, |
Table 4.808. Exceptions thrown by XmlReader::moveToAttributeNs()
err |
desc |
---|---|
|
missing or invalid argument |
| an error occured parsing the XML string |
Moves the position of the current instance to the attribute with the specified index relative to the containing element.
See also XmlReader::moveToAttribute()
XmlReader::moveToAttributeOffset(softint
$offset
) returns bool
$b = $xmlreader.moveToAttributeOffset($offset);
Table 4.809. Arguments for XmlReader::moveToAttributeOffset()
Argument | Description |
---|---|
|
the index of the attribute relative to the containing element to move to |
Table 4.810. Return Values for XmlReader::moveToAttributeOffset()
Return Type |
Description |
---|---|
True in case of success, |
Table 4.811. Exceptions thrown by XmlReader::moveToAttributeOffset()
err |
desc |
---|---|
| an error occured parsing the XML string |
Moves the position of the current instance to the element node containing the current attribute node.
XmlReader::moveToElement() returns bool
$value = $xmlreader.moveToElement();
Table 4.812. Return Values for XmlReader::moveToElement()
Return Type |
Description |
---|---|
True in case of success, |
Table 4.813. Exceptions thrown by XmlReader::moveToElement()
err |
desc |
---|---|
| an error occured parsing the XML string |
Moves the position of the current instance to the first attribute of the current node.
XmlReader::moveToFirstAttribute() returns bool
$value = $xmlreader.moveToFirstAttribute();
Table 4.814. Return Values for XmlReader::moveToFirstAttribute()
Return Type |
Description |
---|---|
True in case of success, |
Table 4.815. Exceptions thrown by XmlReader::moveToFirstAttribute()
err |
desc |
---|---|
| an error occured parsing the XML string |
Moves the position of the current instance to the next attribute of the current node.
XmlReader::moveToNextAttribute() returns bool
$value = $xmlreader.moveToNextAttribute();
Table 4.816. Return Values for XmlReader::moveToNextAttribute()
Return Type |
Description |
---|---|
True in case of success, |
Table 4.817. Exceptions thrown by XmlReader::moveToNextAttribute()
err |
desc |
---|---|
| an error occured parsing the XML string |
Moves the position of the current instance to the next node in the tree at the same level, skipping any subtree. Returns True
if the operation succeeded, False
if there are no more nodes to read. If an error occurs parsing the XML string, an exception is raised.
XmlReader::next() returns bool
$value = $xmlreader.next();
Table 4.818. Return Values for XmlReader::next()
Return Type |
Description |
---|---|
True in case of success, |
Table 4.819. Exceptions thrown by XmlReader::next()
err |
desc |
---|---|
| an error occured parsing the XML string |
Returns an XML string of the contents of the all current node's child nodes and markup, or NOTHING if the current node is neither an element nor an attribute or has no child nodes.
See also XmlReader::getOuterXml().
XmlReader::getInnerXml() returns any
$value = $xmlreader.getInnerXml();
Returns an XML string of the contents of the current node and all child nodes and markup, or NOTHING if the current node is neither an element nor an attribute or has no child nodes.
See also XmlReader::getInnerXml().
XmlReader::getOuterXml() returns any
$value = $xmlreader.getOuterXml();
Set a RelaxNG schema for schema validation while parsing the XML document. This method must be called before the first call to XmlReader::read()
The availability of this function depends on the presence of libxml2's xmlTextReaderRelaxNGValidate()
function when Qore was compiled; for maximum portability check the constant HAVE_PARSEXMLWITHRELAXNG
before calling this method. See Library Option Constants for a list of all option constants.
If any errors occur, an exception is thrown (see below).
XmlReader::relaxNGValidate(string
$relaxng
) returns nothing
$xmlreader.relaxNGValidate($rng);
Table 4.822. Arguments for XmlReader::relaxNGValidate()
Argument | Description |
---|---|
| The RelaxNG schema to use to validate the XML string while parsing. |
Table 4.823. Exceptions thrown by XmlReader::relaxNGValidate()
err |
desc |
---|---|
|
missing or invalid argument |
|
invalid RelaxNG schema or method called after the first call to XmlReader::read() |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Set an XSD schema for schema validation while parsing the XML document. This method must be called before the first call to XmlReader::read()
The availability of this function depends on the presence of libxml2's xmlTextReaderSchemaValidate()
function when Qore was compiled; for maximum portability check the constant HAVE_PARSEXMLWITHSCHEMA
before calling this method. See Library Option Constants for a list of all option constants.
If any errors occur, an exception is thrown (see below).
XmlReader::schemaValidate(string
$xsd
) returns nothing
$xmlreader.schemaValidate($xsd);
Table 4.824. Arguments for XmlReader::schemaValidate()
Argument | Description |
---|---|
| The XSD schema to use to validate the XML string while parsing. |
Table 4.825. Exceptions thrown by XmlReader::schemaValidate()
err |
desc |
---|---|
|
missing or invalid argument |
|
invalid RelaxNG schema or method called after the first call to XmlReader::read() |
| This exception is thrown when the function is not available; for maximum portability, check the constan
t |
Qore will scan the command-line for the options in the following table. Arguments after the script name will be passed to the script in the global $ARGV
variable as a list of options. $ARGV[0]
will be the first option and will not be the script name. If no script name is given and the --exec
option is not used, then Qore code is read from standard input.
qore
[options] script.q
Table 5.1. Parse Option Command-Line Parameters
Long Param | Short | Description |
---|---|---|
|
| Loads a module immediately. The argument can be a module/feature name or an absolute path to the module. |
|
| Disallows the use of global variables. Equivalent to parse option |
|
| Disallows subroutine (function) definitions. Equivalent to parse option |
|
| Disallows any thread control operations (background operator and thread_exit statement, for example). Equivalent to parse option |
|
| Disallows access to thread classes (for example, the Thread::Mutex Class, Thread::Gate Class, Thread::Queue Class, etc). Equivalent to parse option |
|
| Disallows access to both thread control and thread classes (equivalent to the --no-thread-control and --no-thread-classes options documented above). Equivalent to parse option |
|
| Disallows top level code. Equivalent to parse option |
|
| Disallows class definitions. Equivalent to |
|
| Disallows new namespace definitions. Equivalent to |
|
| Disallows any access to external processes (with system(), backquote(), exec(), the backquote operator, etc). Equivalent to parse option |
|
| Disallows access to functions that would affect the current process (exit(), fork(), etc). Equivalent to parse option |
|
| Disallows access to the local filesystem; puts the |
|
| Disallows constant definitions. Equivalent to parse option |
|
| Disallows access to the network; puts the |
|
| Disallows use of the new operator. Equivalent to parse option |
|
| Disallows use of database functionality. Equivalent to parse option |
|
| Allows child program objects to have parse option restrictions that are not a strict subset of the parents. Equivalent to parse option |
|
| Requires global variables to be declared with our prior to use (similar to perl's use strict vars pragma). Equivalent to parse option |
|
| Prohibits further changes to parse options (equivalent to the |
|
| Prohibits further changes to the warning mask. Equivalent to parse option |
|
| Enables all warnings. Equivalent to the |
|
| Enables the named warning. Equivalent to the |
|
| Lists all valid warnings in Qore and exits immediately. |
Table 5.2. Miscellaneous Command-Line Parameters
Long Param | Short | Description |
---|---|---|
|
| parses and executes the argument text as a Qore program. If this option is specified then any script given on the command-line will be ignored. |
|
| parses and executes the argument text as a Qore program, instantiating the class with the same name as the program (with the directory path and extension stripped); also turns on |
|
| Shows any errors loading Qore modules |
|
| Sets the default character encoding for the program |
| Shows a list of all known character encodings | |
| Shows a list of all known character encoding aliases | |
|
| Shows help text |
|
| Shows program version information and exits |
There are two additional options available with debugging versions of Qore as follows:
Table 5.3. Description of Debugging Command-Line Parameters
Long Param | Short | Description |
---|---|---|
--debug= | -d | Turns on Qore debugging output. Higher |
--trace | -t | Turns on Qore tracing. This option is only available with DEBUG builds. |
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.
Table 6.1. Parse Directives
Directive | Description |
---|---|
Turns off all warnings | |
| Disables the named warning until |
Turns on all warnings | |
| Enables the named warning. |
| Instantiates the named class as the application class. Also turns on |
| Starts parsing |
Prohibits further changes to parse options (equivalent to the | |
Prohibits further changes to the warning mask (equivalent to the | |
Disallows class definitions. Equivalent to | |
Allows child program objects to have parse option restrictions that are not a strict subset of the parents'. Equivalent to parse option | |
Disallows constant definitions. Equivalent to parse option | |
Disallows access to database functionality (for example the Datasource class. Equivalent to parse option | |
Disallows any access to functionality that provides external information (see | |
Disallows any access to external processes (see | |
Disallows access to the local filesystem. Equivalent to parse option | |
Disallows the use of global variables. Equivalent to parse option | |
Disallows functionality that draws graphics to the display. Equivalent to parse option | |
Disallows access to functionality that changes locale information (see | |
Disallows new namespace definitions. Equivalent to | |
Disallows access to the network. Equivalent to parse option | |
Disallows use of the new operator. Equivalent to parse option | |
Disallows access to functions that would affect the current process (see | |
Disallows subroutine (function) definitions. Equivalent to parse option | |
Disallows access to terminal I/O (see | |
Disallows access to thread classes (see | |
Disallows access to thread control operations (see | |
Disallows any access to functionality that provides threading information (see | |
Disallows access to all thread control operations and thread classes (equivalent to | |
Disallows top level code. Equivalent to parse option | |
Requires global variables to be declared with our prior to use (like perl's | |
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 | |
Requires type declarations for all function and method parameters, return types, variables, and object members. Equivalent to parse option | |
| If the named feature is not already present in Qore, then the |
Prohibits access to builtin functions and methods flagged with |
%disable-all-warnings
none, warnings are disabled by default
n/a
Disables all warnings while parsing. See Warnings for more information.
%disable-warning
none, warnings are disabled by default
n/a
Disables the named warning while parsing. See Warnings for more information.
%enable-all-warnings
--enable-all-warnings, -W
n/a
Enables all warnings while parsing. See Warnings for more information.
%enable-warning
--enable-warning, -w
n/a
Enables the named warning while parsing. See Warnings for more information.
%exec-class
--exec-class, -x
n/a
Executes the named class as the application class and turns on no-top-level
as well.
%include
n/a from the command-line
n/a
Includes a file to be parsed. If the path is not absolute (i.e. starting with '/'), 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
.
%lock-options
--lock-options, -K
n/a
Prohibits further changes to parse options.
%lock-warnings
--lock-warnings, -A
Prohibits further changes to the warning mask.
%no-child-restrictions
--no-child-restrictions, -I
Allows child program objects to have parse option restrictions that are not a strict subset of the parents'.
%no-class-defs
--no-class-defs
Disallows new class definitions. Any use of the reserved word class will result in a parse exception.
%no-constant-defs
--no-constant-defs
Disallows new constant definitions. Any use of the reserved word const will result in a parse exception.
%no-database
--no-database, -D
Disallows access to database functionality. Currently this means that access to the Datasource and DatasourcePool classes is restricted.
%no-filesystem
--no-filesystem, -F
Disallows any access to the external filesystem.
Table 6.4. Unavailable Features with no-filesystem
Feature/Function |
---|
Dir class |
File class |
FtpClient::get() method |
FtpClient::put() method |
%no-global-vars
--no-global-vars, -G
Disallows the use of global variables.
%no-gui
--no-gui, --set-parse-option=no-gui, -pno-gui
Disallows the use of functionality that draws graphics to the display (this functionality is not implemented in the qore library; only implemented in modules).
%no-locale-control
--no-locale-control, -P
Disallows access to functions that would affect the current process.
Table 6.5. Unavailable Features with no-locale-control
Feature/Function |
---|
TimeZone::set() static method |
TimeZone::setUTCOffset() static method |
TimeZone::setRegion() static method |
%no-namespace-defs
--no-namespace-defs, -M
Disallows new namespace definitions.
%no-network
--no-network, -Y
Disallows any access to the network.
Table 6.6. Unavailable Features with no-network
Feature/Function |
---|
FtpClient class |
HTTPClient class |
XmlRpcClient class |
JsonRpcClient class |
Socket class |
%no-subroutine-defs
--no-subroutine-defs, -S
Disallows subroutine (function) definitions.
%no-thread-classes
--no-thread-classes
Disallows access to thread classes.
Table 6.9. Unavailable Features with no-thread-classes
Feature/Function |
---|
AutoGate class |
AutoLock class |
AutoReadLock class |
AutoWriteLock class |
Condition class |
Counter class |
Mutex class |
Queue class |
RWLock class |
%no-thread-info
--no-thread-info
Disallows access to functionality that provides information about threading.
Table 6.11. Unavailable Features with no-thread-info
Feature/Function |
---|
gettid() function |
num_threads() function |
thread_list() function |
get_thread_data() function |
get_all_thread_data() function |
getAllThreadCallStacks() function |
%no-threads
--no-threads, -T
Disallows access to all thread control operations and thread classes (equivalent to no-thread-control
and no-thread-classes
together).
%no-top-level
--no-top-level, -L
Disallows top level code.
%require-our
--require-our, -O
Requires global variables to be declared with our prior to use (recommended to use for all larger scripts/programs).
%require-prototypes
--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 with this option.
See also require-types, which is a superset of this option.
%require-types
--require-types
Requires type declarations for all function and method parameters, return types, variables, and object members.
See also require-prototypes, which is a subset of this option.
%requires
--load, -l
n/a
Loads a Qore module immediately. The parse directive can be used to load a module during parsing, and the command-line version can be used to load a module before parsing.
From Qore 0.7.1, 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 exteneded to "1.0.0").
For example:
%requires oracle >= 1.0.1
This will load the oracle module if it is at least version 1.0.1.
Note that there is one special feature name: "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.
%strict-args
--strict-args
Prohibits access to builtin functions and methods flagged with RT_NOOP
and also causes errors to be raised if excess arguments are given to functions that do not access excess arguments.
Warnings give the programmer information about possible errors in qore code.
Warnings can be enabled using the -W command-line option (see Command-Line Parsing for more information) or by using the %enable-all-warnings
or %enable-warning
parse directives.
Note that parsing is done in two stages, so if a warning is enabled when the second stage of parsing begins, the warning can be generated anywhere in the source code. Parse directives are processed in the first stage of parsing. In other words, for warnings only raised in the second stage of parsing, it is not possible to turn on and turn off these warnings for specific code blocks within a section of text being parsed.
Table 7.1. Warnings
Warning Code | First In | Description |
---|---|---|
|
| This warning is raised when the same local variable is declared more than once within the same lexical scope. |
|
| This warning is raised when a program tries to change the warning mask with parse options, but the warnings are locked. |
|
| This warning is raised when a program tries to enable or disable an unknown warning. |
|
| This warning is raised when a program uses a variable that has not been declared with my or our. |
|
| Raised when a program declares a global variable more than once. |
|
| Raised when code is defined that can never be executed (for example, code following a return or thread_exit statement). |
|
| Warning is raised when the given method cannot be found in the class at parse time; this is a warning because the object could be a subclass that has the given method implemented, in which case the call will succeed at run time. Use the cast<>() operator to avoid this warning. |
|
| Raised when the parser determins that the types of an operation are such that the operation is guaranteed to produce no value; this warning can only be raised when type information is available at parse time. |
|
| Raised when the parser determines that the argument types of a function or method call are such that the operation is guaranteed to produce a constant value. |
|
| Raised when a function or method call is made with no side effects and the return value is ignored. |
|
| Raised when deprecated functionality is accessed. |
|
| Raised when a function or method call is made with more arguments than are used by the function or method. |
|
| Raised when an immediate hash is declared and at least one of the keys is repeated. |
The following is a list of all keywords in the Qore language that may not be used as funciton or method names and also may not be used as unquoted hash or object member names with the "." operator:
by,
break,
catch,
const,
context,
continue,
do,
else,
for,
foreach,
if,
in,
inherits,
instanceof,
namespace,
my,
NOTHING,
NULL,
on_error,
on_exit,
on_success,
our,
rethrow,
return,
sortBy,
sortDescendingBy,
sub,
subcontext,
summarize,
switch,
synchronized,
thread_exit,
throw,
try,
where,
while
The following are special keywords, in that a parser trick is used allowing them to be used as function or method names if they are followed immediately by an open parenthesis (with no whitespace between the keyword and the open parenthesis), and they may be referenced as unquoted object or hash member names if they are immediately preceded by the "." operator (again with no whitespace between the "." and the keyword):
background,
case,
chomp
class,
delete,
exists,
foldl,
foldr,
map,
pop,
private,
push,
new,
select,
shift,
splice,
trim,
unshift
The following are special keywords, in that a parser trick is used allowing them to be used as function or method names if they are followed by an open parenthesis (in the case of these keywords, it is permissable to have whitespace between the keyword and the open parenthesis), and they may be referenced as unquoted object or hash member names if they are immediately preceded by the "." operator (again with no whitespace between the "." and the keyword):
The following are special keywords, in that they may be referenced as unquoted object or hash member names if preceded immediately by the "." operator, however they may not be used as function or class method names:
Out of memory errors are not always captured. Internal support for trapping these conditions in the C++ new operator must be developed.
In general, Qore's main development target is to provide a stable, powerful, and efficient platform for developing complex programs. Backwards compatibility is a very high priority, even for versions before 1.0, and "unrestricted" code (code not subect to parse restrictions) should remain highly compatible until 1.0 and beyond.
There is no stable list of features that need to be there before the 1.0 release; Qore is getting better, cleaner, and more powerful with each release, so sooner or later 1.0 will happen.