v. 0.7.6
Revision History | ||
---|---|---|
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 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.
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 is a weakly typed language. That means that variables can hold values of any type and subroutines can return any value type (or none at all, see Variables). 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 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 Sybase DBI driver to Qore. |
| Provides a FreeTDS-based DBI driver to Qore. |
| Provides an Oracle DBI driver to Qore. |
| Provides GLUT functionality to Qore. |
| Provides an OpenGL API to Qore. |
| Provides QT4 APIs to Qore. |
| Provides curses APIs 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 for more 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 |
$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.
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 $a = 1; # this is a global variable our ($b, $c, $d); # list of global variables if ($a == 1) { my $a = 2; my ($b, $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:
Table 2.6. Basic data types
Type | Description | Example | Default Value |
---|---|---|---|
True or False value | True | False | |
A sequence of characters | "string" | Empty string | |
A 64-bit signed integer | 1 | 0 | |
A double-precision floating-point number | 1.00023 | 0.0 | |
A date with an optional time component, with resolution to the millisecond. | 2005-07-20 | 1970-01-01 00:00:00 | |
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) | NULL | NULL | |
Represents the state of a variable having no value or function returning no value (not equivalent to NULL) | NOTHING | NOTHING |
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";
Qore dates have a time component supporting a resolution to the millisecond and can be either absolute or relative.
Absolute date/time values specify a specific point in time, such as January 1, 2005 10:35:00 and can be specified with a special syntax as follows:
<4d-year>-<2d-month>-<2d-day>[-<2d-hour>:<2d-minute>:<2d-second>[.<3d-millisecond>]]
or, an almost-ISO-8601-compliant format (without the ISO-8601 time zone component but including an optional millisecond component)
<4d-year>-<2d-month>-<2d-day>[T<2d-hour>:<2d-minute>:<2d-second>[.<3d-millisecond>]]
for example, for just the date, without a time component:
<4d-year>-<2d-month>-<2d-day>
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):
<2d-hour>:<2d-minute>:<2d-second>[.<3d-millisecond>]]
Some examples should make it clearer:
2005-03-29-18:12:25 # represents: March 29, 2005 6:12:25 pm 0512-01-01T01:49:59.213 # represents: January 1, 512 1:49:59 am and 213 milliseconds 2005-03-29 # represents: March 29, 2005 00:00:00 18:35:26 # represents: January 1, 1970 6:35:26 pm (start of the Qore epoch)
The year must be a four-digit number, and all other values except milliseconds must be two-digit numbers. If milliseconds are present, 3 digits are required after the decimal point. Pad the numbers with leading zeros if the numbers are smaller than the required number of spaces. 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.
Currently there is no time-zone component in Qore dates. Timezone support may be added in future versions of the Qore language, either by an addition to this data type, or by adding another date type including a time zone component. Specifically, ISO-8601 time zone components are not accepted by the qore parser and will cause a parse exception to be thrown.
Relative date/time values are specified as follows:
<integer><date component specifier>
Table 2.7. Date Specifiers For Relative Dates
Component | Meaning | Example | Description |
---|---|---|---|
Y | Years | 2Y | 2 Years |
M | Months | 3M | 3 Months |
D | Days | 10D | 10 Days |
h | Hours | 15h | 15 hours |
m | Minutes | 25m | 25 minutes |
s | Seconds | 19s | 19 seconds |
ms | Milliseconds | 250ms | 250 milliseconds |
Relative dates are normally used for date addition and subtraction. See Date/Time Arithmetic for more information.
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. When calculating second offsets from this date, a 64-bit integer is used.
The binary data type is used to hold binary arbitrary binary data. Internally it is represented by a memory pointer and a size indicator.
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.
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 to/from strings, the following format must be used: "YYYYMMDDHHmmSS".
When dates are converted to and from integer values, the a 64-bit second offset from January 1, 1970 is used for the conversion. For example int(2006-01-01)
gives 1136073600
.
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 on objects and classes). 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:
$list = 1, 2, "three", 4.0, 5, 6;
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:
$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 only literal strings can be used.
$element3 = $hash{"pe" + "ar"};
Is equivalent to:
$element3 = $hash.pear;
and:
$element3 = $hash."pear";
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 resolved to a string).
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, and objects are 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.
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.8. 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.9. 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 | |
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 ($a) { 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.
QDir::setCurrent("/tmp");
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 () {
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.
# 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 $closure = sub ($a) { 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 (however note the important difference with the , operator as noted below). To explicitly specify the precedence for expression evaluation, use parentheses ().
Table 2.10. Operators
Operator | Prec. | Description | Example |
---|---|---|---|
`` | 1 | `ls -l` | |
{} | 1 | hash element or object member expression dereference operator | $hash{"na" + "me"} |
. | 1 |
| |
[] | 1 | $list[1] | |
++ | 2 | ++$a, $a++ | |
-- | 2 | --$a, $a-- | |
new | 3 | new Socket() | |
background | 3 | background mainThread() | |
! | 4 | if (!($a > 10)) ... | |
~ | 5 | $var = ~$var | |
- (unary minus) | 6 | $var = -$var | |
shift | 7 | shift $list | |
pop | 7 | pop $list | |
chomp | 7 | chomp $string | |
trim | 7 | trim $string | |
map | 7 | map $closure($1), $list | |
foldl | 7 | foldl $closure($1 - $2), $list | |
foldr | 7 | foldr $closure($1 - $2), $list | |
select | 7 | select $list, $1 > 1 | |
elements | 8 | elements $list | |
keys | 8 | keys $hash | |
* | 9 | $var = $a * 10 | |
/ | 9 | $var = $a / 10 | |
% | 10 | $var = $a % 10 | |
+ | 11 | plus operator: string, binary, list, and hash concatenation, integer and float addition |
|
- | 11 | $a - 10 | |
>> | 12 | 0xff00 >> 8 | |
<< | 12 | 0xff00 << 8 | |
exists | 13 | exists $var | |
instanceof | 13 | instanceof Qore::Mutex | |
< | 14 | $a < 10 | |
> | 14 | $a > 10 | |
== | 14 | $a == 10 | |
!= | 14 | $a != 10 | |
<= | 14 | $a <= 10 | |
>= | 14 | $a >= 10 | |
<=> | 14 | $a <=> $b | |
=== | 14 | $a === 10 | |
!== | 14 | $a !== 10 | |
=~ // | 14 | $a =~ /text/ | |
!~ // | 14 | $a !~ /text/ | |
=~ s/// | 14 | $a =~ s/text/text/ | |
=~ x// | 14 | $a =~ x/(\w+):(\w+)/ | |
=~ tr | 14 | $a =~ tr/src_chars/targ_chars/ | |
& | 15 | $a & 0xff | |
| | 15 | $a | 0xff | |
^ | 15 | $a ^ 0xff | |
&& | 16 | ($a = 1) && ($b < 10) | |
|| | 16 | ($a = 1) || ($b < 10) | |
? : | 17 | $a == 2 ? "yes" : "no" | |
, | 18 | 1, 2, 3, 4, 5 | |
unshift | 19 | unshift $list, $val | |
push | 19 | push $list, $val | |
splice | 19 | splice $list, 2, 2, (1, 2, 3) | |
= | 20 | $var = 1 | |
+= | 21 | $var += 5 | |
-= | 21 | $var -= 5 | |
&= | 21 | $var &= 0x2000 | |
|= | 21 | $var |= 0x2000 | |
%= | 21 | $var %= 100 | |
*= | 21 | $var *= 10 | |
/= | 21 | $var /= 10 | |
^= | 21 | $var ^= 0x2000 | |
<<= | 21 | $var <<= 0x2000 | |
>>= | 21 | $var >>= 0x2000 |
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.
The Qore comma ',' operator has a higher precendece than the '=' operator, meaning that a statement like $a = 1, 2, 3;
is possible without parentheses. However, it means that a statment like $a = func(1, 2, $b = 3, 4);
will probably not do what you want (it uses $b
as the third argument which is assigned to the list (3, 4)
); you must write $a = func(1, 2, ($b = 3), 4);
to pass 4 arguments to the function func
.
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`
Argument | Processing |
---|---|
| The shell command will be executed and the stdout is returned as a string. |
Table 2.11. 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.12. Arguments Processed by {}
Argument | Processing |
---|---|
| This expression must evaluate to a hash or an object. If not, then the operator returns no value. |
| 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.13. 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.14. 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.15. 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.16. 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.17. 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.18. 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.19. 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.20. 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.
new class_identifier(constructor_arguments ...)
$obj = new Qore::Mutex();
Table 2.21. 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 and NOTHING is returned. |
Table 2.22. 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.23. Arguments Processed By background
Argument | Processing |
---|---|
|
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.24. 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. |
Reverses the logical sense of an expression (True becomes False and False becomes True).
!expression
if (!exists $error_code) do_something();
Table 2.25. Arguments Processed By !
Argument | Processing |
---|---|
| The expression is evaluated and converted to Boolean, if necessary. Then the value is logically reversed (True becomes False, False becomes True) |
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.26. Arguments Processed By ~
Argument | Processing |
---|---|
| Performs bitwise negation on its argument (ex: 666 & ~27 = 640) |
This operator does not throw any exceptions.
Changes the sign of numeric values.
-expression
$a = -$b;
Table 2.27. Arguments Processed By Unary Minus -
Argument | Processing |
---|---|
| Gives the negative of its argument (ex: -(-1.1) = 1.1, -(1.1) = -1.1 |
| Gives the negative of its argument (ex: -(-1) = 1, -(1) = -1 |
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.28. Arguments Processed By shift
Argument | Processing |
---|---|
| 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.29. Arguments Processed By pop
Argument | Processing |
---|---|
| 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.30. Arguments Processed By chomp
Argument | Processing |
---|---|
| Removes any EOL characters from a string and returns the number of characters removed. |
| Removes any EOL characters from each string element of the list passed and returns the number of characters removed. |
| 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.31. Arguments Processed By trim
Argument | Processing |
---|---|
| Removes whitespace characters from the beginning and end of a string and returns the value processed. |
| Removes whitespace characters from the beginning and end of each string element of the list passed and returns the list. |
| 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.32. Arguments Processed By map
Argument | Processing |
---|---|
| The expression to map on the list; the implicit argument $1 represents the current element being processed. |
| 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 False on an element, then the element will be skipped and the map expression will not be applied on that element. |
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.33. 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. |
| 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.34. 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. |
| 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.35. Arguments Processed By select
Argument | Processing |
---|---|
| 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 True will the element appear in the result list. |
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;
Table 2.36. Arguments Processed By keys
Argument | Processing |
---|---|
List | Returns the number of elements in the list. |
Hash | Returns the number of keys in the hash. |
String | Returns the number of characters in the string. |
Binary | Returns the number of bytes in the binary object. |
This operator does not throw any exceptions.
Returns a list representing the keys in a hash.
keys hash_expression
foreach my $key in (keys $hash) printf("%s = %s\n", $key, $hash.$key);
Table 2.37. Arguments Processed By keys
Argument | Processing |
---|---|
| Returns a list of strings giving the keys in |
This operator does not throw any exceptions.
Multiplies two arguments.
expression1
*expression2
$value = $x * $y
Table 2.38. Argument Processing and Conversion Priorities for *
Argument | Processing |
---|---|
Float | Gives the result of multiplying its arguments. |
Integer | Gives the result of multiplying its arguments. |
This operator does not throw any exceptions.
Divides a number by another.
expression1
/expression2
$value = $x / $y;
Table 2.39. Argument Processing and Conversion Priorities for /
Argument | Processing |
---|---|
Float | Gives the result of dividing its arguments. |
Integer | Gives the result of dividing its arguments. |
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.40. Arguments Processed By %
Argument | Processing |
---|---|
Integer | 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.41. Argument Processing and Conversion Priorities for +
Argument | Processing |
---|---|
List | Gives the result of concatenating its arguments, i.e. (1, 2) + (3, 4) = (1, 2, 3, 4) |
String | Gives the result of concatenating its arguments. |
Date | Gives the result of adding date/time values (see Date/Time Arithmetic) |
Float | Gives the result of adding its arguments. |
Integer | Gives the result of adding its arguments. |
Hash | 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, 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.
expression1
-expression2
$num = $x - $y;
$hash = $hash - "key";
Table 2.42. Argument Processing and Conversion Priorities for -
Argument | Processing |
---|---|
Float | arithmetic subtraction: |
Integer | arithmetic subtraction: |
Hash - String | 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.43. Arguments Processed By >>
Argument | Processing |
---|---|
Integer | 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.44. Arguments Processed By <<
Argument | Processing |
---|---|
Integer | 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.45. 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.46. 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.47. Argument Processing and Conversion Priorities for <
Argument | Processing |
---|---|
Float | If |
Integer | If |
String | If |
Date | 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.48. Argument Processing and Conversion Priorities for >
Argument | Processing |
---|---|
Float | If |
Integer | If |
String | If |
Date | 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.49. Argument Processing and Conversion Priorities for ==
Argument | Processing |
---|---|
String | If |
Float | If |
Integer | If |
Date | If |
List | If each element in the each list where order is relevant satisfies this operator, the operator returns True, otherwise it returns False |
Hash | If each hash has the same keys and the value of each equal key in each hash satisfies this operator, the operator returns True, otherwise it returns False |
Binary | If |
Object | If |
NULL | If both expressions are NULL, returns True, otherwise returns False |
NOTHING | If neither expression has a value, returns True, otherwise returns False |
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.50. Argument Processing and Conversion Priorities for !=
Argument | Processing |
---|---|
String | If |
Float | If |
Integer | If |
Date | If |
List | If any element in the each list compared where order is relevant satisfies this operator, the operator returns True, otherwise it returns False |
Hash | If the hashes have different key sets, or the values of any equal key in each hash satisfies this operator, the operator returns True, otherwise it returns False |
Binary | If either |
Object | If |
NULL | If one expression is NULL and the other not, returns True, otherwise False. |
NOTHING | If one of the expressions has a value, returns True, otherwise False. |
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.51. Argument Processing and Conversion Priorities for <=
Argument | Processing |
---|---|
Float | If |
Integer | If |
String | If |
Date | 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.52. Argument Processing and Conversion Priorities for >=
Argument | Processing |
---|---|
Float | If |
Integer | If |
String | If |
Date | 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.53. Argument Processing and Conversion Priorities for <=>
Argument | Processing |
---|---|
String | If |
Float | If |
Integer | If |
Date | 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.54. Arguments Processed By ===
Argument | Processing |
---|---|
All | This operator returns True only if the types and values of both sides of the operator are exactly equal, otherwise returns False. No type conversions are done. |
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.55. Arguments Processed By !==
Argument | Processing |
---|---|
All | This operator returns True if either the types or the values of the arguments are different, otherwise it retuns False. No type conversions are done. |
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.
expression
=~ [m]/regex
/[isxm]
if ($str =~ /hello/)
printf("%s contains 'hello'\n", $str);
Table 2.56. Arguments Processed By =~
Argument | Processing |
---|---|
String | This operator returns True if the regular expression in |
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.
expression
!~ [m]/regex
/[isxm]
if ($str !~ /hello/)
printf("%s does not contain 'hello'\n", $str);
Table 2.57. Arguments Processed By !~
Argument | Processing |
---|---|
String | This operator returns True if the regular expression in |
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.
lvalue
=~ s/regex_pattern
/target_string
/[isxmg]
$str =~ s/hello/goodbye/i;
$str =~ s/(\w+) +(\w+)/$2, $1/;
Table 2.58. Arguments Processed By =~ s///
Argument | Processing |
---|---|
String | 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.
string
=~ x/regex_with_patterns
/[isxm]
$list =~ x/(\w+):(\w+)/;
$list =~ x/(.*)\.(.*)/;
Table 2.59. Arguments Processed By =~ x//
Argument | Processing |
---|---|
String | This operator extracts strings from the |
This operator does not throw any exceptions.
Makes character substitutions in an lvalue; character ranges can also be used.
lvalue
=~ tr/source_chars
/target_chars
/
$str =~ tr/a-z/A-Z/;
Table 2.60. Arguments Processed By =~ tr//
Argument | Processing |
---|---|
String | 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.61. Arguments Processed By &
Argument | Processing |
---|---|
Integer | 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.62. Arguments Processed By |
Argument | Processing |
---|---|
Integer | 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.63. Arguments Processed By ^
Argument | Processing |
---|---|
Integer | 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.
expression1
&&expression2
if ($x && $y)
printf("%n and %n are both True\n", $x, $y);
Table 2.64. Arguments Processed By &&
Argument | Processing |
---|---|
Integer | Returns True if both expressions are True, False if otherwise. Logical short-circuiting is implemented; if |
This operator does not throw any exceptions.
Returns True if either of the arguments are True.
expression1
||expression2
if ($x || $y)
printf("either %n or %n or both are True\n", $x, $y);
Table 2.65. Arguments Processed By ||
Argument | Processing |
---|---|
Integer | Returns True if either or both expressions evaluate to True, False if otherwise. Logical short-circuiting is implemented; if |
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.66. 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.67. 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.68. Arguments Processed By unshift
Argument | Processing |
---|---|
All | Inserts the value of |
Adds one element to the end of a list.
push lvalue, expression
push $list, "last";
Table 2.69. 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.
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.70. 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. |
Assigns a value to an lvalue.
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;
Table 2.72. Arguments Processed By +=
Argument | Processing |
---|---|
| 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. |
| the expression will be evaluated and converted to a string if necessary and concatenated to the lvalue. |
| the expression will be evaluated and converted to a float if necessary and added to the lvalue. |
| the expression will be evaluated and converted to a string if necessary and added to the lvalue. |
| 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;
Table 2.73. Arguments Processed By -=
Argument | Processing |
---|---|
| the expression will be evaluated and converted to a float if necessary and subtracted from the lvalue |
| the hash key represented by |
| the lvalue will be assigned to - |
| 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 subtracted from the lvalue |
Performs a bitwise (binary) AND operation on an lvalue using the value of an expression.
lvalue
&=expression
$a &= 0xfe;
Table 2.74. 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.
lvalue
|=expression
$a |= 0xba;
Table 2.75. 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.
lvalue
%=expression
$a %= 100;
Table 2.76. 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 |
Performs a multiplication operation on an lvalue using the value of an expression.
lvalue
*=expression
$a *= 10;
Table 2.77. 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. |
Performs a division operation on an lvalue using the value of an expression.
lvalue
/=expression
$a /= 10;
Table 2.78. 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.79. 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.80. 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.
lvalue
<<=expression
$a <<= 3;
Table 2.81. 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.
lvalue
>>=expression
$a >>= 3;
Table 2.82. 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.83. Regular Expression Operators
Operator | Description |
---|---|
Returns True if the regular expression matches a string. | |
Returns True if the regular expression does not match a string. | |
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.84. 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.85. Regular Expression Functions
Function | Description |
---|---|
Returns True if the regular expression matches a string. | |
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 and months with different lengths, 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:
2004-02-29 - 1Y = 2003-02-28
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:
2004-02-29T10:15:00 - 10D = 2004-02-19T10:15:00
Subtracting one absolulte date from another will result in a relative date, normalized to the day value (that is, milliseconds over 999 are converted to seconds, seconds over 59 to minutes, minutes over 59 to hours, hours over 23 to 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:
$diff = 2007-02-29T10:15:03.255 - 2004-02-29T10:14:02.100; printf("%n\n", $diff)
Results in:
<time: 1096 days 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:
int(2004-02-29) - int(2004-02-28) = 86400
Qore has no time zone support and therefore all date/time values are timezone agnostic. In particular, Daylight Savings Time is not taken into effect with date arithmetic. For this reason a day in Qore is always exactly 24 hours long.
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.86. 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 delete statement | delete | delete statements |
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.
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.87. 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 delete the contents of an lvalue, the delete statement can be used. For objects, this will also run the destructor method (if defined for the class).
delete $lvalue;
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(%effective_start_date, "YYYY-MM-DD HH:mm:SS")); }
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(%effective_start_date, "YYYY-MM-DD HH:mm:SS")); }
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(%effective_start_date, "YYYY-MM-DD HH:mm:SS")); subcontext sortDescendingBy (%effective_end_date) { printf("\tservice %s: ends: %s\n", %msisdn, format_date(%effective_end_date, "YYYY-MM-DD HH:mm:SS")); } }
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() { return "Barney"; } $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_exit 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_exit 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.
{ $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
([variable1, variable2, ...
]) {statements;
}
Variables listed in parentheses by the subroutine name 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.
Subroutines can use the return statement to provide a return value. Subroutine names must be valid Qore identifiers.
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) { 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($num) { 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 breadth-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. Constants are defined with the following syntax:
const [namespace_path
::]constant_identifier
=value
;
The value cannot require run-time evaluation (executes a function, has a variable reference, uses an operator that changes values, etc) or a parse exception will be raised.
Objects are instantiations of a Qore class. Classes 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] [namespace_path::
...]class_identifier
[, ...]] { [private$.var1[, ...]
;] [static] [synchronized] [private] [namespace_path
::]method_name_identifier
([$var1, $var2, ...]) {statements
; } ... }
Alternatively objects can be defined out of line as follows:
class [namespace_path::
]class_identifier
[inherits [private] [namespace_path::
...]class_identifier
[, ...]]; [static] [synchronized] [private] [namespace_path::
]class_identifier
::method_identifier
([$var1, $var2, ...]) {statements
; }
Private members can only be declared in an in-line class definition (the first example above).
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.88. Special Methods
Name | Description |
---|---|
| Called when objects are created 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. In a class tree, |
| 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. In a class tree, |
| 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. In a class tree, |
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.
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.
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([$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($opts) : 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($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 $o = new TestObject(); # 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($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 $o = new TestObject(); # 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 statement). 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.89. 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.90. 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.91. 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.92. 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 statement, 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.93. 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.
Table 2.94. 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.95. 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 curerntly 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.96. 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.97. 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.98. 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.99. 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.100. 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.101. 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.102. 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.103. 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.104. 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.105. 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.106. 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.107. 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.108. 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.109. 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.110. 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.111. 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.112. 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.113. 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.114. 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.115. 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.116. 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.117. 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.118. 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.119. 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.120. 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.121. 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.
Table 3.2. System Function Library
Function Name |
Ret Type |
Exception |
Brief Description |
---|---|---|---|
N/A |
N |
aborts the process | |
Float or Integer |
N |
Returns the absolute value of the argument passed | |
Float |
N |
Returns the arc cosine of the number passed in radians | |
Float |
N |
Returns the arc sine of the number passed in radians. | |
Float |
N |
Returns the arc tangent of the number passed in radians. | |
String |
Y |
Executes a process and returns a string of the output (stdout only) | |
String | N | Returns a string giving the last element of a file path. | |
Binary | N | Returns a binary data type of the data passed. | |
String | Y | Returns a string created from the binary data passed. | |
Int |
N |
Returns the byte position of a substring within a string and takes an optional starting offset | |
Binary |
Y |
Encrypts data using the Cipher Block Chaining function for the blowfish algorithm. | |
Binary |
Y |
Decrypts data using the Cipher Block Chaining function for the blowfish algorithm. | |
String |
Y |
Decrypts data to a string using the Cipher Block Chaining function for the blowfish algorithm. | |
Boolean |
N |
Converts the argument to a boolean value | |
Int |
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 | |
any | 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 | |
any | 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. | |
any | 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). | |
any | 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. | |
any |
Y |
calls a method given by a string of the object passed, passing the remaining arguments to the method as arguments | |
any |
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 | |
Binary |
Y |
Encrypts data using the Cipher Block Chaining function for the CAST5 algorithm. | |
Binary |
Y |
Decrypts data using the Cipher Block Chaining function for the CAST5 algorithm. | |
String |
Y |
Decrypts data to a string using the Cipher Block Chaining function for the CAST5 algorithm. | |
Float |
N |
Returns the cube root of the number passed. | |
Float | N | Returns a value rounded up to the next highest integer | |
Integer | Y | Changes the current working directory. | |
Integer | Y | Changes the mode of a file. | |
String | 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. | |
String | N | Changes the user and group owners of a file (if the current user has permission to do so), follows symbolic links. | |
String | N | Returns a string containing a single ASCII character represented by the numeric value passed. | |
Integer |
N |
Returns the system time in microseconds (1/1000000 second intervals since Jan 1, 1970 00:00). | |
Integer |
N |
Returns the system time in milliseconds (1/1000 second intervals since Jan 1, 1970 00:00). | |
Integer |
N |
Returns the system time in nanoseconds (1/1000000000 second intervals since Jan 1, 1970 00:00). | |
Binary | Y | Performs zlib-based "deflate" data compression (RFC 1951) and returns a binary object of the compressed data. | |
String | Y | Performs explicit string character encoding conversions. | |
Float |
N |
Returns the cosine of the number in radians passed. | |
Float |
N |
Returns the hyperbolic cosine of the number passed. | |
Date | N | Converts the argument passed to a date. | |
Date | N | Converts an integer argument as a millisecond offset from January 1, 1970 to a date. | |
Date |
N |
Returns a relative date in days for date arithmetic. | |
String | N | Decodes percent numeric codes in a URL string and returns the decoded string. | |
n/a |
N |
Deletes all keys in the thread-local data hash. | |
n/a | N | Deletes the data associated to one or more keys in the thread-local data hash (destroys any objects as well). | |
Binary |
Y |
Encrypts data using the Cipher Block Chaining function for the DES algorithm. | |
Binary |
Y |
Decrypts data using the Cipher Block Chaining function for the DES algorithm. | |
String |
Y |
Decrypts data using the Cipher Block Chaining function for the DES algorithm. | |
Binary |
Y |
Encrypts data using the Cipher Block Chaining function for the two-key triple DES algorithm. | |
Binary |
Y |
Decrypts data using the Cipher Block Chaining function for the two-key triple DES algorithm. | |
String |
Y |
Decrypts data to a string using the Cipher Block Chaining function for the two-key triple DES algorithm. | |
Binary |
Y |
Encrypts data using the Cipher Block Chaining function for the three-key triple DES algorithm. | |
Binary |
Y |
Decrypts data using the Cipher Block Chaining function for the three-key triple DES algorithm. | |
String |
Y |
Decrypts data to a string using the Cipher Block Chaining function for the three-key triple DES algorithm. | |
Binary |
Y |
Encrypts data using the Cipher Block Chaining function for RSA's DESX algorithm. | |
Binary |
Y |
Encrypts data using the Cipher Block Chaining function for RSA's DESX algorithm. | |
String |
Y |
Encrypts data to a string using the Cipher Block Chaining function for RSA's DESX algorithm. | |
String | 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) | |
Binary | 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) | |
String | 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) | |
Binary | 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) | |
Integer | N | Returns the value of the system "errno" variable, holding the last error code generated by a system call | |
n/a | N | Replaces the current process image with another. | |
Boolean |
N |
Returns True if the function exists in the current program's function name space. | |
N/A |
N |
Exits the program | |
Float |
N |
Returns the value of e raised to the power of the argument passed | |
Float |
N |
Returns the value of 2 raised to the power of the argument passed | |
Float |
N |
Returns an equivalent of exp(x) - 1 | |
String |
Y |
"field" printf, field width specifiers are respected. Returns string printed. | |
String |
Y |
"field" sprintf(), field width specifiers are respected | |
Float |
N |
Returns the argument converted to a floating-point number | |
Float | N |
Returns a value rounded down to the nearest integer | |
n/a | N | Flushes output to the console output with print(), printf(), etc | |
String | 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. | |
Integer | N |
Creates a duplicate of the current process | |
String | N |
Allows dates to be formatted | |
String | N |
Allows numbers to be formatted with more options than sprintf() | |
String |
N |
Returns "builtin", "user", or NOTHING according to the function name passed | |
Hash |
N |
Returns the entire thread data hash. | |
Integer |
N |
Returns an integer value representing the days value of the date passed (can be either a relative or absolute date). | |
String |
N |
Returns the name of the default character encoding for the Qore library. | |
String |
N |
Returns a string describing the character encoding of the string passed. | |
Integer |
N |
Returns an integer value representing the hours value of the date passed (can be either a relative or absolute date). | |
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) | |
Integer |
N |
Returns an integer value representing the milliseconds value of the date passed (can be either a relative or absolute date). | |
Integer |
N |
Returns an integer value representing the minutes value of the date passed (can be either a relative or absolute date). | |
Integer |
N |
Returns an integer value representing the months value of the date passed (can be either a relative or absolute date). | |
Hash | N | Returns a hash of build and version information for the qore library. | |
List | N | Returns a list of hashes giving information about qore library options. | |
Integer | N | Returns an integer value representing the seconds value of the date passed (can be either a relative or absolute date). | |
String | N | Returns a string giving the path (directory and filename) from which the current script was executed (if known). | |
String | N | Returns a string giving the directory from which the current script was executed (if known). | |
String | N | Returns a string giving the filename of the current script (if known). | |
Any |
N |
Returns the value of the thread-local data attached to the key passed | |
Integer |
N |
Returns an integer value representing the years value of the date passed (can be either a relative or absolute date). | |
Hash |
N | Returns a hash of call stacks keyed by each TID (thread ID). | |
Integer | N | Returns the byte value withing the string or binary object passed. | |
String | N | Returns the class name of the object passed. | |
String | N | Returns the name of the current working directory. | |
Date |
N |
Retuns an absolute date value for the ISO-8601 calendar week information passed (year, week number, optional: day) | |
Integer |
N |
Returns an integer representing the day of the week for the absolute date passed (0=Sunday, 6=Saturday) | |
Integer |
N |
Returns an integer representing the ordinal day number in the year for the absolute date passed | |
Integer | N | Returns an integer representing the capabilities of a DBI driver. | |
List | N | Returns a list of codes representing the capabilities of a DBI driver. | |
List | N | Returns a list of strings of DBI drivers currently available. | |
Int |
N |
Returns the effective group ID of the current process. | |
Int |
N |
Returns the effective user ID of the current process. | |
List |
N |
Returns a list of strings of the builtin and module-supplied features of Qore. | |
String |
N |
Retrieves the value of an environment variable | |
Int |
N |
Returns the real group ID of the current process. | |
String | N | Returns the official hostname corresponding to the network addressed passed | |
Hash | N | Returns all host information corresponding to the network address | |
String | N | Returns the first network address corresponding to the hostname | |
Hash | N | Returns all host information corresponding to the hostname | |
String | N | Returns the hostname of the system | |
Integer |
N |
Returns an integer representing the ISO-8601 day of the week for the absolute date passed (1=Monday, 7=Sunday) | |
Hash |
N |
Returns a hash representing the ISO-8601 calendar week information for the absolute date passed (hash keys: year, week, day) | |
String |
N |
Returns a string representing the ISO-8601 calendar week information for the absolute date passed (ex: 2006-01-01 = "2005-W52-7") | |
List |
N |
Returns a list of strings of the names of the methods of the class of the object passed as a parameter. | |
List |
N |
Returns a list of hashes describing the currently-loaded Qore modules. | |
Int |
N |
Returns the PID (process ID) of the current process. | |
Int | N | Returns the parent PID of the current process. | |
Hash |
N |
Returns a hash representing the user information of the user ID passed. | |
Int |
N |
Returns the Qore thread ID (TID) of the current thread. | |
Int |
N |
Returns the real user ID of the current process. | |
List |
N |
Returns a list of files matching the string argument | |
Date | N |
Returns a date/time value in GMT | |
Binary | N | Uncompresses data compressed with the "gzip" algorithm (RFC 1952) using zlib functions and returns a binary object. | |
String | N | Uncompresses data compressed with the "gzip" algorithm (RFC 1952) using zlib functions and returns a string. | |
Binary | Y | Performs zlib-based "gzip" data compression (RFC 1952) and returns a binary object of the compressed data. | |
Hash |
N |
Converts an object or a list to a hash; otherwise returns an empty hash. | |
List |
N |
Returns a list of all the values in the hash argument passed. | |
Integer | N | Returns an integer for a hexadecimal string value. | |
Hash | N | Returns a hash of information about the file corresponding to the pathname argument; does not follow symbolic links (returns information about symbolic links). | |
Date |
N |
Returns a relative date in hours to be used in date arithmetic. | |
Hash | N | Returns a hash of information about the file corresponding to the pathname argument; follows symbolic links. | |
String |
Y |
Returns a string with any HTML escape codes translated to the original characters | |
String |
Y |
Returns a string with any characters that can be escaped translated to HTML escape codes. | |
Float |
N |
Returns the length of the hypotenuse of a right-angle triangle with sides given as the two arguments. | |
Int | N | Returns the character position of a substring within a string and takes an optional starting offset | |
Boolean | N | Returns True if the first argument is a member of the second argument list using comparisons with type conversions. | |
Boolean | N | Returns True if the first argument is a member of the second argument list using comparisons without type conversions. | |
Int |
N |
Returns the argument converted to an integer | |
Boolean |
N |
Returns True if the string passed identifies a block device file on the filesystem. | |
Boolean |
N |
Returns True if the string passed identifies a character device file on the filesystem. | |
Boolean |
N |
Returns True if the string passed identifies a device file (either block or character) on the filesystem. | |
Boolean |
N |
Returns True if the string passed identifies a directory on the filesystem. | |
Boolean |
N |
Returns True if the string passed identifies an executable file. | |
Boolean |
N |
Returns True if the string passed identifies a regular file on the filesystem. | |
Boolean |
N |
Returns True if the string passed identifies a symbolic link on the filesystem. | |
Boolean |
N |
Returns True if the string passed identifies a pipe (FIFO) on the filesystem. | |
Boolean |
N |
Returns True if the string passed identifies a file readable by the current user. | |
Boolean |
N |
Returns True if the string passed identifies a socket on the filesystem. | |
Boolean |
N |
Returns True if the string passed identifies a file writable by the current user. | |
String |
N |
Creates a string from a list and separator character | |
Int |
N |
Sends a signal to a process (default: SIGHUP) | |
String | N | Changes the user and group owners of a file (if the current user has permission to do so), does not follow symbolic links. | |
Int |
N |
Returns the length in characters for the string passed. | |
List |
N |
Returns a list with the argument passed as the first element (or an empty list if no argument is passed) | |
n/a | Y | Loads a Qore module at run-time if the feature name is not already present in the current Program object. | |
Date |
N |
Returns a date value in localtime based on the value of the argument passed, which must be the number of seconds after Jan 1, 1970, 00:00:00 | |
Float |
N |
Returns the base 10 logarithm of the value passed | |
Float |
N |
Returns the natural logarithm of the value passed plus 1 | |
Float |
N |
Returns the exponent of a number. | |
List |
N |
Returns a list of filesystem values for the file or symbolic link passed. | |
String | N | Returns a base64-encoded representation of a binary object or a string. | |
String |
Y |
Creates a JSON-RPC 1.1 error response string from the parameters passed, formatted with line breaks for easier readability. | |
String |
Y |
Creates a generic JSON-RPC error response string from the parameters passed, formatted with line breaks for easier readability. | |
String |
Y |
Creates a JSON-RPC request string from the parameters passed, formatted with line breaks for easier readability. | |
String |
Y |
Creates a JSON-RPC response string from the parameters passed, formatted with line breaks for easier readability. | |
String |
Y |
Serializes qore data into a JSON string, formatted with line breaks for easier readability. | |
String |
Y |
Serializes a hash into an XML string with formatting and without an XML header. | |
String | Y | Serializes the arguments into an XML string for an XML-RPC call with formatting. | |
String | 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. | |
String | 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. | |
String | 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. | |
String | Y | Serializes the arguments into an XML string formatted for an XML-RPC fault response with whitespace formatting. | |
String | 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. | |
String | Y | Serializes the arguments into an XML string formatted for an XML-RPC response with whitespace formatting. | |
String | 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. | |
String |
Y |
Serializes the arguments into an XML string in XML-RPC Value format with whitespace formatting. | |
String |
Y |
Serializes a hash into an XML string with formatting and an XML header. | |
String | N | Returns a hex-encoded representation of a binary object or a string. | |
String |
Y |
Creates a JSON-RPC 1.1 error response string from the parameters passed, without any line breaks. | |
String |
Y |
Creates a generic JSON-RPC error response string from the parameters passed, without any line breaks. | |
String |
Y |
Creates a JSON-RPC request string from the parameters passed, without any line breaks. | |
String |
Y |
Creates a JSON-RPC response string from the parameters passed, without any line breaks. | |
String |
Y |
Serializes qore data into a JSON string, without any line breaks. | |
String |
Y |
Serializes a hash into an XML string without an XML header or formatting. | |
String | Y | Serializes the arguments into an XML string formatted for an XML-RPC call without formatting. | |
String | 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. | |
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. | |
String | 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. | |
String | Y | Serializes the arguments into an XML string formatted for an XML-RPC fault response without formatting. | |
String | 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. | |
String | Y | Serializes the arguments into an XML string formatted for an XML-RPC response without formatting. | |
String | 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. | |
String |
Y |
Serializes the arguments into an XML string in XML-RPC Value format without formatting. | |
String | Y | Serializes a hash into a complete XML string with an XML header and without formatting. | |
Any | 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. | |
String |
Y |
Returns the MD2 message digest of the supplied argument as a hex string (for strings, the trailing null character is not included in the digest) | |
Binary |
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) | |
String |
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) | |
Binary |
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) | |
String |
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) | |
Binary |
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) | |
String |
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) | |
Binary |
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) | |
Date | N | Returns a relative date in milliseconds to be used in date arithmetic. | |
Any | 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. | |
Date |
N |
Returns a relative date in minutes to be used in date arithmetic. | |
Int |
Y |
Creates a directory. | |
Int |
N |
Creates a named pipe | |
Int | N |
Returns the number of seconds after Jan 1, 1970, 00:00:00, assuming that the date passed is in local time | |
Date | N | Returns a relative date in months to be used in date arithmetic. | |
Float | N | Returns the natural logarithm of the value passed | |
Date | N | Returns current date and time with resolution to the second | |
Date | N | Returns current date and time with resolution to the millisecond | |
Int |
N |
Returns the current number of threads in the process | |
Int |
N |
Gives the numeric value of the character passed | |
n/a |
Y |
Adds the text passed to the current program's code | |
Binary | Y | Parses a base64 encoded string and returns the binary object | |
Hash | N | Returns a hash of the components of a datasource string. | |
Binary | Y | Parses a hex-encoded string and returns the binary object | |
Qore Data |
N |
Parses a JSON string and returns the corresponding qore data structure. | |
Hash |
Y | Parses a URL string and returns a hash of the components. | |
Hash | Y | parses an XML string and returns a Qore hash structure. | |
Hash | Y | parses an XML string, validates the generated XML against a RelaxNG schema string, and returns a Qore hash structure. | |
Hash | Y | parses an XML string, validates the generated XML against an XSD schema string, and returns a Qore hash structure. | |
Hash | 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. | |
Hash | 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. | |
Hash | 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. | |
Hash |
Y | deserializies an XML-RPC call string, returning a Qore data structure representing the call information. | |
Hash |
Y | deserializies an XML-RPC response string, returning a Qore data structure representing the response information. | |
Hash |
Y | deserializies an XML-RPC value tree, returning a Qore data structure representing the information. | |
Float |
Y |
Returns the value of the first argument raised to the power of the second | |
- |
Y |
Prints the string passed without any formatting. | |
String |
Y |
Prints a formatted string and returns string printed. | |
Float | N | Returns a random integer number. | |
Binary |
Y |
Encrypts data using the Cipher Block Chaining function for RSA's RC2(tm) algorithm. | |
Binary |
Y |
Decrypts data using the Cipher Block Chaining function for RSA's RC2(tm) algorithm. | |
String |
Y |
Decrypts data to a string using the Cipher Block Chaining function for RSA's RC2(tm) algorithm. | |
Binary |
Y |
Encrypts data using the Alleged RC4 cipher algorithm, which should be compatible with RSA's RC4(tm) algorithm. | |
Binary |
Y |
Decrypts data using the Alleged RC4 cipher algorithm, which should be compatible with RSA's RC4(tm) algorithm. | |
String |
Y |
Decrypts data to a string using the Alleged RC4 cipher algorithm, which should be compatible with RSA's RC4(tm) algorithm. | |
Binary |
Y |
Encrypts data using the Cipher Block Chaining function for RSA's RC5(tm) algorithm. | |
Binary |
Y |
Decrypts data using the Cipher Block Chaining function for RSA's RC5(tm) algorithm. | |
String |
Y |
Decrypts data to a string using the Cipher Block Chaining function for RSA's RC5(tm) algorithm. | |
Boolean | Y | Returns true if the regular expression matches the string passed | |
String | Y | Returns a list of substrings in a string based on matching patterns defined by a regular expression. | |
String | Y | Returns a string with patterns substituted according to the arguments passed. | |
n/a | N | Removes an installed signal handler and returns the signal handling state to the default. | |
n/a | N | Removes the listed keys from the thread-local data hash. | |
n/a | Y | Renames (or moves) a file or directory. | |
String |
N |
Replaces all occurrances of a substring in a string with another string and returns the new string. | |
String or List | N | Reverses the order of a string or a list and returns the new string or list. | |
String |
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) | |
Binary |
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) | |
Int |
N |
Returns the starting character position of a string in another string as searched from the end of the string. | |
Int |
Y |
Removes a directory. | |
Float | N | Returns a value rounded up to the nearest integer integer. | |
- |
Y |
Saves the data passed against the key passed in thread-local storage. | |
Date | N | Returns a relative date/time value in seconds to be used in date arithmetic. | |
n/a | N | Installs or replaces a signal handler. | |
Integer |
Y |
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()) | |
Integer |
Y |
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()) | |
String |
N |
Sets the value of an environment variable | |
Integer |
Y |
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()) | |
Integer |
Y |
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()) | |
String |
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) | |
Binary |
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) | |
String | 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) | |
Binary | 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) | |
String | 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) | |
Binary | 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) | |
String | 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) | |
Binary | 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) | |
String | 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) | |
Binary | 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) | |
String | 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) | |
Binary | 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) | |
Int |
N |
Causes the current thread to sleep for a certain number of seconds. | |
List | 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. | |
List | 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. | |
List | 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. | |
List | 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. | |
List |
N |
Splits a string into a list of components based on a separator string | |
String |
Y |
Creates a string from the format argument passed and the other arguments. | |
Float |
N |
Returns the sine of the number in radians passed. | |
Float |
N |
Returns the hyperbolic sine of the number passed. | |
Float |
N |
Returns the square root of the number passed. | |
n/a |
N |
Seeds the random number generator with the integer passed. | |
List |
N |
Returns a list of filesystem information for the filename passed. | |
String |
N |
Returns the description of the error number passed | |
String |
N |
Returns the argument converted to a string | |
Int |
N |
Returns the number of characters in a string | |
Integer | N | Returns an integer corresponding to the string passed with the possibility to specify the base (default base 10). | |
String |
N |
Returns a substring of a string | |
Int |
Y |
Executes a process and returns the return code | |
Float |
N |
Returns the tangent of the number in radians passed. | |
Float |
N |
Returns the hyperbolic tangent of the number passed. | |
List | N | Returns a list of all current thread IDs | |
n/a | Y | Immediately runs all thread resource cleanup routines for the current thread and throws all associated exceptions. | |
Date |
N |
Returns the number of seconds since January 1, 1970 00:00 for a given date in GMT. | |
String |
N |
Converts a string to all lowercase | |
String |
N |
Converts a string to all uppercase | |
String | 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 variable references to do modifications in-place. | |
Int |
N |
Returns the data type of the argument passed (see Type_Constants) | |
String |
N |
deprecated: use type() instead | |
Int |
N |
Sets the file creation mask for the process | |
Binary | N | Uncompresses (inflates) data compressed with the "deflate" algorithm (RFC 1951) using zlib functions and returns a binary object. | |
String | N | Uncompresses (inflates) data compressed with the "deflate" algorithm (RFC 1951) using zlib functions and returns a string. | |
Int |
N |
Deletes a file and returns 0 for success. | |
n/a | N | Unsets an environment variable | |
Int | N | Causes the current thread to sleep for a certain number of microseconds | |
String |
Y |
Outputs a formatted string based on a variable number of arguments given in a list after the format string. Returns the string printed. | |
String |
Y |
Formats a string based on a variable number of arguments given in a list after the format string and returns this formatted string. | |
Date |
N |
Returns a relative date/time value in years to be used in date arithmetic. |
Returns the absolute value of the argument passed.
abs(numeric_expression
)
$x = abs($y);
Table 3.3. Arguments and Return Values for abs()
Argument Type | Return Type | Description |
---|---|---|
Integer | Integer | Absolute value of the integer passed. |
Float | Float | Absolute value of the floating-point value passed. |
This function does not throw any exceptions.
Returns the arc cosine of the number passed in radians
acos(float
)
$x = acos($y);
Table 3.4. Arguments and Return Values for acos()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns the arc cosine of the number passed in radians. |
This function does not throw any exceptions.
Returns the arc sine of the number passed in radians
asin(float
)
$x = asin($y);
Table 3.5. Arguments and Return Values for asin()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns the arc sine of the number passed in radians. |
This function does not throw any exceptions.
Returns the arc tangent of the number passed in radians
atan(float
)
$x = atan($y);
Table 3.6. Arguments and Return Values for atan()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns the arc tangent of the number passed in radians. |
This function does not throw any exceptions.
Returns the cube root of the number passed.
cbrt(float
)
$x = cbrt($y);
Table 3.7. Arguments and Return Values for cbrt()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns the cube root of the number passed. |
This function does not throw any exceptions.
Returns a floating-point number equal to the smallest integral value greater than or equal to the argument passed.
ceil(float
)
$x = ceil(3.2); # will return 4.0
Table 3.8. Arguments and Return Values for ceil()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns a value rounded up to the nearest integral floating-point value. |
This function does not throw any exceptions.
Returns the cosine of the number in radians passed.
cos(float
)
$x = cos($y);
Table 3.9. Arguments and Return Values for cos()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns the cosine of the number in radians passed. |
This function does not throw any exceptions.
Returns the hyperbolic cosine of the number in radians passed.
cosh(float
)
$x = cosh($y);
Table 3.10. Arguments and Return Values for cosh()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns the hyperbolic cosine of the number in radians passed. |
This function does not throw any exceptions.
Returns the value of e raised to the power of the argument passed.
exp(float
)
$x = exp($y);
Table 3.11. Arguments and Return Values for exp()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns the value of e raised to the power of the argument passed. |
This function does not throw any exceptions.
Returns the value of 2 raised to the power of the argument passed.
exp2(float
)
$x = exp2($y);
Table 3.12. Arguments and Return Values for exp2()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns the value of 2 raised to the power of the argument passed. |
This function does not throw any exceptions.
Returns an equivalent of exp(x) - 1.
expm1(float
)
$x = expm1($y);
Table 3.13. Arguments and Return Values for expm1()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns an equivalent of exp(x) - 1. |
This function does not throw any exceptions.
Returns a floating-point value rounded down to the integral value.
floor(float
)
$x = floor(3.7); # will return 3.0
Table 3.14. Arguments and Return Values for floor()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns a float-point value rounded down to the integral value. |
This function does not throw any exceptions.
Returns a string of a formatted number according to the arguments passed.
format_number(format_string, number
)
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"
Table 3.15. Arguments and Return Values for format_number()
Argument Types | Return Type | Description |
---|---|---|
String, Float | String | Returns a string corresponding to a number according to the formatting string passed. |
This function does not throw any exceptions.
Returns the length of the hypotenuse of a right-angle triangle with sides given as the two arguments.
hypot(float_x, float_y
)
$z = hypot($x, $y);
Table 3.16. Arguments and Return Values for hypot()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns the length of the hypotenuse of a right-angle triangle with sides given as the two arguments. |
This function does not throw any exceptions.
Returns the base 10 logarithm of the value passed.
log10(float
)
$x = log10($y);
Table 3.17. Arguments and Return Values for log10()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns the base 10 logarithm of the value passed. |
This function does not throw any exceptions.
Returns the natural logarithm of the value passed plus 1.
log1p(float
)
$x = log1p($y);
Table 3.18. Arguments and Return Values for log1p()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns the natural logarithm of the value passed plus 1. |
This function does not throw any exceptions.
Returns the exponent of a number.
logb(float
)
$x = logb($y);
Table 3.19. Arguments and Return Values for logb()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns the exponent of a number. |
This function does not throw any exceptions.
Returns the natural logarithm of the value passed.
nlog(float
)
$x = nlog();
Table 3.20. Arguments and Return Values for nlog()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns the natural logarithm of the value passed. |
This function does not throw any exceptions.
Returns a number raised to the power of another number.
pow(x, y
)
$z = pow($x, $y);
Table 3.21. Arguments and Return Values for pow()
Argument Types | Return Type | Description |
---|---|---|
Float | Float | Returns x raised to the power of y. |
Table 3.22. 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.
round(float
)
$x = round(3.2); # returns 3.0
Table 3.23. Arguments and Return Values for round()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns a value rounded to the nearest integral floating-point value, half-way cases are rounded away from zero. |
Table 3.24. Exceptions Thrown by round()
err | desc |
---|---|
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Returns the sine of the number in radians passed.
sin(float
)
$x = sin($y);
Table 3.25. Arguments and Return Values for sin()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns the sine of the number in radians passed. |
This function does not throw any exceptions.
Returns the hyperbolic sine of the number in radians passed.
sinh(float
)
$x = sinh($y);
Table 3.26. Arguments and Return Values for sinh()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns the hyperbolic sine of the number in radians passed. |
This function does not throw any exceptions.
Returns the square root of the number passed.
sqrt(float
)
$x = sqrt($y);
Table 3.27. Arguments and Return Values for sqrt()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns the square root of the number passed. |
This function does not throw any exceptions.
Returns the tangent of the number in radians passed.
tan(float
)
$x = tan($y);
Table 3.28. Arguments and Return Values for tan()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns the tangent of the number in radians passed. |
This function does not throw any exceptions.
Returns the hyperbolic tangent of the number in radians passed.
tanh(float
)
$x = tanh($y);
Table 3.29. Arguments and Return Values for tanh()
Argument Type | Return Type | Description |
---|---|---|
Float | Float | Returns the hyperbolic tangent of the number in radians passed. |
This function does not throw any exceptions.
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(format_string, arguments...
)
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.30. Arguments and Return Values for f_printf()
Arguments | Return Type | Description |
---|---|---|
String, [...] | String | 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.
f_sprintf(format_string, arguments...
)
$str = f_sprintf("%5s", "a long string"); # will return "a lon"
Table 3.31. Arguments and Return Values for f_sprintf()
Argument Type | Return Type | Description |
---|---|---|
String, [args...] | String | 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()
flush();
Not available with PO_NO_TERMINAL_IO
Table 3.32. 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(string
)
print("hello\n"); # do not use formatting with this function
Not available with PO_NO_TERMINAL_IO
Table 3.33. Arguments and Return Values for print()
Argument Type |
Return Type |
Description |
---|---|---|
String |
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(format_string, arguments...
)
printf("%5s\n", "a long string"); # will output "a long string", exceeding the field width
Not available with PO_NO_TERMINAL_IO
Table 3.34. Arguments and Return Values for printf()
Arguments | Return Type | Description |
---|---|---|
String, [...] | String |
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.
sprintf(format_string, arguments...
)
$str = sprintf("%5s", "a long string"); # returns "a long string", exceeding the field width
Table 3.35. Arguments and Return Values for sprintf()
Argument Type | Return Type | Description |
---|---|---|
String, [args...] | String | 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(format_string, arg_list
)
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.36. Arguments and Return Values for vprintf()
Argument Type |
Return Type |
Description |
---|---|---|
String, [List] | String |
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.
vsprintf(format_string, arg_list
)
$str = vsprintf("%5s %3d\n", ("a long string", 5000)); # returns "a long string 5000", exceeding field width of 5
Table 3.37. Arguments and Return Values for vsprintf()
Argument Type |
Return Type |
Description |
---|---|---|
String, [List] |
String |
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). Please note that many operating system/hardware combinbations are not capable of reporting time at this resolution; the last 3 or more digits may be zero in this case.
clock_getmicros()
$time = clock_getmicros();
Table 3.38. Arguments and Return Values for clock_getmicros()
Argument Type |
Return Type |
Description |
---|---|---|
n/a |
Integer |
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()
$time = clock_getmillis();
Table 3.39. Arguments and Return Values for clock_getmillis()
Argument Type |
Return Type |
Description |
---|---|---|
n/a |
Integer |
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).
clock_getnanos()
$time = clock_getnanos();
Table 3.40. Arguments and Return Values for clock_getnanos()
Argument Type |
Return Type |
Description |
---|---|---|
n/a |
Integer |
Returns the number of nanoseconds (1/1000000000 second) since Jan 1, 1970 00:00. |
This function does not throw any exceptions.
Converts an integer argument representing the offset in milliseconds from January 1, 1970 to a date.
date_ms(integer
)
$date = date_ms(1); # return 1970-01-01T00:00:00.001
Table 3.41. Arguments and Return Values for date_ms()
Argument Type | Return Type | Description |
---|---|---|
Integer | Date | Returns the date corresponding to the offset in ms given from January 1, 1970. |
This function does not throw any exceptions.
Returns a relative date/time value in days for date arithmetic.
days(expression
)
$days = days(5 * 5); # returns 25D
Table 3.42. Arguments and Return Values for days()
Argument Type |
Return Type |
Description |
---|---|---|
Integer |
Date |
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(format_string, date_value
)
$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.43. Arguments and Return Values for format_date()
Argument Type | Return Type | Description |
---|---|---|
String, Date | String | Formats the date value using the string as a formatting specification. |
This function does not throw any exceptions.
Table 3.44. Date Format Arguments
String | 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) |
| non zero-padded millisecond number (0 - 999) |
| zero-padded millisecond number (000 - 999) |
| AM or PM (upper-case) |
| am or pm (lower-case) |
All other text is output directly in the output text unchanged.
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
)
$date = get_midnight(2007-01-23T11:24:03.250); # returns 2007-01-23T00:00:00.000
Table 3.52. Arguments and Return Values for get_midnight()
Argument Type |
Return Type |
Description |
---|---|---|
Date |
Date |
Returns a date/time value representing midnight on the date passed (strips the time from the date passed and returns the new value) |
Retuns an absolute date value for the ISO-8601 calendar week information passed (year, week number, optional: weekday, where 1=Monday, 7=Sunday). If the weekday is omitted, Monday (1) is assumed.
getDateFromISOWeek(integer, integer, optional:integer
)
$date = getDateFromISOWeek(2007, 3); # returns 2007-01-15T00:00:00.000
Table 3.53. Arguments and Return Values for getDateFromISOWeek()
Argument Type |
Return Type |
Description |
---|---|---|
Integer, Integer, Optional:integer |
Date |
Retuns an absolute date value for the ISO-8601 calendar week information passed (year, week number, optional: day) |
Returns an integer representing the day of the week for the absolute date passed (0=Sunday, 6=Saturday)
getDayOfWeek(date
)
$dow = getDayOfWeek(2007-05-15); # returns 2
Table 3.54. Arguments and Return Values for getDayOfWeek()
Argument Type |
Return Type |
Description |
---|---|---|
Date |
Integer |
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
)
$dn = getDayNumber(2007-05-15); # returns 135
Table 3.55. Arguments and Return Values for getDayNumber()
Argument Type |
Return Type |
Description |
---|---|---|
Date |
Integer |
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
)
$dow = getISODayOfWeek(2007-05-15); # returns 2 for Tuesday
Table 3.56. Arguments and Return Values for getISODayOfWeek()
Argument Type |
Return Type |
Description |
---|---|---|
Date |
Integer |
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
)
$h = getISOWeekHash(2007-05-15); # returns year=2007, week=20, day=2
Table 3.57. Arguments and Return Values for getISOWeekHash()
Argument Type |
Return Type |
Description |
---|---|---|
Date |
Hash |
Returns a hash representing the ISO-8601 calendar week information for the absolute date passed (hash keys: year, week, day) |
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
)
$str = getISOWeekString(2007-05-15); # returns "2007-W20-2"
Table 3.58. Arguments and Return Values for getISOWeekString()
Argument Type |
Return Type |
Description |
---|---|---|
Date |
String |
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 GMT time is returned. Otherwise the single argument must be an integer giving the number of seconds since Jan 1, 1970, 00:00:00.
gmtime([int_value]
)
$date = gmtime(mktime(now())); # returns current GMT
$date = gmtime(); # also returns current GMT
Table 3.59. Arguments and Return Values for gmtime()
Argument Type |
Return Type |
Description |
---|---|---|
Integer |
Date |
The optional integer argument must be the number of seconds passed since Jan 1, 1970, 00:00:00 (see mktime() for a function that returns such a value). Qore uses the C library function gmtime() to calculate the return value, which is returned as a Qore Date type. If no argument is passed, then the current date and time in GMT are returned. If an argument is passed that is not a date/time value, then NOTHING is returned. |
This function does not throw any exceptions.
Returns a relative date/time value in hours to be used in date arithmetic.
hours(expression
)
$h = hours(5 * 5); # returns 25h
Table 3.60. Arguments and Return Values for hours()
Argument Type |
Return Type |
Description |
---|---|---|
Integer |
Date |
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 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. If no argument is passed, then the current local date and time are returned.
localtime([int_value]
)
$time = localtime(10);
Table 3.61. Arguments and Return Values for localtime()
Argument Type |
Return Type |
Description |
---|---|---|
Integer |
Date |
The optional integer argument must be the number of seconds passed since Jan 1, 1970, 00:00:00 (see mktime() for a function that returns such a value). Qore uses the C library function localtime() to calculate the return value, which is returned as a Qore Date type. If no argument is passed, then the current date and time in the current time zone are returned. If an argument is passed that is not a date/time value, then NOTHING is returned. |
This function does not throw any exceptions.
Returns a relative date/time value in milliseconds to be used in date arithmetic.
millseconds(expression
)
$ms = millseconds(5 * 5); # returns 25ms
Table 3.62. Arguments and Return Values for milliseconds()
Argument Type |
Return Type |
Description |
---|---|---|
Integer |
Date |
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.
Returns a relative date/time value in minutes to be used in date arithmetic.
minutes(expression
)
$m = minutes(5 * 5); # returns 25m
Table 3.63. Arguments and Return Values for minutes()
Argument Type |
Return Type |
Description |
---|---|---|
Integer |
Date |
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.
Returns the number of seconds of the date and time in local time passed since Jan 1, 1970, 00:00:00 GMT.
mktime(date_value
)
$secs = mktime(2007-09-23T00:00:01);
Synopsis
Usage
Table 3.64. Arguments and Return Values for mktime()
Argument Type |
Return Type |
Description |
---|---|---|
Date |
Integer |
The date argument should be in local time; the function returns the number of seconds passed since Jan 1, 1970 00:00:00 corresponding to this date. Qore uses the C library function mktime() to return the value. |
This function does not throw any exceptions.
Returns a relative date/time value in months to be used in date arithmetic.
months(expression
)
$m = months(5 * 5); # returns 25M
Table 3.65. Arguments and Return Values for months()
Argument Type |
Return Type |
Description |
---|---|---|
Integer |
Date |
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 with resolution to the second. For a similar function returning the current date and time with millisecond resolution, see now_ms().
now()
$now = now();
Table 3.66. Arguments and Return Values for now()
Argument Type |
Return Type |
Description |
---|---|---|
n/a |
Date |
Returns the current date and time with resolution to the second. |
This function does not throw any exceptions.
Returns the current date and time with resolution to the millisecond. For a similar function returning the current date and time with courser granularity, when resolution only to the second is needed, see now().
now_ms()
$now_ms = now_ms();
Table 3.67. Arguments and Return Values for now_ms()
Argument Type |
Return Type |
Description |
---|---|---|
n/a |
Date |
Returns the current date and time with resolution to the millisecond. |
This function does not throw any exceptions.
Returns a relative date/time value in seconds to be used in date arithmetic.
seconds(expression
)
$time = now() + seconds(5 * 5); # 25 seconds from now
Table 3.68. Arguments and Return Values for seconds()
Argument Type |
Return Type |
Description |
---|---|---|
Integer |
Date |
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.
Returns the number of seconds since January 1, 1970 00:00 for a given date in GMT. The availabilty of this function depends on the system's underlying C-library; the Qore function is only available if the constant HAVE_TIMEGM
is True. See Library Option Constants for a list of all option constants.
timegm(date
)
$secs = timegm(2007-05-01T11:34:01);
Table 3.69. Arguments and Return Values for timegm()
Argument Type |
Return Type |
Description |
---|---|---|
Date |
Integer |
Returns the number of seconds since January 1, 1970 00:00 for a given date in GMT. |
Table 3.70. Exceptions Thrown by timegm()
err | desc |
---|---|
| This exception is thrown when the function is not available; for maximum portability, check the constant |
Returns a relative date/time value in years to be used in date arithmetic.
years(expression
)
$years = years(5 * 5); # returns 25Y
Table 3.71. Arguments and Return Values for years()
Argument Type |
Return Type |
Description |
---|---|---|
Integer |
Date |
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
)
$bin = binary("hello");
Table 3.72. Arguments and Return Values for binary()
Argument Type |
Return Type |
Description |
---|---|---|
String |
Binary |
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, [encoding]
)
$str = binary_to_string($bin, "utf8");
Table 3.73. Arguments and Return Values for binary_to_string()
Argument Type | Return Type | Description |
---|---|---|
Binary, [String] | String | 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. |
Table 3.74. Exceptions Thrown by binary_to_string()
err | desc |
---|---|
| No binary value was passed as the first argument. |
Converts the argument to a boolean value.
boolean(expression
)
$bool = boolean(1); # returns True
Table 3.75. Arguments and Return Values for boolean()
Argument Type |
Return Type |
Description |
---|---|---|
Any |
Boolean |
Converts the argument to an integer if necessary, where any non-zero value is True, zero is False. |
This function does not throw any exceptions.
Converts the argument to a date and returns the date.
date(expression
)
$date = date(1); # return 1970-01-01T00:00:01
Table 3.76. Arguments and Return Values for date()
Argument Type | Return Type | Description |
---|---|---|
Any | Date | Converts the argument to a date and returns the date. |
This function does not throw any exceptions.
Converts the argument passed to a floating-point value.
float(expression
)
$float = float("1.435"); # returns 1.435
Table 3.77. Arguments and Return Values for float()
Argument Type | Return Type | Description |
---|---|---|
Any | Float | Converts argument passed to a floating-point value. |
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
|object
)
$h = hash($object); # creates a hash of the object's members
Table 3.78. Arguments and Return Values for hash()
Argument Type | Return Type | Description |
---|---|---|
Object | Hash | Returns a hash of the object's members (public members only if called outside the class). |
List | Hash | 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. |
anything other than Object or List | Hash | Returns an empty hash. |
This function does not throw any exceptions.
Converts the argument passed to an integer value if it is not already.
int(expression
)
$int = int("200"); # returns 200
Table 3.79. Arguments and Return Values for int()
Argument Type | Return Type | Description |
---|---|---|
Any | Integer | Converts argument passed to an integer value. |
This function does not throw any exceptions.
Returns a list; if any arguments are passed, they are inserted as the first element in the list returned.
list([expression
])
$l = list(200);
Table 3.80. Arguments and Return Values for list()
Argument Type | Return Type | Description |
---|---|---|
[Any ...] | List | Returns a list. If any arguments are passed, they are inserted as the first element in the list returned. |
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(expression
)
$str = string(200); # returns "200"
Table 3.81. Arguments and Return Values for string()
Argument Type | Return Type | Description |
---|---|---|
Any | String | 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(expression
)
$type = type("hello"); # returns Type::String ("string")
Table 3.82. Arguments and Return Values for type()
Argument Type | Return Type | Description |
---|---|---|
Any | String | 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.
Retrieves the environment variable passed as an argument.
getenv(variable_name
)
$v = getenv("PATH");
Table 3.84. Arguments and Return Values for getenv()
Argument Type | Return Type | Description |
---|---|---|
String | String | The contents of the environment variable, if the environment variable exists, otherwise returns no value. |
This function does not throw any exceptions.
Sets an environment variable to a value.
setenv(key_string, value_string
)
setenv("PATH", "/bin:/usr/bin");
Table 3.85. Arguments and Return Values for setenv()
Argument Type | Return Type | Description |
---|---|---|
String, String | n/a | Sets the environment variable to a string value (the value is converted to a string if necessary). |
This function does not throw any exceptions.
Unsets an environment variable.
unsetenv(key_string
)
unsetenv("PATH");
Table 3.86. Arguments and Return Values for unsetenv()
Argument Type | Return Type | Description |
---|---|---|
String | n/a | Unsets the environment variable given by the string passed. |
This function does not throw any exceptions.
This function is only supported on systems where the C library support for unsetenv() is present.
Retrieves the byte position of a substring within a string.
bindex(string, substring [, start_position]
)
$i = bindex("hello there", "the");
Table 3.87. Arguments and Return Values for bindex()
Argument Type | Return Type | Description |
---|---|---|
String, String, [Integer] | Integer | 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(string, substring, [position]
)
$i = brindex("hello there", "the");
Table 3.88. Arguments and Return Values for brindex()
Argument Type | Return Type | Description |
---|---|---|
String, String, [Integer] | Integer | 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.
chomp(string
)
$line = chomp("hello\n"); # returns "hello"
Table 3.89. Arguments and Return Values for chomp()
Argument Type | Return Type | Description |
---|---|---|
String | String | Returns the new string with any end-of-line character(s) removed; if the first argument is a variable reference, then the string is modified in place and the new string is also returned. |
This function does not throw any exceptions.
Returns a string containing a single ASCII character represented by the numeric value passed.
chr(integer
)
$i = chr(65); # returns "A"
Table 3.90. Arguments and Return Values for chr()
Argument Type | Return Type | Description |
---|---|---|
Integer | String | Returns a string containing a single ASCII character represented by the numeric value passed. |
This function does not throw any exceptions.
Performs explicit string character encoding conversions.
convert_encoding(string, new_encoding
)
$utf8_str = convert_encoding($iso_8859_1_str, "utf-8");
Table 3.91. Arguments and Return Values for convert_encoding()
Argument Type | Return Type | Description |
---|---|---|
String, String | String | Converts the string arguement to the encoding given and returns the new string. |
Table 3.92. 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(url_string
)
$decoded_url = decode_url($encoded_url);
Table 3.93. Arguments and Return Values for decode_url()
Argument Type | Return Type | Description |
---|---|---|
| String | Returns a string with numeric percent codes decoded to characters. |
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, new_encoding
)
$utf8_str = force_encoding($bad_str, "utf-8");
Table 3.94. Arguments and Return Values for convert_encoding()
Argument Type | Return Type | Description |
---|---|---|
String, String | String | Returns a string with identical byte data as the input string, but tagged with the new encoding. |
This function does not throw any exceptions.
Returns a string describing the character encoding of the string passed.
get_encoding(string
)
$enc = get_encoding($string);
Table 3.95. Arguments and Return Values for get_encoding()
Argument Type | Return Type | Description |
---|---|---|
String | String | Returns a string describing the character encoding of the string passed (ex: "UTF-8", "ISO-8850-1", "KOI8-R"). |
This function does not throw any exceptions.
Retrieves the character position of a substring within a string.
index(string, substring [, start_position]
)
$i = index("hello there", "the");
Table 3.96. Arguments and Return Values for index()
Argument Type | Return Type | Description |
---|---|---|
String, String, [Integer] | Integer | 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.
Creates a string from a list and separator string.
join(separator_string, list
)
$str = join(":", ("a", "b", "c")); # returns "a:b:c"
Table 3.97. Arguments and Return Values for join()
Argument Type | Return Type | Description |
---|---|---|
String, List | Srring | Returns a string with each element of the list separated by the separator string. |
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(string
)
$len = length("hello"); # returns 5
Table 3.98. Arguments and Return Values for length()
Argument Type | Return Type | Description |
---|---|---|
String | Integer | Returns the length in characters for the string passed. |
This function does not throw any exceptions.
Gives the numeric value of the first character in the string passed.
ord(string
)
$i = ord("A"); # returns 65
Table 3.99. Arguments and Return Values for ord()
Argument Type | Return Type | Description |
---|---|---|
String | Integer | Gives the numeric value of the first character in the string passed. Only works reliably with character encodings where each character is a single byte. |
This function does not throw any exceptions.
Returns True if the regular expression matches the string passed, otherwise returns False.
regex(string, pattern_string, [options]
)
$bool = regex("hello", "^hel"); # returns True
Table 3.100. Arguments and Return Values for regex()
Argument Type | Return Type | Description |
---|---|---|
String, String | Boolean | Returns True if |
Table 3.101. 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, pattern_string, [options]
)
$list = regex_extract("hello:there", "(\\w+):(\\w+)");
Table 3.102. Arguments and Return Values for regex_extract()
Argument Type | Return Type | Description |
---|---|---|
String, String, [Integer] | String | Returns the result of |
Table 3.103. 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, pattern_string, target_string, [options]
)
$str = regex_subst("hello there", "^there$", "you"); # returns "hello you"
Table 3.104. Arguments and Return Values for regex_subst()
Argument Type | Return Type | Description |
---|---|---|
String, String, String, [Integer] | String | Returns the result of |
Table 3.105. 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.
Replaces all occurrances of a substring in a string with another string.
replace(string, substring, new_substring
)
$str = replace("hello there", "there", "you"); # returns "hello you"
Table 3.106. Arguments and Return Values for replace()
Argument Type | Return Type | Description |
---|---|---|
String, String, String | String | Replaces all occurrances of a substring in a string with another string and returns the new string. |
This function does not throw any exceptions.
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(string, substring, [position]
)
$i = rindex("hello there", "the");
Table 3.107. Arguments and Return Values for rindex()
Argument Type | Return Type | Description |
---|---|---|
String, String, [Integer] | Integer | Returns the starting character position of a string in another, starting from the end of the string, or from |
This function does not throw any exceptions.
Splits a string into a list of components based on a separator string.
split(pattern, string
)
$list = split(":", "some:text:here"); # returns ("some", "text", "here")
Table 3.108. Arguments and Return Values for split()
Argument Type | Return Type | Description |
---|---|---|
String, String | List | Returns a list of each component of a string separated by a separator string, with the separator removed. |
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(string
)
$len = strlen("hello"); # returns 5
Table 3.109. Arguments and Return Values for strlen()
Argument Type | Return Type | Description |
---|---|---|
String | Integer | 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(string, offset, [length]
)
$str = substr("hello there", 6); # returns "there"
Table 3.110. Arguments and Return Values for substr()
Argument Type | Return Type | Description |
---|---|---|
String, Integer, [Integer] | String | Returns the substring according to the arguments. If |
This function does not throw any exceptions.
Converts the argument passed to a string value all in lower case.
tolower(string
)
$str = tolower("HELLO"); # returns "hello"
Table 3.111. Arguments and Return Values for tolower()
Argument Type | Return Type | Description |
---|---|---|
String | String | Converts argument passed to a string value, all in lower case. |
This function does not throw any exceptions.
Converts the argument passed to a string value all in upper case.
toupper(string
)
$str = toupper("hello"); # returns "HELLO"
Table 3.112. Arguments and Return Values for toupper()
Argument Type | Return Type | Description |
---|---|---|
Any | String | Converts argument passed to a string value, all in upper case. |
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 the following whitespace characters are removed: ' ', '\n', '\r', '\t', '\v' (vertical tab, ASCII 11), and '\0' (null character). To trim other character, pass a string as the second argument specifying the characters to be removed.
trim(string, [chars_to_trim]
)
$line = trim(" hello \n"); # returns "hello"
Table 3.113. Arguments and Return Values for trim()
Argument Type | Return Type | Description |
---|---|---|
String, [String] | String | Returns the new string with characters removed from the beginning and end of the string; if the first argument is a variable reference, then the string is modified in place and the new string is also returned. |
This function does not throw any exceptions.
Aborts the current program (this function does not return).
abort()
abort();
Not available with PO_NO_PROCESS_CONTROL
This function does not throw any exceptions.
Returns a string giving the last element of a file path.
basename(string
)
$str = basename("/usr/local/bin/file_name"); # returns "file_name"
Table 3.114. Arguments and Return Values for basename()
Argument Type | Return Type | Description |
---|---|---|
String | String | Returns the last element in a file path (meant to be the filename). |
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.
errno()
$str = strerror(errno());
Table 3.115. Arguments and Return Values for errno()
Argument Type | Return Type | Description |
---|---|---|
n/a | Integer | 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(exec_string
)
exec("/bin/ls -l");
Not available with PO_NO_PROCESS_CONTROL
or PO_NO_EXTERNAL_PROCESS
Table 3.116. Arguments and Return Values for exec()
Argument Type | Return Type | Description |
---|---|---|
String | 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(return_code
)
exit(2);
Not available with PO_NO_PROCESS_CONTROL
Table 3.117. Arguments and Return Values for exit()
Argument Type | Return Type | Description |
---|---|---|
Integer | 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.
fork()
$pid = fork();
Not available with PO_NO_PROCESS_CONTROL
Table 3.118. Arguments and Return Values for fork()
Argument Type | Return Type | Description |
---|---|---|
n/a | Integer | 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.119. Exceptions Thrown by fork()
err | desc |
---|---|
| Cannot fork if more than one thread is running. |
Returns the effective group ID of the current process.
getegid()
$egid = getegid();
Table 3.120. Arguments and Return Values for getegid()
Argument Type | Return Type | Description |
---|---|---|
n/a | Integer | 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.
geteuid()
Table 3.121. Arguments and Return Values for geteuid()
Argument Type | Return Type | Description |
---|---|---|
n/a | Integer | 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.
getgid()
$gid = getgid();
Table 3.122. Arguments and Return Values for getgid()
Argument Type | Return Type | Description |
---|---|---|
n/a | Integer | 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(address, [type]
)
$hostname = gethostbyaddr("192.168.0.33");
Table 3.123. Arguments and Return Values for gethostbyaddr()
Argument Type | Return Type | Description |
---|---|---|
| String | Returns the hostname of the system or NOTHING if the address is unknown. |
Table 3.124. 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(address, [type]
)
$hash = gethostbyaddr_long("192.168.0.33");
Table 3.125. Arguments and Return Values for gethostbyaddr_long()
Argument Type | Return Type | Description |
---|---|---|
| Hash | Returns a hash representing all host and address information corresponding to the network address passed or NOTHING if the address is unknown. |
Table 3.126. Host Information Hash
Key | Type | Value |
---|---|---|
| String | The official fully-qualified name of the host |
| List of Strings | Any hostname aliases for the host |
| String | The type of network address (either "ipv4" or "ipv6") |
| Integer | One of the Network Address Type Constants (either |
| Integer | The length of the addresses in bytes when represented in binary form. |
| List of Strings | All addresses corresponding to the host; the list should have at least 1 element |
Table 3.127. 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(hostname
)
$addr = gethostbyname("host1");
Table 3.128. Arguments and Return Values for gethostbyname()
Argument Type | Return Type | Description |
---|---|---|
| String | Returns the first address corresponding to the hostname passed or NOTHING if the host is unknown. |
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(hostname
)
$hash = gethostbyname_long("host1");
Table 3.129. Arguments and Return Values for gethostbyname_long()
Argument Type | Return Type | Description |
---|---|---|
| Hash | Returns a hash representing all host and address information corresponding to the hostname passed or NOTHING if the host is unknown. |
This function does not throw any exceptions.
Returns the hostname of the system.
gethostname()
$host = gethostname();
Table 3.130. Arguments and Return Values for gethostname()
Argument Type | Return Type | Description |
---|---|---|
n/a | String | Returns the hostname of the system. |
This function does not throw any exceptions.
Returns the PID (process ID) of the current process.
getpid()
$pid = getpid();
Table 3.131. Arguments and Return Values for getpid()
Argument Type | Return Type | Description |
---|---|---|
n/a | Integer | 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.
getppid()
$ppid = getppid();
Table 3.132. Arguments and Return Values for getppid()
Argument Type | Return Type | Description |
---|---|---|
n/a | Integer | 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.
getuid()
$uid = getuid();
Table 3.133. Arguments and Return Values for getuid()
Argument Type | Return Type | Description |
---|---|---|
n/a | Integer | Returns the real user ID of the current process. |
This function does not throw any exceptions.
Returns a list of files matching the string argument.
glob(string
)
$list = glob("*.txt");
Table 3.134. Arguments and Return Values for glob()
Argument Type | Return Type | Description |
---|---|---|
String | List | Returns a list of files matching the string argument. |
This function does not throw any exceptions.
Sends a signal to a process, if no signal number is given, then SIGHUP is sent by default.
kill(integer_pid, [integer_signal]
)
kill($pid, SIGINT);
Not available with PO_NO_EXTERNAL_PROCESS
Table 3.135. Arguments and Return Values for kill()
Argument Type | Return Type | Description |
---|---|---|
Integer, [Integer] | Integer | Sends a signal to a process, if the optional signal number is not given, then SIGHUP is sent. A 0 return value means that the signal was succesfully sent. |
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
)
setegid($egid);
Not available with PO_NO_PROCESS_CONTROL
Table 3.136. Arguments and Return Values for setegid()
Argument Type |
Return Type |
Description |
---|---|---|
EGID |
Integer |
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()) |
Table 3.137. 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
)
seteuid($euid);
Not available with PO_NO_PROCESS_CONTROL
Table 3.138. Arguments and Return Values for seteuid()
Argument Type |
Return Type |
Description |
---|---|---|
EUID |
Integer |
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()) |
Table 3.139. 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
)
setgid($gid);
Not available with PO_NO_PROCESS_CONTROL
Table 3.140. Arguments and Return Values for setgid()
Argument Type |
Return Type |
Description |
---|---|---|
GID |
Integer |
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()) |
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
)
setuid($uid);
Not available with PO_NO_PROCESS_CONTROL
Table 3.142. Arguments and Return Values for setuid()
Argument Type |
Return Type |
Description |
---|---|---|
UID |
Integer |
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()) |
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(seconds
)
sleep(5s); # sleeps for 5 seconds
Not available with PO_NO_PROCESS_CONTROL
Table 3.144. Arguments and Return Values for sleep()
Argument Type | Return Type | Description |
---|---|---|
Integer or Relative Date/Time | Integer | 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.
stat(pathname
)
$mode = stat($filepath)[2];
Not available with PO_NO_FILESYSTEM
Table 3.145. Arguments and Return Values for stat()
Argument Type | Return Type | Description |
---|---|---|
String | List | Returns a list of filesystem values for the file passed, following symbolic links. See Stat List below for a description of the list returned by this function. |
This function does not throw any exceptions.
Table 3.146. Stat List Description
Position | Data Type | Description |
---|---|---|
0 | Integer | device inode number the file is on |
1 | Integer | inode of the file |
2 | Integer | inode protection mode |
3 | Integer | number of hard links to this file |
4 | Integer | user ID of the owner |
5 | Integer | group ID of the owner |
6 | Integer | device type number |
7 | Integer | file size in bytes |
8 | Date/Time | last access time of the file |
9 | Date/Time | last modified time of the file |
10 | Date/Time | last change time of the file's inode |
11 | Integer | block size |
12 | Integer | blocks allocated for the file |
Returns the string corresponding to the error code passed (generally retrieved with errno()).
strerror(error_code
)
printf("%s\n", strerror(errno()));
Table 3.147. Arguments and Return Values for strerror()
Argument Type | Return Type | Description |
---|---|---|
Integer | String | Returns a string corresponding to the error code passed (normally retrieved with errno()) |
This function does not throw any exceptions.
Executes an external program and returns the exit code of the process.
system(shell_command
)
$rc = system("ls -l");
Not available with PO_NO_EXTERNAL_PROCESS
Table 3.148. Arguments and Return Values for system()
Argument | Return Type | Description |
---|---|---|
String | Integer | If shell meta-characters are present in the string to be executed, Qore uses the C library system() call to execute the external program, otherwise a fork() and exec() is used. The exit code of the process is returned as an integer. |
This function does not throw any exceptions.
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 1250ms
), however as this function supports a resolution of 1 microsecond, to achieve a resolution below milliseconds, an integer must be used instead of a relative date/time value. See sleep() for a similar function supporting second resolution.
usleep(file
)
usleep(1250ms); # sleeps for 1.25 seconds
usleep(500); # sleeps for 500 microseconds (0.5 milliseconds)
Not available with PO_NO_PROCESS_CONTROL
Table 3.149. Arguments and Return Values for usleep()
Argument Type | Return Type | Description |
---|---|---|
Integer or Relative Date/Time | Integer | Causes the current thread to sleep for a certain number of microseconds (1/1000000 second). Returns 0 for success. Integers are interpreted as microseconds, relative date/time values are interpreted literally. |
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(input_data, key, [init_vector]
)
$bin = blowfish_encrypt_cbc("hello there", $key);
Table 3.150. Arguments and Return Values for blowfish_encrypt_cbc()
Argument Type | Return Type | Description |
---|---|---|
String | Binary, String Binary, [String | Binary] | Binary | Encrypts data using the Cipher Block Chaining function for the blowfish algorithm; accepts a variable-length key (recommended 16-bytes or more). The initialization vector must be at least 8 bytes long if present. |
Table 3.151. 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, key, [init_vector]
)
$bin = blowfish_decrypt_cbc("hello there", $key);
Table 3.152. Arguments and Return Values for blowfish_decrypt_cbc()
Argument Type |
Return Type |
Description |
---|---|---|
Binary, String | Binary, [String | Binary] |
Binary |
Decrypts data using the Cipher Block Chaining function for the blowfish algorithm using a variable-length key. |
Table 3.153. 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, key, [init_vector]
)
$str = blowfish_decrypt_cbc_to_string($bin, $key);
Table 3.154. Arguments and Return Values for blowfish_decrypt_cbc_to_string()
Argument Type |
Return Type |
Description |
---|---|---|
Binary, Key, [init_vector] |
String |
Decrypts data to a string using the Cipher Block Chaining function for the blowfish algorithm using a variable-length key. |
Table 3.155. 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) |
Encrypts data using the Cipher Block Chaining function for the DES algorithm using an 8-byte key. Returns a binary object of the encrypted data.
des_encrypt_cbc(input_data, key, [init_vector]
)
$bin = des_encrypt_cbc($text, $key);
Table 3.156. Arguments and Return Values for des_encrypt_cbc()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary, String | Binary, [String | Binary] |
Binary |
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.157. 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, key, [init_vector]
)
Table 3.158. Arguments and Return Values for des_decrypt_cbc()
Argument Type |
Return Type |
Description |
---|---|---|
Binary, String | Binary, [String | Binary] |
Binary |
Decrypts data using the Cipher Block Chaining function for the DES algorithm using an 8-byte key. If the init_vector is present it must also be at least 8 bytes long. |
Table 3.159. 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, key, [init_vector]
)
Table 3.160. Arguments and Return Values for des_decrypt_cbc_to_string()
Argument Type |
Return Type |
Description |
---|---|---|
Binary, Key, [init_vector] |
String |
Decrypts data using the Cipher Block Chaining function for the DES algorithm using an 8-byte key. If the init_vector is present it must also be at least 8 bytes long. |
Table 3.161. 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(input_data, key, [init_vector]
)
$bin = des_ede_encrypt_cbc($text, $key);
Table 3.162. Arguments and Return Values for des_ede_encrypt_cbc()
Argument Type | Return Type | Description |
---|---|---|
String | Binary |
Binary |
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.163. 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, key, [init_vector]
)
$bin = des_ede_decrypt_cbc($data, $key);
Table 3.164. Arguments and Return Values for des_ede_decrypt_cbc()
Argument Type |
Return Type |
Description |
---|---|---|
Binary, String | Binary, [String | Binary] |
Binary |
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.165. 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, key, [init_vector]
)
$str = des_ede_decrypt_cbc_to_string($data, $key);
Table 3.166. Arguments and Return Values for des_ede_decrypt_cbc_to_string()
Argument Type |
Return Type |
Description |
---|---|---|
Binary, String | Binary, [String | Binary] |
String |
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.167. 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, key, [init_vector]
)
$bin = des_ede3_encrypt_cbc($data, $key);
Table 3.168. Arguments and Return Values for des_ede3_encrypt_cbc()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary, String | Binary, [String | Binary] |
Binary |
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.169. 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(encrypted_data, key, [init_vector]
)
$bin = des_ede3_decrypt_cbc($data, $key);
Table 3.170. Arguments and Return Values for des_ede3_decrypt_cbc()
Argument Type |
Return Type |
Description |
---|---|---|
Binary, Key, [init_vector] |
Binary |
Decrypts data using the Cipher Block Chaining function for the three-key triple DES algorithm. |
Table 3.171. 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(encrypted_data, key, [init_vector]
)
$str = des_ede3_decrypt_cbc_to_string($data, $key);
Table 3.172. Arguments and Return Values for des_ede3_decrypt_cbc_to_string()
Argument Type |
Return Type |
Description |
---|---|---|
Binary, String | Binary, [String | Binary] |
String |
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.173. 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, key, [init_vector]
)
$bin = desx_encrypt_cbc($data, $key);
Table 3.174. Arguments and Return Values for desx_encrypt_cbc()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary, String | Binary, [String | Binary] |
Binary |
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. |
Table 3.175. 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(encrypted_data, key, [init_vector]
)
$bin = desx_decrypt_cbc($data, $key);
Table 3.176. Arguments and Return Values for desx_decrypt_cbc()
Argument Type |
Return Type |
Description |
---|---|---|
Binary, Key, [init_vector] |
Binary |
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. |
Table 3.177. 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, key, [init_vector]
)
$str = desx_decrypt_cbc_to_string($data, $key);
Table 3.178. Arguments and Return Values for desx_decrypt_cbc_to_string()
Argument Type |
Return Type |
Description |
---|---|---|
Binary, String 7 Binary, [String | Binary] |
String |
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. |
Table 3.179. 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, key, [init_vector]
)
$bin = rc2_encrypt_cbc($data, $key);
Table 3.180. Arguments and Return Values for rc2_encrypt_cbc()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary, String | Binary, [String | Binary] |
Binary |
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. |
Table 3.181. 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(encrypted_data, key, [init_vector]
)
$bin = rc2_decrypt_cbc($data, $key);
Table 3.182. Arguments and Return Values for rc2_decrypt_cbc()
Argument Type |
Return Type |
Description |
---|---|---|
Binary, String | Binary, [String | Binary] |
Binary |
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. |
Table 3.183. 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(encrypted_data, key, [init_vector]
)
$str = rc2_decrypt_cbc_to_string($data, $key);
Table 3.184. Arguments and Return Values for rc2_decrypt_cbc_to_string()
Argument Type |
Return Type |
Description |
---|---|---|
Binary, String | Binary, [String | Binary] |
String |
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. |
Table 3.185. 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, key, [init_vector]
)
$bin = cast5_encrypt_cbc($data, $key);
Table 3.186. Arguments and Return Values for cast5_encrypt_cbc()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary, String | Binary, [String | Binary] |
Binary |
Encrypts data using the Cipher Block Chaining function for the CAST5 algorithm using a variable-length key and an optional 8-byte initialization vector. |
Table 3.187. 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(encrypted_data, key, [init_vector]
)
$bin = cast5_decrypt_cbc($data, $key);
Table 3.188. Arguments and Return Values for cast5_decrypt_cbc()
Argument Type |
Return Type |
Description |
---|---|---|
Binary, Key, [init_vector] |
Binary |
Decrypts data using the Cipher Block Chaining function for the CAST5 algorithm using a variable-length key and an optional 8-byte initialization vector. |
Table 3.189. 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, key, [init_vector]
)
$str = cast5_decrypt_cbc_to_string($data, $key);
Table 3.190. Arguments and Return Values for cast5_decrypt_cbc_to_string()
Argument Type |
Return Type |
Description |
---|---|---|
Binary, Key, [init_vector] |
String |
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. |
Table 3.191. 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, key, [init_vector]
)
$bin = rc4_encrypt($data, $key);
Table 3.192. Arguments and Return Values for rc4_encrypt()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary, String | Binary, [String | Binary, ] |
Binary |
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. |
Table 3.193. 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, key, [init_vector]
)
$bin = rc4_decrypt($data, $key);
Table 3.194. Arguments and Return Values for rc4_decrypt()
Argument Type |
Return Type |
Description |
---|---|---|
Binary, Key, [init_vector] |
Binary |
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. |
Table 3.195. 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, key, [init_vector]
)
$str = rc4_decrypt_to_string($data, $key);
Table 3.196. Arguments and Return Values for rc4_decrypt_to_string()
Argument Type |
Return Type |
Description |
---|---|---|
Binary, Key, [init_vector] |
String |
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. |
Table 3.197. 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, key, [init_vector]
)
$bin = rc5_encrypt_cbc($data, $key);
Table 3.198. Arguments and Return Values for rc5_encrypt_cbc()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary, String | Binary, [String | Binary] |
Binary |
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. |
Table 3.199. 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, key, [init_vector]
)
$bin = rc5_decrypt_cbc($data, $key);
Table 3.200. Arguments and Return Values for rc5_decrypt_cbc()
Argument Type |
Return Type |
Description |
---|---|---|
Binary, Key, [init_vector] |
Binary |
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. |
Table 3.201. 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(encrypted_data, key, [init_vector]
)
$str = rc5_decrypt_cbc_to_string($data, $key);
Table 3.202. Arguments and Return Values for rc5_decrypt_cbc_to_string()
Argument Type |
Return Type |
Description |
---|---|---|
Binary, Key, [init_vector] |
String |
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. |
Table 3.203. 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 |
Returns the DSS message digest of the supplied argument (for strings, the trailing null character is not included in the digest) as a string of hex characters.
DSS(string | binary
)
$str = DSS("hello"); # returns "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d"
Table 3.204. Arguments and Return Values for DSS()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
String |
Returns the DSS message digest of the supplied argument (for strings, the trailing null character is not included in the digest) |
Table 3.205. Exceptions thrown by DSS()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Returns the DSS message digest of the supplied argument (for strings, the trailing null character is not included in the digest) as a binary object.
DSS_bin(string | binary
)
$bin = DSS_bin("hello"); # returns <aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d>
Table 3.206. Arguments and Return Values for DSS_bin()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
Binary |
Returns the DSS message digest of the supplied argument (for strings, the trailing null character is not included in the digest). |
Table 3.207. Exceptions thrown by DSS_bin()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Returns the DSS1 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) as a hex string.
DSS1(string | binary
)
$str = DSS1("hello"); # return "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d"
Table 3.208. Arguments and Return Values for DSS1()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
String |
The DSS1 message digest of the supplied argument as a hex string (for strings, the trailing null character is not included in the digest) |
Table 3.209. Exceptions thrown by DSS1()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Returns the DSS1 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) as a binary object.
DSS1_bin(string | binary
)
$bin = DSS1_bin("hello"); # returns <aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d>
Table 3.210. Arguments and Return Values for DSS1_bin()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
Binary |
The DSS1 message digest of the supplied argument (for strings, the trailing null character is not included in the digest). |
Table 3.211. Exceptions thrown by DSS1()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Returns the MD2 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) as a string of hex digits.
MD2(string | binary
)
$str = MD2("hello"); # returns "a9046c73e00331af68917d3804f70655"
Table 3.212. Arguments and Return Values for MD2()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
String |
The MD2 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) |
Table 3.213. Exceptions thrown by MD2()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Returns the MD2 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) as a string of hex digits.
MD2_bin(string | binary
)
$bin = MD2_bin("hello"); # returns <a9046c73e00331af68917d3804f70655>
Table 3.214. Arguments and Return Values for MD2_bin()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
Binary |
The MD2 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) |
Table 3.215. Exceptions thrown by MD2_bin()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Returns the MD4 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) as a string of hex characters.
MD4(string | binary
)
$str = MD4("hello"); # returns "866437cb7a794bce2b727acc0362ee27"
Table 3.216. Arguments and Return Values for MD4()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
String |
The MD4 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) |
Table 3.217. Exceptions thrown by MD4()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Returns the MD4 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) as a string of hex characters.
MD4_bin(string | binary
)
$str = MD4_bin("hello"); # returns "866437cb7a794bce2b727acc0362ee27"
Table 3.218. Arguments and Return Values for MD4_bin()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
Binary |
The MD4 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) as a binary object |
Table 3.219. Exceptions thrown by MD4_bin()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Returns the MD5 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) as a string of hex characters.
MD5(string | binary
)
$str = MD5("hello"); # returns "5d41402abc4b2a76b9719d911017c592"
Table 3.220. Arguments and Return Values for MD5()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
String |
The MD5 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) as a string of hext characters. |
Table 3.221. Exceptions thrown by MD5()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Returns the MD5 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) as a binary object.
MD5_bin(string | binary
)
$str = MD5_bin("hello"); # returns <5d41402abc4b2a76b9719d911017c592>
Table 3.222. Arguments and Return Values for MD5_bin()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
Binary |
The MD5 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) as a binary object. |
Table 3.223. 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.
MDC2(string | binary
)
$str = MDC2("hello");
Table 3.224. Arguments and Return Values for MDC2()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
String |
Returns the MDC2 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) |
Table 3.225. 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.
MDC2_bin(string | binary
)
$bin = MDC2_bin("hello");
Table 3.226. Arguments and Return Values for MDC2_bin()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
Binary |
Returns the MDC2 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) |
Table 3.227. 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 |
Returns the RIPEMD160 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) as a string of hex characters.
RIPEMD160(string | binary
)
$str = RIPEMD160("hello"); # returns "108f07b8382412612c048d07d13f814118445acd"
Table 3.228. Arguments and Return Values for RIPEMD160()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
String |
Returns the RIPEMD160 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) |
Table 3.229. 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(string | binary
)
$str = RIPEMD160_bin("hello"); # returns "108f07b8382412612c048d07d13f814118445acd"
Table 3.230. Arguments and Return Values for RIPEMD160_bin()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
Binary |
Returns the RIPEMD160 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) |
Table 3.231. Exceptions thrown by RIPEMD160_bin()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Returns the SHA message digest of the supplied argument (for strings, the trailing null character is not included in the digest) as a string of hext characters.
SHA(string | binary
)
$str = SHA("hello"); returns "ac62a630ca850b4ea07eda664eaecf9480843152"
Table 3.232. Arguments and Return Values for SHA()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
String |
Returns the SHA message digest of the supplied argument (for strings, the trailing null character is not included in the digest) |
Table 3.233. Exceptions thrown by SHA()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Returns the SHA message digest of the supplied argument (for strings, the trailing null character is not included in the digest)
SHA_bin(string | binary
)
$bin = SHA_bin("hello"); returns <ac62a630ca850b4ea07eda664eaecf9480843152>
Table 3.234. Arguments and Return Values for SHA_bin()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
Binary |
Returns the SHA message digest of the supplied argument (for strings, the trailing null character is not included in the digest) |
Table 3.235. Exceptions thrown by SHA_bin()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Returns the SHA1 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.
SHA1(string | binary
)
$str = SHA1("hello"); # "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d"
Table 3.236. Arguments and Return Values for SHA1()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
String |
Returns the SHA1 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) |
Table 3.237. Exceptions thrown by SHA1()
err |
desc |
---|---|
|
missing data parameter, invalid data parameter (expecing string or binary), error calculating digest |
Returns the SHA1 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.
SHA1_bin(string | binary
)
$bin = SHA1_bin("hello"); # <aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d>
Table 3.238. Arguments and Return Values for SHA1_bin()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
String |
Returns the SHA1 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) |
Table 3.239. 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.
SHA224(string | binary
)
$str = SHA224("hello"); # "ea09ae9cc6768c50fcee903ed054556e5bfc8347907f12598aa24193"
Table 3.240. Arguments and Return Values for SHA224()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
String |
Returns the SHA224 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) |
Table 3.241. 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(string | binary
)
$bin = SHA224_bin("hello"); # <ea09ae9cc6768c50fcee903ed054556e5bfc8347907f12598aa24193>
Table 3.242. Arguments and Return Values for SHA224_bin()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
String |
Returns the SHA224 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) |
Table 3.243. 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(string | binary
)
$str = SHA256("hello"); # "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
Table 3.244. Arguments and Return Values for SHA256()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
String |
Returns the SHA256 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) |
Table 3.245. 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(string | binary
)
$bin = SHA256_bin("hello"); # <2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824>
Table 3.246. Arguments and Return Values for SHA256_bin()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
String |
Returns the SHA256 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) |
Table 3.247. 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(string | binary
)
$str = SHA384("hello"); # "59e1748777448c69de6b800d7a33bbfb9ff1b463e44354c3553bcdb9c666fa90125a3c79f90397bdf5f6a13de828684f"
Table 3.248. Arguments and Return Values for SHA384()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
String |
Returns the SHA384 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) |
Table 3.249. 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(string | binary
)
$bin = SHA384_bin("hello"); # <59e1748777448c69de6b800d7a33bbfb9ff1b463e44354c3553bcdb9c666fa90125a3c79f90397bdf5f6a13de828684f>
Table 3.250. Arguments and Return Values for SHA384_bin()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
String |
Returns the SHA384 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) |
Table 3.251. 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(string | binary
)
$str = SHA512("hello"); # "9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043"
Table 3.252. Arguments and Return Values for SHA512()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
String |
Returns the SHA512 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) |
Table 3.253. 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(string | binary
)
$bin = SHA512_bin("hello"); # <9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043>
Table 3.254. Arguments and Return Values for SHA512_bin()
Argument Type |
Return Type |
Description |
---|---|---|
String | Binary |
String |
Returns the SHA512 message digest of the supplied argument (for strings, the trailing null character is not included in the digest) |
Table 3.255. 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(directory_string
)
chdir("/usr/share");
Not available with PO_NO_FILESYSTEM
Table 3.256. Arguments and Return Values for chdir()
Argument Type | Return Type | Description |
---|---|---|
String | Integer | Changes the current working directory. Returns 0 if successful. |
Table 3.257. Exceptions Thrown by chdir()
err | desc |
---|---|
| The string for the new directory was missing from the call. |
Changes the mode of a file.
chmod(filename, mode
)
chmod("/bin/login", 0755);
Not available with PO_NO_FILESYSTEM
Table 3.258. Arguments and Return Values for chmod()
Argument Type | Return Type | Description |
---|---|---|
String, Integer | Integer | Sets the mode of the given file to the integer passed. Returns 0 if successful. |
Table 3.259. 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(filepath, user_id, group_id
)
chown("/bin/login", 0, 0);
Not available with PO_NO_FILESYSTEM
Table 3.260. Arguments and Return Values for chown()
Argument Type | Return Type | Description |
---|---|---|
String, Integer, Integer | Integer | Changes the owner and group of the file passed. Returns 0 if successful. |
Table 3.261. Exceptions Thrown by chown()
err | desc |
---|---|
| Expecting a string as the first argument. |
Returns a string giving the current working directory.
getcwd()
my $cwd = getcwd();
Not available with PO_NO_FILESYSTEM
Table 3.262. Arguments and Return Values for getcwd()
Argument Type | Return Type | Description |
---|---|---|
n/a | String | Returns the complete path of the current working directory as a 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).
hlstat(pathname
)
$type = hlstat("/bin/sh").type; # returns "REGULAR"
Not available with PO_NO_FILESYSTEM
Table 3.264. 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.
hstat(pathname
)
$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.
is_bdev(path
)
$bool = is_bdev("/dev/sda");
Not available with PO_NO_FILESYSTEM
Table 3.266. Arguments and Return Values for is_bdev()
Argument Type |
Return Type |
Description |
---|---|---|
Path |
Boolean |
Returns True if the string passed identifies a block device file on the filesystem. |
Returns True if the string passed identifies a character device file on the filesystem.
is_cdev(path
)
$bool = is_cdev("/dev/tty");
Not available with PO_NO_FILESYSTEM
Table 3.267. Arguments and Return Values for is_cdev()
Argument Type |
Return Type |
Description |
---|---|---|
Path |
Boolean |
Returns True if the string passed identifies a character device file on the filesystem. |
Returns True if the string passed identifies a device file (either block or character) on the filesystem.
is_dev(path
)
$bool = is_dev("/dev/sda");
Not available with PO_NO_FILESYSTEM
Table 3.268. Arguments and Return Values for is_dev()
Argument Type |
Return Type |
Description |
---|---|---|
Path |
Boolean |
Returns True if the string passed identifies a device file (either block or character) on the filesystem. |
Returns True if the string passed identifies a directory on the filesystem.
is_dir(path
)
$bool = is_dir("/usr/share");
Not available with PO_NO_FILESYSTEM
Table 3.269. Arguments and Return Values for is_dir()
Argument Type |
Return Type |
Description |
---|---|---|
Path |
Boolean |
Returns True if the string passed identifies a directory on the filesystem. |
Returns True if the string passed identifies an executable file.
is_executable(path
)
$bool = is_executable("/bin/sh");
Not available with PO_NO_FILESYSTEM
Table 3.270. Arguments and Return Values for is_executable()
Argument Type |
Return Type |
Description |
---|---|---|
Path |
Boolean |
Returns True if the string passed identifies an executable file. |
Returns True if the string passed identifies a regular file on the filesystem.
is_file(path
)
$bool = is_file("/etc/hosts");
Not available with PO_NO_FILESYSTEM
Table 3.271. Arguments and Return Values for is_file()
Argument Type |
Return Type |
Description |
---|---|---|
Path |
Boolean |
Returns True if the string passed identifies a regular file on the filesystem. |
Returns True if the string passed identifies a symbolic link on the filesystem.
is_link(path
)
$bool = is_link("/bin/sh");
Not available with PO_NO_FILESYSTEM
Table 3.272. Arguments and Return Values for is_link()
Argument Type |
Return Type |
Description |
---|---|---|
Path |
Boolean |
Returns True if the string passed identifies a symbolic link on the filesystem. |
Returns True if the string passed identifies a pipe (FIFO) on the filesystem.
is_pipe(path
)
$bool = is_pipe("/bin/sh");
Not available with PO_NO_FILESYSTEM
Table 3.273. Arguments and Return Values for is_pipe()
Argument Type |
Return Type |
Description |
---|---|---|
Path |
Boolean |
Returns True if the string passed identifies a pipe (FIFO) on the filesystem. |
Returns True if the string passed identifies a file readable by the current user.
is_readable(path
)
$bool = is_readable("/etc/hosts");
Not available with PO_NO_FILESYSTEM
Table 3.274. Arguments and Return Values for is_readable()
Argument Type |
Return Type |
Description |
---|---|---|
Path |
Boolean |
Returns True if the string passed identifies a file readable by the current user. |
Returns True if the string passed identifies a socket on the filesystem.
is_socket(path
)
$bool = is_socket("/tmp/X0");
Not available with PO_NO_FILESYSTEM
Table 3.275. Arguments and Return Values for is_socket()
Argument Type |
Return Type |
Description |
---|---|---|
Path |
Boolean |
Returns True if the string passed identifies a socket on the filesystem. |
Returns True if the string passed identifies a file writable by the current user.
is_writeable(path
)
$bool = is_writeable("/etc/hosts");
Not available with PO_NO_FILESYSTEM
Table 3.276. Arguments and Return Values for is_writeable()
Argument Type |
Return Type |
Description |
---|---|---|
Path |
Boolean |
Returns True if the string passed identifies a file writable by the current user. |
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(filepath, user_id, group_id
)
lchown("/bin/login", 0, 0);
Not available with PO_NO_FILESYSTEM
Table 3.277. Arguments and Return Values for lchown()
Argument Type | Return Type | Description |
---|---|---|
String, Integer, Integer | Integer | Changes the owner and group of the file passed. Returns 0 if successful. |
Table 3.278. Exceptions Thrown by lchown()
err | desc |
---|---|
| Expecting a string as the first argument. |
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.
lstat(pathname
)
$list = lstat(("/bin/sh");
Not available with PO_NO_FILESYSTEM
Table 3.279. Arguments and Return Values for lstat()
Argument Type | Return Type | Description |
---|---|---|
String | List | Returns a list of filesystem values for the file passed. See Stat List for a description of the list returned by this function. |
This function does not throw any exceptions.
Creates a directory, optionally specifying the mode.
mkdir(string_name, [mode]
)
mkdir("/tmp/newdir", 0755);
Not available with PO_NO_FILESYSTEM
Table 3.280. Arguments and Return Values for mkdir()
Argument Type | Return Type | Description |
---|---|---|
String, [Integer] | Integer | Creates a directory with the specified name. If the mode parameter is not sent, then 0777 is used by default (which is AND'ed with the umask). Returns 0 if no error occurred. |
Table 3.281. Exceptions Thrown by mkdir()
err | desc |
---|---|
| Missing directory name for the mkdir() call. |
Creates a named pipe file with an optional file mode (default = 0600).
mkfifo(filename, [mode]
)
mkfifo("/tmp/pipe");
Not available with PO_NO_FILESYSTEM
Table 3.282. Arguments and Return Values for mkfifo()
Argument Type |
Return Type |
Description |
---|---|---|
String, [Integer] |
Integer |
Creates a named pipe with the supplied path and optional mode. If |
This function does not throw any exceptions.
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(old_path, new_path
)
rename("/tmp/temp_file", "/home/test/test_file.txt");
Not available with PO_NO_FILESYSTEM
Table 3.283. Arguments and Return Values for rename()
Argument Type | Return Type | Description |
---|---|---|
String, String | n/a | Renames (or moves) the file ior directory indentified by |
Table 3.284. Exceptions Thrown by rename()
err | desc |
---|---|
| Missing arguments or a system error occured. |
Removes a directory.
rmdir(path
)
rmdir("/tmp/newdir");
Not available with PO_NO_FILESYSTEM
Table 3.285. Arguments and Return Values for rmdir()
Argument Type | Return Type | Description |
---|---|---|
String | Integer | Removes an empty directory. Returns 0 if no error occurred. |
Table 3.286. Exceptions Thrown by rmdir()
err | desc |
---|---|
| Missing directory name for the |
Sets the file creation mask for the process.
umask(mode
)
umask(0777);
Not available with PO_NO_FILESYSTEM
Table 3.287. Arguments and Return Values for umask()
Argument Type | Return Type | Description |
---|---|---|
Integer | Integer | Sets the file creation mask for the process, returns 0 for success. If no argument is passed, no action is taken, and the function returns NOTHING. |
This function does not throw any exceptions.
Deletes a file and returns 0 for success.
unlink(file
)
unlink("/tmp/tmp_file");
Not available with PO_NO_FILESYSTEM
Table 3.288. Arguments and Return Values for unlink()
Argument Type | Return Type | Description |
---|---|---|
String | Integer | Deletes a file and returns 0 for success. |
This function does not throw any exceptions.
This section documents functions for compressing and uncompressing data.
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: 6). Note that strings are compressed without the trailing null character.
compress(string | binary, [level]
)
$bin = compress("hello");
Table 3.289. Arguments and Return Values for compress()
Argument Type | Return Type | Description |
---|---|---|
| Binary | Compresses the input data and returns a binary object. The optional |
Table 3.290. 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 = gunzip_to_binary($data);
Table 3.291. Arguments and Return Values for gunzip_to_binary()
Argument Type | Return Type | Description |
---|---|---|
| Binary | Uncompresses the input data and returns a binary object. |
Table 3.292. 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, [encoding]
)
$str = gunzip_to_string($gzipped_string);
Table 3.293. Arguments and Return Values for gunzip_to_string()
Argument Type | Return Type | Description |
---|---|---|
| Binary | Uncompresses the input data and returns a string. The optional |
Table 3.294. 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; if no second argument is given, then a tradeoff between speed and compression size is taken (default: 6). Note that strings are compressed without the trailing null character.
gzip(string | binary, [level]
)
$bin = gzip($data);
Table 3.295. Arguments and Return Values for gzip()
Argument Type | Return Type | Description |
---|---|---|
| Binary | Compresses the input data and returns a binary object of the gzipped data. The optional |
Table 3.296. 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 compressed with bzip2 and returns a binary object of the uncompressed data.
bunzip2_to_binary(binary
)
$bin = bunzip2_to_binary($data);
Table 3.297. Arguments and Return Values for bunzip2_to_binary()
Argument Type | Return Type | Description |
---|---|---|
| Binary | Uncompresses the input data and returns a binary object. |
Table 3.298. Exceptions Thrown by bunzip2_to_binary()
err | desc |
---|---|
| libbz2 returned an error while processing. |
Uncompresses data compressed with bzip2 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.
bunzip2_to_string(binary, [encoding]
)
$str = bunzip2_to_string($gzipped_string);
Table 3.299. Arguments and Return Values for bunzip2_to_string()
Argument Type | Return Type | Description |
---|---|---|
| Binary | Uncompresses the input data and returns a string. The optional |
Table 3.300. Exceptions Thrown by bunzip2_to_string()
err | desc |
---|---|
| libbz2 returned an error while processing. |
Performs "bzip2" data compression and returns a binary object of the compressed data. The optional second argument specifies the compression buffer size as an argument from 1 - 9; if no second argument is given, then the maximum buffer size is assumed (default: 9). Note that strings are compressed without the trailing null character.
bzip2(string | binary, [level]
)
$bin = bzip2($data);
Table 3.301. Arguments and Return Values for bzip2()
Argument Type | Return Type | Description |
---|---|---|
| Binary | Compresses the input data and returns a binary object of the bzip2 data. The optional |
Table 3.302. Exceptions Thrown by bzip2()
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 = uncompress_to_binary($compressed_data);
Table 3.303. Arguments and Return Values for uncompress_to_binary()
Argument Type | Return Type | Description |
---|---|---|
| Binary | Uncompresses the input data and returns a binary object. |
Table 3.304. 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, [encoding]
)
$str = uncompress_to_string($compressed_data);
Table 3.305. Arguments and Return Values for uncompress_to_string()
Argument Type | Return Type | Description |
---|---|---|
| Binary | Uncompresses the input data and returns a string. The optional |
Table 3.306. Exceptions Thrown by uncompress_to_string()
err | desc |
---|---|
| zlib returned an error while processing. |
Executes a process and returns a string of the output (stdout only)
backquote(shell_command_string
)
$files = backquote("ls");
Not available with PO_NO_EXTERNAL_PROCESS
Table 3.307. Arguments and Return Values for backquote()
Argument Type | Return Type | Description |
---|---|---|
String | String | Executes the string passed as a shell command in a subprocess and returns the stdout of the process as a string. |
Table 3.308. 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(func, [arg1, arg2, ...]
)
$result = call_builtin_function("func_name", $arg1, $arg2);
Table 3.309. Arguments and Return Values for call_builtin_function()
Argument Type | Return Type | Description |
---|---|---|
String, Any | Any (depends on function) | Executes the given builtin function with the remainder of the arguments as the arguments to the function. |
Table 3.310. Exceptions Thrown by call_builtin_function()
err | desc |
---|---|
| The first argument must be a string. |
| Parse options do not allow access to the function. |
| The 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(func, [args]
)
call_builtin_function_args("func_name", $arg_list);
Table 3.311. Arguments and Return Values for call_builtin_function_args()
Argument Type | Return Type | Description |
---|---|---|
String, [List] | Any (depends on function) | Executes the given builtin function using any second argument as the list of arguments. |
Table 3.312. Exceptions Thrown by call_builtin_function_args()
err | desc |
---|---|
| The first argument must be a string. |
| 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, passing the remaining arguments after the function name to the function, closure, or call reference.
call_function(func, [arg1, arg2, ...]
)
$result = call_function("func_name", $arg1, $arg2);
$result = call_function($call_ref, $arg1, $arg2);
Table 3.313. Arguments and Return Values for call_function()
Argument Type | Return Type | Description |
---|---|---|
String | closure | call reference, Any | Any (depends on function) | 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.314. Exceptions Thrown by call_function()
err | desc |
---|---|
| The first argument must be a string, closure, or call reference. |
| 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(func, [args]
)
call_function_args("func_name", $arg_list);
call_function_args($call_ref, $arg_list);
Table 3.315. Arguments and Return Values for call_function_args()
Argument Type | Return Type | Description |
---|---|---|
String | closure | call reference, [List] | Any (depends on function) | Executes the given function, closure, or call reference using any second argument as the list of arguments. |
Table 3.316. Exceptions Thrown by call_function_args()
err | desc |
---|---|
| The first argument must be a string, closure, or call reference. |
| 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, method_string, [args ...]
)
$result = callObjectMethod($obj, "method", $arg1, $arg2);
Table 3.317. Arguments and Return Values for callObjectMethod()
Argument Type | Return Type | Description |
---|---|---|
Object, String, [args ...] | Any (depends on method) | Calls a method of an object, passing the remainder of the arguments to the function as arguments to the method, and returns the return value, if any. |
Table 3.318. 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, method_string, [arg_list]
)
$result = callObjectMethodArgs($obj, "method", $arg_list);
Table 3.319. Arguments and Return Values for callObjectMethodArgs()
Argument Type | Return Type | Description |
---|---|---|
Object, String, [args ...] | Any (depends on method) | Calls a method of an object, using the optional third argument as the argument list to the method, and returns the return value, if any. |
Table 3.320. 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
)
$bool = existsFunction("func_name");
Table 3.321. Arguments and Return Values for existsFunction()
Argument Type | Return Type | Description |
---|---|---|
String | Boolean | Returns True if the function exists in the current program's function name space, otherwise returns False. |
This function does not throw any exceptions.
Returns "builtin", "user", or NOTHING according to the function name passed.
functionType(string
)
$type = functionType("print");
Table 3.322. Arguments and Return Values for functionType()
Argument Type | Return Type | Description |
---|---|---|
String | Boolean | Returns "builtin" (for a builtin function), "user" (for a user function), or NOTHING (if the function cannot be found) according to the function name passed. |
This function does not throw any exceptions.
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()
$info = get_qore_library_info();
Table 3.323. Arguments and Return Values for get_qore_library_info()
Arguments | Return Type | Description |
---|---|---|
n/a | Hash | 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.324. 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()
$list = get_qore_option_list();
Table 3.325. Arguments and Return Values for get_qore_option_list()
Arguments | Return Type | Description |
---|---|---|
n/a | List | 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.326. 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(expr, [offset]
)
$byte = getByte($bin, 2); # returns the thrid byte of the binary object
Table 3.327. Arguments and Return Values for getByte()
Arguments | Return Type | Description |
---|---|---|
| Integer | The value of the byte at the offset in the string or binary object. If no offset is passed, then the first byte is returned. If the object is empty or the offset is larger than the object's size, then no value is returned. |
Returns the class name of an object.
getClassName(object
)
$name = getClassName($obj);
Table 3.328. Arguments and Return Values for getClassName()
Argument Type |
Return Type |
Description |
---|---|---|
Object |
String |
Returns the class name of the object passed. |
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(driver_name
)
$caps = getDBIDriverCapabilities("oracle");
Table 3.329. Arguments and Return Values for getDBIDriverCapabilities()
Argument Type | Return Type | Description |
---|---|---|
String | Integer | 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(driver_name
)
$list = getDBIDriverCapabilityList("mysql");
Table 3.330. Arguments and Return Values for getDBIDriverCapabilityList()
Argument Type | Return Type | Description |
---|---|---|
String | List | 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()
$list = getDBIDriverList();
Table 3.331. Arguments and Return Values for getDBIDriverList()
Argument Type | Return Type | Description |
---|---|---|
n/a | List | 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()
$list = getFeatureList();
Table 3.332. Arguments and Return Values for getFeatureList()
Argument Type | Return Type | Description |
---|---|---|
n/a | List | 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
)
$list = getMethodList($obj);
Table 3.333. Arguments and Return Values for getMethodList()
Argument Type | Return Type | Description |
---|---|---|
Object | List | Returns all methods in the class, both private and public. Does not return inherited methods. If no object is passed to the function, NOTHING is returned. |
This function does not throw any exceptions.
Returns a list of hashes describing the currently-loaded Qore modules.
getModuleList()
$list = getModuleList();
Table 3.334. Arguments and Return Values for getModuleList()
Argument Type | Return Type | Description |
---|---|---|
n/a | List | 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()
$encoding = get_default_encoding();
Table 3.335. Arguments and Return Values for get_default_encoding()
Argument Type | Return Type | Description |
---|---|---|
n/a | String | Returns the name of the default character encoding. |
This function does not throw any exceptions.
Returns a hash representing the user information for the user ID passed.
getpwuid(integer_uid
)
$hash = getpwuid(0); # returns the login information for root
Table 3.336. Arguments and Return Values for getpwuid()
Argument Type |
Return Type |
Description |
---|---|---|
Integer |
Hash |
Returns a hash representing the user information for the user ID passed. If the uid does not exist, NOTHING is returned. Otherwise the hash has the following keys: pw_name, pw_passwd, pw_gecos, pw_dir, pw_shell, pw_uid, pw_gid. |
This function does not throw any exceptions.
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()
$path = get_script_path();
Table 3.337. Arguments and Return Values for get_script_path()
Argument Type | Return Type | Description |
---|---|---|
n/a | String or NOTHING | Returns the path name of the current script, or NOTHING if unknown. |
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()
$dir = get_script_dir();
Table 3.338. Arguments and Return Values for get_script_dir()
Argument Type | Return Type | Description |
---|---|---|
n/a | String or NOTHING | Returns the name of the directory for the current script, or NOTHING if unknown. |
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()
$name = get_script_name();
Table 3.339. Arguments and Return Values for get_script_name()
Argument Type | Return Type | Description |
---|---|---|
n/a | String or NOTHING | Returns the filename of the current script, or NOTHING if unknown. |
This function does not throw any exceptions.
Returns a list of all the values in the hash argument passed.
hash_values(hash
)
$list = hash_values($hash);
Table 3.340. Arguments and Return Values for hash_values()
Argument Type |
Return Type |
Description |
---|---|---|
Hash |
List |
Returns a list of all the values in the hash argument passed. If no hash is passed, returns NOTHING. |
This function does not throw any exceptions.
Returns an integer for a hexadecimal string value.
hextoint(hex_string
)
$int = hextoint("ab3d4e0f12");
Table 3.341. Arguments and Return Values for hextoint()
Argument Type |
Return Type |
Description |
---|---|---|
String |
Integer |
Returns an integer for a hexadecimal string value. |
This function does not throw any exceptions.
Returns a string with any HTML escape codes translated to the original characters.
html_decode(string
)
html_decode("<hello>"); # returns "<hello>"
Table 3.342. Arguments and Return Values for html_decode()
Argument Type | Return Type | Description |
---|---|---|
String | String | Returns a string with any HTML escape codes (ie & -> &, etc) translated to the original characters. |
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
)
$str = html_encode("<hello>"); # returns "<hello>"
Table 3.343. Arguments and Return Values for html_encode()
Argument Type | Return Type | Description |
---|---|---|
String | String | Returns a string with characters needed HTML escape code transation (ie & -> & etc) translated to the escape codes. |
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(value, list
)
my $bool = inlist(123, (True, "123", False); # this will return True
Table 3.344. Arguments and Return Values for inlist()
Argument Type | Return Type | Description |
---|---|---|
| Boolean | Returns True if |
| Boolean | Always returns False. |
| Boolean | Returns the value of the comparison of |
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(value, list
)
my $bool = inlist_hard(123, (True, "123", False); # this will return False
Table 3.345. Arguments and Return Values for inlist_hard()
Argument Type | Return Type | Description |
---|---|---|
| Boolean | Returns True if |
| Boolean | Always returns False. |
| Boolean | Returns the value of the comparison of |
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(module_name
)
load_module("pgsql");
Table 3.346. Arguments and Return Values for load_module()
Argument Type | Return Type | Description |
---|---|---|
String | String | Loads the module with the given name if possible, otherwise throws an exception. This function returns no value. |
Table 3.347. 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(arg
)
$str = makeBase64String($bin);
Table 3.348. Arguments and Return Values for makeBase64String()
Argument Type | Return Type | Description |
---|---|---|
Binary or String | String | Returns a base64-encoded representation of a binary object or a string. |
This function does not throw any exceptions.
Returns a hex-encoded representation of a binary object or a string (see also makeBase64String()).
makeHexString(arg
)
$str = makeHexString($bin);
Table 3.349. Arguments and Return Values for makeHexString()
Argument Type | Return Type | Description |
---|---|---|
Binary or String | String | Returns a hex-encoded representation of a binary object or a string. |
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, [callback]
)
max(elem1, elem2[, ...]
)
$max = max($complex_list, \callback_function());
$max = max(1, 2, 3, 4);
Table 3.350. Arguments and Return Values for max()
Argument Type | Return Type | Description |
---|---|---|
| Any | 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. |
| Any | 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, [callback]
)
min(elem1, elem2[, ...]
)
$min = min($complex_list, \callback_function());
$min = min(1, 10, 2, 3);
Table 3.351. Arguments and Return Values for min()
Argument Type | Return Type | Description |
---|---|---|
| Any | 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. |
| Any | Finds the minimum value in the list of simple data types passed as top-level arguments to the function and returns that value. No closure or call 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).
Adds the text passed to the current program's code.
parse(code_string, label_string
)
parse($code, "label");
Table 3.352. Arguments and Return Values for parse()
Argument Type | Return Type | Description |
---|---|---|
String | n/a | Parses the string passed and adds the code to the current program. |
Parses a base64 encoded string and returns the binary object (see also parseHexString()).
parseBase64String(base64_string
)
$bin = parseBase64String($base64_string);
Table 3.354. Arguments and Return Values for parseBase64String()
Argument Type | Return Type | Description |
---|---|---|
String | Binary | Parses a base64 encoded string and returns the binary object. If anything is passed other than a string as an argument, no action is taken and the function returns NOTHING. |
Table 3.355. 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(datasource_string
)
$hash = parseDatasource($ds_string);
Table 3.356. Arguments and Return Values for parseDatasource()
Argument Type | Return Type | Description |
---|---|---|
String | Hash | Returns a hash of the components of a datasource string. A datasource string has the following structure: |
Table 3.357. Exceptions Thrown by parseDatasource()
err | desc |
---|---|
| A syntax error occurred parsing the datasource string (missing field, unexpected character, etc). |
Table 3.358. 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 |
Parses a hex-encoded string and returns the binary object (see also parseBase64String()).
parseHexString(hex_string
)
$bin = parseHexString($hex_string);
Table 3.359. Arguments and Return Values for parseHexString()
Argument Type | Return Type | Description |
---|---|---|
String | Binary | Parses a hex-encoded string and returns the binary object. If anything is passed other than a string as an argument, no action is taken and the function returns NOTHING. |
Table 3.360. 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
parseURL(url_string
)
$hash = parseURL($url_string);
Table 3.361. Arguments and Return Values for parseURL()
Argument Type | Return Type | Description |
---|---|---|
String | Hash | Parses a URL string and returns a hash of the components. URLs have the format: |
This function does not throw any exceptions.
Returns a random integer number (uses the C library function random()
to generate the number).
rand()
$num = rand();
Table 3.362. Arguments and Return Values for rand()
Argument Type | Return Type | Description |
---|---|---|
n/a | Integer | A random integer number is returned. See srand() for a function to seed the random number generator. |
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(signal
)
remove_signal_handler(SIGINT);
Not available with PO_NO_PROCESS_CONTROL
Table 3.363. Arguments and Return Values for remove_signal_handler()
Argument Type | Return Type | Description |
---|---|---|
Integer | n/a | The signal number to process. |
This function does not throw any exceptions.
Reverses a string or a list (depending on the argument) and returns the new string or list. Works properly on UTF-8 strings with multi-byte characters as well.
reverse(string_or_list
)
$str = reverse("ABCDEF"); # returns "FEDCBA"
Table 3.364. Arguments and Return Values for reverse()
Argument Type | Return Type | Description |
---|---|---|
List | List | The list with its elements reversed. |
String | String | The string with its characters reversed. |
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(signal, closure | call_reference
)
set_signal_handler(SIGINT, \signal_handler());
Not available with PO_NO_PROCESS_CONTROL
Table 3.365. Arguments and Return Values for set_signal_handler()
Argument Type | Return Type | Description |
---|---|---|
Integer, closure | Call Reference | n/a | The signal number to process and reference to the code to execute when the signal is raised. |
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, [callback]
)
$list = sort($complex_list, \callback());
Table 3.366. Arguments and Return Values for sort()
Argument Type | Return Type | Description |
---|---|---|
List, [closure | Call Reference] | List | Sorts the list passed in ascending order and returns the sorted list. The list must be made up of basic data types unless a closure or call reference is used. |
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, [callback]
)
$list = sortDescending($complex_list, \callback());
Table 3.367. Arguments and Return Values for sortDescending()
Argument Type | Return Type | Description |
---|---|---|
List, [closure | Call Reference] | List | Sorts the list passed in descending order and returns the sorted list. The list must be made up of basic data types unless a closure or call reference is used. |
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, [callback]
)
$list = sortDescendingStable($complex_list, \callback());
Table 3.368. Arguments and Return Values for sortDescendingStable()
Argument Type | Return Type | Description |
---|---|---|
List, [closure | Call Reference] | List | Sorts the list passed in descending order and returns the sorted list. The list must be made up of basic data types unless a closure or call reference is used. |
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, [callback]
)
$list = sortStable($complex_list, \callback());
Table 3.369. Arguments and Return Values for sortStable()
Argument Type | Return Type | Description |
---|---|---|
List, [closure | Call Reference] | List | Sorts the list passed in ascending order and returns the sorted list. The list must be made up of basic data types unless a closure or call reference is used. |
This function does not throw any exceptions.
Seeds the random number generator with the integer passed (uses the C library function srandom()
).
srand(integer
)
srand(now()); # seeds with current time
Table 3.370. Arguments and Return Values for srand()
Argument Type | Return Type | Description |
---|---|---|
Integer | n/a | Seeds the random number generator with the integer passed. See rand() for a function to get a random number. |
This function does not throw any exceptions.
Returns an integer corresponding to the string passed with the possibility to specify the base (default base 10).
strtoint(string, [base]
)
$int = strtoint("41", 8);
Table 3.371. Arguments and Return Values for strtoint()
Argument Type |
Return Type |
Description |
---|---|---|
String |
Integer |
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()
delete_all_thread_data();
Not available with PO_NO_THREAD_CONTROL
Table 3.372. 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(key_string, [key_string, ...]
)
delete_thread_data("key1", "key2");
Not available with PO_NO_THREAD_CONTROL
Table 3.373. Arguments and Return Values for delete_thread_data()
Arguments | Return Values | Description |
---|---|---|
String, [String ...] | n/a | Deletes the data associated to one or more keys in the thread-local data hash. |
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()
$hash = get_all_thread_data();
Not available with PO_NO_THREAD_CONTROL
Table 3.374. Arguments and Return Values for get_all_thread_data()
Argument Type | Return Type | Description |
---|---|---|
n/a | Hash | 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()
$hash = getAllThreadCallStacks();
Not available with PO_NO_THREAD_CONTROL
Table 3.375. Arguments and Return Values for getAllThreadCallStacks()
Argument Type | Return Type | Description |
---|---|---|
n/a | Hash | 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.376. 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(key_string
)
$data = get_thread_data("key1");
Not available with PO_NO_THREAD_CONTROL
Table 3.377. Arguments and Return Values for get_thread_data()
Argument Type | Return Type | Description |
---|---|---|
String | depends on key | Returns the value of the thread-local data attached to the key passed. |
This function does not throw any exceptions.
Returns the Qore thread ID (TID) of the current thread.
gettid()
$tid = gettid();
Table 3.378. Arguments and Return Values for gettid()
Argument Type | Return Type | Description |
---|---|---|
n/a | Integer | 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()
$num = num_threads();
Table 3.379. Arguments and Return Values for num_threads()
Argument Type | Return Type | Description |
---|---|---|
n/a | Integer | 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(key_string, [key_string, ...]
)
remove_thread_data("key1", "key2");
Not available with PO_NO_THREAD_CONTROL
Table 3.380. Arguments and Return Values for remove_thread_data()
Arguments | Return Values | Description |
---|---|---|
String, [String ...] | n/a | Removes the data associated to one or more keys in the thread-local data hash. |
This function does not throw any exceptions.
Saves the data passed against the key passed in thread-local storage.
save_thread_data(key_string, value_expression
)
save_thread_data("key1", $value);
Not available with PO_NO_THREAD_CONTROL
Table 3.381. Arguments and Return Values for save_thread_data()
Argument Type | Return Type | Description |
---|---|---|
String, Any | n/a | Saves the data passed against the key passed in thread-local storage. |
This function does not throw any exceptions.
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()
$list = thread_list();
Table 3.382. Arguments and Return Values for thread_list()
Argument Type | Return Type | Description |
---|---|---|
n/a | List | 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()
try { throwThreadResourceExceptions(); } catch ($ex) { # ... log or handle exceptions }
Not available with PO_NO_THREAD_CONTROL
Table 3.383. 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, [encoding]
)
$xml = makeFormattedXMLFragment($hash);
Table 3.384. Arguments and Return Values for makeFormattedXMLFragment()
Argument Type | Return Type | Description |
---|---|---|
Hash, [String] | String | 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. |
Table 3.385. 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.
makeFormattedXMLRPCCallString(method_name, [arguments ...]
)
$xml = makeFormattedXMLRPCCallString("method.name", $arg1, $arg2);
Table 3.386. Arguments and Return Values for makeFormattedXMLRPCCallString()
Argument Type | Return Type | Description |
---|---|---|
String, [Any ...] | String | 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.387. 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.
makeFormattedXMLRPCCallStringWithEncoding(encoding_name, method_name, [arguments ...]
)
$xml = makeFormattedXMLRPCCallStringWithEncoding("ISO-8859-1", "method.name", $arg1, $arg2);
Table 3.388. Arguments and Return Values for makeFormattedXMLRPCCallStringWithEncoding()
Argument Type | Return Type | Description |
---|---|---|
String, String, [Any ...] | String | Serializes the arguments into an XML string in XML-RPC call format with whitespace formatting. The encoding of the resulting string will be the encoding given by the first argument. |
Table 3.389. 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.
makeFormattedXMLRPCCallStringArgs(method_name, [arg_list]
)
$xml = makeFormattedXMLRPCCallStringArgs("method.name", $arg_list);
Table 3.390. Arguments and Return Values for makeFormattedXMLCallStringArgs()
Argument Type | Return Type | Description |
---|---|---|
String, [List] | String | 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.391. 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.
makeFormattedXMLRPCCallStringArgsWithEncoding(encoding_name, method_name, [arg_list]
)
$xml = makeFormattedXMLRPCCallStringArgsWithEncoding("ISO-8859-1", "method.name", $arg_list);
Table 3.392. Arguments and Return Values for makeFormattedXMLCallStringArgsWithEncoding()
Argument Type | Return Type | Description |
---|---|---|
String, String, [List] | String | 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.393. 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.
makeFormattedXMLRPCFaultResponseString(error_code, error_string
)
$xml = makeFormattedXMLRPCFaultResponseString(10, "oh no, big error");
Table 3.394. Arguments and Return Values for makeFormattedXMLRPCFaultResponseString()
Argument Type | Return Type | Description |
---|---|---|
Integer, String | String | Serializes the arguments into an XML string formatted for an XML-RPC fault response with whitespace formatting. The encoding of the resulting string will always be the default encoding. |
Table 3.395. 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.
makeFormattedXMLRPCFaultResponseStringWithEncoding(encoding_name, error_code, error_string
)
$xml = makeFormattedXMLRPCFaultResponseStringWithEncoding("ISO-8859-2", 10, "oh no, big error");
Table 3.396. Arguments and Return Values for makeFormattedXMLRPCFaultResponseStringWithEncoding()
Argument Type | Return Type | Description |
---|---|---|
String, Integer, String | String | Serializes the arguments into an XML string formatted for an XML-RPC fault response with whitespace formatting. The encoding of the resulting string will be the encoding given by the first argument. |
Table 3.397. 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.
makeFormattedXMLRPCResponseString(any
)
$xml = makeFormattedXMLRPCResponseString($value);
Table 3.398. Arguments and Return Values for makeFormattedXMLRPCResponseString()
Argument Type | Return Type | Description |
---|---|---|
Any | String | 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.399. 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.
makeFormattedXMLRPCResponseStringWithEncoding(encoding_name, any
)
$xml = makeFormattedXMLRPCResponseStringWithEncoding("ISO-8859-1", $value);
Table 3.400. Arguments and Return Values for makeFormattedXMLRPCResponseStringWithEncoding()
Argument Type | Return Type | Description |
---|---|---|
Any | String | Serializes the arguments into an XML string formatted for an XML-RPC response with whitespace formatting>. The encoding of the resulting string is given by the first argument. |
Table 3.401. 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.
makeFormattedXMLRPCValueString(any
)
$xml = makeFormattedXMLRPCValueString($value);
Table 3.402. Arguments and Return Values for makeFormattedXMLRPCValueString()
Argument Type | Return Type | Description |
---|---|---|
Any | String | Serializes the arguments into an XML string in XML-RPC value format with whitespace formatting. The encoding of the resulting string will always be the default encoding. |
Table 3.403. 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, [encoding]
)
makeFormattedXMLString(string, hash, [encoding]
)
$xml = makeFormattedXMLString($hash);
$xml = makeFormattedXMLString("key", $hash);
Table 3.404. Arguments and Return Values for makeFormattedXMLString()
Argument Type | Return Type | Description |
---|---|---|
Hash, [String] | String | 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. |
String, Hash, [String] | String | 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. |
Table 3.405. Exceptions Thrown by makeFormattedXMLRPCValueString()
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, [encoding]
)
$xml = makeXMLFragment($hash);
Table 3.406. Arguments and Return Values for makeXMLFragment()
Argument Type | Return Type | Description |
---|---|---|
Hash, [String] | String | 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. |
Table 3.407. 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.
makeXMLRPCCallString(method_name, [arguments ...]
)
$xml = makeXMLRPCCallString("method.name", $arg1, $arg2);
Table 3.408. Arguments and Return Values for makeXMLRPCCallString()
Argument Type | Return Type | Description |
---|---|---|
String, [Any ...] | String | 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.409. 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.
makeXMLRPCCallStringWithEncoding(encoding_name, method_name, [arguments ...]
)
$xml = makeXMLRPCCallStringWithEncoding("ISO-8859-2", "method.name", $arg1, $arg2);
Table 3.410. Arguments and Return Values for makeXMLRPCCallStringWithEncoding()
Argument Type | Return Type | Description |
---|---|---|
String, String, [Any ...] | String | Serializes the arguments into an XML string in XML-RPC call format without whitespace formatting. The encoding of the resulting string will correspond to the encoding given as the first argument. |
Table 3.411. 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.
makeXMLRPCCallStringArgs(method_name, [arg_list]
)
$xml = makeXMLRPCCallStringArgs("method.name", $arg_list);
Table 3.412. Arguments and Return Values for makeXMLCallStringArgs()
Argument Type | Return Type | Description |
---|---|---|
String, [List] | String | 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.413. 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.
makeXMLRPCCallStringArgsWithEncoding(encoding_name, method_name, [arg_list]
)
$xml = makeXMLRPCCallStringArgsWithEncoding("ISO-8859-2", "method.name", $arg_list);
Table 3.414. Arguments and Return Values for makeXMLCallStringArgsWithEncoding()
Argument Type | Return Type | Description |
---|---|---|
String, String, [List] | String | 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.415. 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.
makeXMLRPCFaultResponseString(error_code, error_string
)
$xml = makeXMLRPCFaultResponseString(10, "oh no, an error occured");
Table 3.416. Arguments and Return Values for makeXMLRPCFaultResponseString()
Argument Type | Return Type | Description |
---|---|---|
Integer, String | String | Serializes the arguments into an XML string formatted for an XML-RPC fault response without whitespace formatting. The encoding of the resulting string will always be the encoding of the fault string (2nd argument). |
Table 3.417. Exceptions Thrown by makeXMLRPCCallStringArgs()
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.
makeXMLRPCFaultResponseStringWithEncoding(encoding_string, error_code, error_string
)
$xml = makeXMLRPCFaultResponseStringWithEncoding("ISO-8859-2", 10, "oh no, an error occured");
Table 3.418. Arguments and Return Values for makeXMLRPCFaultResponseStringWithEncoding()
Argument Type | Return Type | Description |
---|---|---|
String, Integer, String | String | Serializes the arguments into an XML string formatted for an XML-RPC fault response without whitespace formatting. The encoding of the resulting string will correspond to the encoding given as the first argument. |
Table 3.419. Exceptions Thrown by makeXMLRPCCallStringArgsWithEncoding()
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.
makeXMLRPCResponseString(any
)
$xml = makeXMLRPCResponseString($response);
Table 3.420. Arguments and Return Values for makeXMLRPCResponseString()
Argument Type | Return Type | Description |
---|---|---|
Any | String | 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.421. 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.
makeXMLRPCResponseStringWithEncoding(encoding_name, any
)
$xml = makeXMLRPCResponseStringWithEncoding("ISO-8859-2", $response);
Table 3.422. Arguments and Return Values for makeXMLRPCResponseStringWithEncoding()
Argument Type | Return Type | Description |
---|---|---|
String, Any | String | Serializes the arguments into an XML string formatted for an XML-RPC response without whitespace formatting>. The encoding of the resulting string will correspond to the first argument. |
Table 3.423. 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.
makeXMLRPCValueString(any
)
$xml = makeXMLRPCValueString($value);
Table 3.424. Arguments and Return Values for makeXMLRPCValueString()
Argument Type | Return Type | Description |
---|---|---|
Any | String | 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.425. 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, [encoding]
)
makeXMLString(string, hash, [encoding]
)
$xml = makeXMLString($hash);
$xml = makeXMLString("key", $hash);
Table 3.426. Arguments and Return Values for makeXMLString()
Argument Type | Return Type | Description |
---|---|---|
Hash, [String] | String | 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. |
String, Hash, [String] | String | 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. |
Table 3.427. Exceptions Thrown by makeXMLRPCValueString()
err | desc |
---|---|
| An error occurred serializing the Qore data to an XML string. |
| Incorrect arguments passed. |
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(xml_string, [output_encoding]
)
$hash = parseXMLAsData($xml);
Table 3.428. Arguments and Return Values for parseXMLAsData()
Argument Type | Return Type | Description |
---|---|---|
String, [String] | Hash | Parses an XML string and returns a Qore hash structure. |
Table 3.429. 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(xml_string, relaxng_string, [output_encoding]
)
$hash = parseXMLAsDataWithRelaxNG($xml, $rng);
Table 3.430. Arguments and Return Values for parseXMLAsDataWithRelaxNG()
Argument Type | Return Type | Description |
---|---|---|
String, String, [String] | Hash | Parses an XML string (1st argument), validates against the RelaxNG string (2nd argument), and returns a Qore hash structure. |
Table 3.431. 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(xml_string, xsd_string, [output_encoding]
)
$hash = parseXMLAsDataWithSchema($xml, $xsd);
Table 3.432. Arguments and Return Values for parseXMLAsDataWithSchema()
Argument Type | Return Type | Description |
---|---|---|
String, String, [String] | Hash | Parses an XML string (1st argument), validates against the XSD string (2nd argument), and returns a Qore hash structure. |
Table 3.433. 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 |
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.
For a similar function collapsing all duplicate XML elements into a list in the Qore hash, see parseXMLAsData().
parseXML(xml_string, [output_encoding]
)
$hash = parseXML($xml);
Table 3.434. Arguments and Return Values for parseXML()
Argument Type | Return Type | Description |
---|---|---|
String, [String] | Hash | Parses an XML string and returns a Qore hash structure. |
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.
For a similar function collapsing all duplicate XML elements into a list in the Qore hash, see parseXMLAsDataWithRelaxNG(). 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(xml_string, relaxng_string, [output_encoding]
)
$hash = parseXMLWithRelaxNG($xml, $rng);
Table 3.436. Arguments and Return Values for parseXMLWithRelaxNG()
Argument Type | Return Type | Description |
---|---|---|
String, String, [String] | Hash | Parses an XML string (1st argument), validates against the RelaxNG schema string (2nd argument), and returns a Qore hash structure. |
Table 3.437. 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.
For a similar function collapsing all duplicate XML elements into a list in the Qore hash, see parseXMLAsDataWithSchema(). 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(xml_string, xsd_string, [output_encoding]
)
$hash = parseXMLWithSchema($xml, $xsd);
Table 3.438. Arguments and Return Values for parseXMLWithSchema()
Argument Type | Return Type | Description |
---|---|---|
String, String, [String] | Hash | Parses an XML string (1st argument), validates against the XSD string (2nd argument), and returns a Qore hash structure. |
Table 3.439. 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 |
Deserializies an XML-RPC call string, returning a Qore data structure representing the call information.
parseXMLRPCCall(xmlrpc_call_string, [output_encoding]
)
$hash = parseXMLRPCCall($xml);
Table 3.440. Arguments and Return Values for parseXMLRPCCall()
Argument Type | Return Type | Description |
---|---|---|
String, [String] | Hash | Deserializies an XML-RPC call string, returning a Qore data structure representing the call information. The hash will have the following keys: methodName, params |
Table 3.441. 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(xmlrpc_response_string, [output_encoding]
)
$hash = parseXMLRPCResponse($xml);
Table 3.442. Arguments and Return Values for parseXMLRPCResponse()
Argument Type | Return Type | Description |
---|---|---|
String, [String] | Hash | 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. |
Table 3.443. 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(xmlrpc_value_string, [output_encoding]
)
$hash = parseXMLRPCValue($xml);
Table 3.444. Arguments and Return Values for parseXMLRPCValue()
Argument Type | Return Type | Description |
---|---|---|
String, [String] | Hash | Deserializies an XML-RPC value string, returning Qore data representing the value data. |
Table 3.445. Exceptions Thrown by parseXMLRPCResponse()
err | desc |
---|---|
| Error parsing an XML-RPC value node. |
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.
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 Type, [Encoding]
)
$json = makeJSONString($value);
Table 3.446. Arguments and Return Values for makeJSONString()
Argument Type |
Return Type |
Description |
---|---|---|
Any Type, [Encoding] |
String |
Serializes qore data into a JSON string, without any line breaks. |
Table 3.447. Exceptions Thrown by makeJSONString()
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 Type, [Encoding]
)
$json = makeFormattedJSONString($value);
Table 3.448. Arguments and Return Values for makeFormattedJSONString()
Argument Type |
Return Type |
Description |
---|---|---|
Any Type, [Encoding] |
String |
Serializes qore data into a JSON string, formatted with line breaks for easier readability. |
Table 3.449. Exceptions Thrown by makeFormattedJSONString()
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(method_name, [json_version], [id], [arguments]
)
$json = makeJSONRPCRequestString("method_name", "1.1", $id, $request_data);
Table 3.450. Arguments and Return Values for makeJSONRPCRequestString()
Argument Type |
Return Type |
Description |
---|---|---|
Method_name, [json_version], [id], [arguments] |
String |
Creates a JSON-RPC request string from the parameters passed, without any line breaks. |
Table 3.451. Exceptions Thrown by makeJSONRPCRequestString()
err | desc |
---|---|
| Error serializing to JSON string. |
| missing method name as first parameter. |
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(method_name, [json_version], [id], [arguments]
)
$json = makeFormattedJSONRPCRequestString("method_name", "1.1", $id, $request_data);
Table 3.452. Arguments and Return Values for makeFormattedJSONRPCRequestString()
Argument Type |
Return Type |
Description |
---|---|---|
Method_name, [json_version], [id], [arguments] |
String |
Creates a JSON-RPC request string from the parameters passed, formatted with line breaks for easier readability. |
Table 3.453. 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, 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([json_version], [id], [response]
)
$json = makeJSONRPCResponseString("1.1", $id, $response);
Table 3.454. Arguments and Return Values for makeJSONRPCResponseString()
Argument Type |
Return Type |
Description |
---|---|---|
[json_version], [id], [response] |
String |
Creates a JSON-RPC response string from the parameters passed, without any line breaks. |
Table 3.455. Exceptions Thrown by makeJSONRPCResponseString()
err | desc |
---|---|
| Error serializing to JSON string. |
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([json_version], [id], [response]
)
$json = makeFormattedJSONRPCResponseString("1.1", $id, $response);
Table 3.456. Arguments and Return Values for makeFormattedJSONRPCResponseString()
Argument Type |
Return Type |
Description |
---|---|---|
[json_version], [id], [response] |
String |
Creates a JSON-RPC response string from the parameters passed, formatted with line breaks for easier readability. |
Table 3.457. Exceptions Thrown by makeFormattedJSONRPCResponseString()
err | desc |
---|---|
| Error serializing to JSON string. |
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([json_version], [id], [response]
)
$json = makeJSONRPCErrorString("1.1", $id, $response);
Table 3.458. Arguments and Return Values for makeJSONRPCErrorString()
Argument Type |
Return Type |
Description |
---|---|---|
[json_version], [id], [response] |
String |
Creates a generic JSON-RPC error response string from the parameters passed, without any line breaks. |
Table 3.459. Exceptions Thrown by makeJSONRPCErrorString()
err | desc |
---|---|
| Error serializing to JSON string. |
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([json_version], [id], [response]
)
$json = makeFormattedJSONRPCErrorString("1.1", $id, $response);
Table 3.460. Arguments and Return Values for makeFormattedJSONRPCErrorString()
Argument Type |
Return Type |
Description |
---|---|---|
[json_version], [id], [response] |
String |
Creates a generic JSON-RPC error response string from the parameters passed, formatted with line breaks for easier readability. |
Table 3.461. Exceptions Thrown by makeFormattedJSONRPCErrorString()
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(code, message, [[id], [error]
)
$json = makeJSONRPC11ErrorString(200, $msg, $id, $error);
Table 3.462. Arguments and Return Values for makeJSONRPC11ErrorString()
Argument Type |
Return Type |
Description |
---|---|---|
Code, Error_message, [id], [error_response] |
String |
Creates a JSON-RPC 1.1 error response string from the parameters passed, formatted with line breaks for easier readability. |
Table 3.463. Exceptions Thrown by makeJSONRPC11ErrorString()
err | desc |
---|---|
| Error serializing to JSON string. |
| Invalid argument to method. |
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(code, error_message, [id], [error_response]
)
$json = makeFormattedJSONRPC11ErrorString(200, $msg, $id, $error);
Table 3.464. Arguments and Return Values for makeFormattedJSONRPC11ErrorString()
Argument Type |
Return Type |
Description |
---|---|---|
Code, Error_message, [id], [error_response] |
String |
Creates a JSON-RPC 1.1 error response string from the parameters passed, formatted with line breaks for easier readability. |
Table 3.465. Exceptions Thrown by makeFormattedJSONRPC11ErrorString()
err | desc |
---|---|
| Error serializing to JSON string. |
| Invalid argument to method. |
Parses a JSON string and returns the corresponding qore data structure.
parseJSON(json_string
)
$data = parseJSON($json_string);
Table 3.466. Arguments and Return Values for parseJSON()
Argument Type |
Return Type |
Description |
---|---|---|
Json_string |
Qore Data |
Parses a JSON string and returns the corresponding qore data structure. |
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.468. 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.469. 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.470. 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. | |
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 | 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. Library Options
Name | Type | Description |
---|---|---|
| Boolean | Indicates if the Qore library supports fast atomic reference counting |
| Boolean | Indicates if protection against stack overruns is provided |
| Boolean | Indicates if active thread stack tracing has been enabled as a debugging option and if the getAllThreadCallStacks() function is available. |
| Boolean | Indicates if the round() function is available. |
| Boolean | Indicates if the timegm() function is available. |
| Boolean | Indicates if the seteuid() function is available. |
| Boolean | Indicates if the setegid() function is available. |
| Boolean | Indicates if parseXMLWithRelaxNG() and XmlReader::relaxNGValidate() are available. |
| Boolean | Indicates if parseXMLWithSchema() and XmlReader::schemaValidate() are available. |
| Boolean | 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. |
| Boolean | 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. |
| Boolean | 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. |
| Boolean | 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. |
| Boolean | 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. |
| Boolean | 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. |
Table 4.4. Boolean Constants in the Qore Namespace
Name | Type | Description |
---|---|---|
| Boolean | True |
| Boolean | False |
Table 4.6. 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.7. Event Map Hash Constant
Key | String Value |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Table 4.9. Network Address Type Constants
Name | Description |
---|---|
| Designates an IPv4 network addresses. |
| Designates an IPv6 network addresses. |
| Designates a local socket file name (interchangeable with |
| POSIX synonym for |
Table 4.10. 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.11. 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.12. 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.13. 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.14. Terminal Attributes Control Character Constants
Name | Special Character | Default Value |
---|---|---|
|
| ^D |
|
| _POSIX_VDISABLE |
|
| _POSIX_VDISABLE |
|
| ^? `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.15. X506_VerificationReasons Hash
Key | Value |
---|---|
|
|
| Unable to get issuer certificate |
| Unable to get certificate CRL |
| Unable to decrypt certificate's signature. This means that the actual signature value could not be determined rather than it not matching the expected value; this is only meaningful for RSA |
| Unable to decrypt CRL's signature |
| Unable to decode issuer public key (SubjectPublicKeyInfo) |
| Certificate signature failure; the signature of the certificate is invalid |
| CRL signature failure; the signature of the certificate is invalid |
| Certificate is not yet valid |
| Certificate has expired |
| CRL is not yet valid |
| CRL has expired |
| Format error in certificate's notBefore field (invalid time) |
| Format error in certificate's notAfter field (invalid time) |
| Format error in CRL's lastUpdate field (invalid time) |
| Format error in CRL's nextUpdate field (invalid time) |
| Out of memory error |
| Certificate is self-signed and cannot be found in the trusted list |
| Self signed certificate in certificate chain |
| Unable to get local issuer certificate. This normally means the list of trusted certificates is not complete |
| Unable to verify the first certificate |
| Certificate chain too long |
| Certificate has been revoked |
| Invalid CA certificate |
| The basicConstraints pathlength parameter has been exceeded |
| The certificate cannot be used for the specified purpose |
| Root CA is not marked as trusted for the specified purpose |
| Root CA is marked to reject the specified purpose |
| The current candidate issuer certificate was rejected because its subject name did not match the issuer name of the current certificate |
| The current candidate issuer certificate was rejected because its subject key identifier was present and did not match the authority key identifier of the current certificate |
| Issuer name and serial number of candidate certificate do not match the authority key identifier of the current certificate |
| The keyUsage extension does not permit certificate signing |
| Verification failure |
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.
Table 4.16. 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 arugment 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.17. 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.18. Error Constants in the Err Namespace
Name | Type | Description |
---|---|---|
| Integer | System-dependent integer ERRNO constants (ex: ENOMEM, etc) |
Table 4.19. Exception Constants in the Qore Namespace
Name | Type | Description |
---|---|---|
| String | Exception Type System: used for system exceptions. |
| String | Exception Type User: used for user exceptions (thrown using the throw statement. |
| Integer | Call Type User: used for user function/method calls in a call stack. |
| Integer | Call Type Builtin: used for builtin function/method calls in a call stack. |
| Integer | Call Type New Thread: used in a call stack when a new thread is started with the background expression. |
| Integer | Call Type Rethrow: a marker for a rethrown exception in a call stack. |
Table 4.20. Regular Expression Option Constants in the Qore Namespace
Name | Type and Value | Description |
---|---|---|
| Integer: 1 | Ignores case when matching regular expressions, equivalent to /i |
| Integer: 2 | makes start-of-line (^) or end-of-line ($) match after or before any newline in the subject string, equivalent to /m |
| Integer: 4 | makes a dot (.) match a newline character, equivalent to /s |
| Integer: 8 | 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.
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.22. 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.23. 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 | |
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. | |
Y | Reads a certain number of bytes from the file within an optional timeout period and returns binary data. | |
Y | Reads a 1-byte signed integer from the file. | |
Y | Reads a 2-byte signed integer from the file in big-endian format. | |
Y | Reads a 4-byte signed integer from the file in big-endian format. | |
Y | Reads an 8-byte signed integer from the file in big-endian format. | |
Y | Reads a 2-byte signed integer from the file in little-endian format. | |
Y | Reads a 4-byte signed integer from the file in little-endian format. | |
Y | Reads an 8-byte signed integer from the file in little-endian format. | |
Y | Reads a 1-byte unsigned integer from the file. | |
Y | Reads a 2-byte unsigned integer from the file in big-endian format. | |
Y | Reads a 4-byte unsigned integer from the file in big-endian format. | |
Y | Reads a 2-byte unsigned integer from the file in little-endian format. | |
Y | Reads a 4-byte unsigned integer from the file in little-endian format. | |
Y | Read a certain amount of data and return a binary object. | |
Y | Reads until an EOL marker is found | |
N | Sets the character encoding for the file. | |
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. |
Table 4.24. File Constants in the Qore Namespace
Name | Description |
---|---|
| Open the file read-only. |
| Open the file write-only. |
| Create the file if it doesn't exist. |
| Open the file in append mode. |
| Open for reading and writing. |
| Truncate the size to zero. |
Table 4.25. File Locking Constants in the Qore Namespace
Name | Description |
---|---|
| Use for read-only locking. |
| Use for exclusive write locking. |
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).
new File([string:encoding]
)
$f = new File("ISO-8859-1"); # specify ISO-8859-1 encoding for the file
Table 4.26. Arguments for File::constructor()
Argument | Type | Description |
---|---|---|
| String | The character encoding for the file. Any strings written to the file will be converted to this character encoding if necessary. |
Table 4.27. Return Value for File::constructor()
Return Type | Description |
---|---|
Object | The File object created. |
Closes the file if it's open and destroys the File object.
delete lvalue
delete $f;
EVENT_CHANNEL_CLOSED, EVENT_DELETED
EVENT_CHANNEL_CLOSED, EVENT_DELETED
Creates a new File object with the same character encoding specification as the original.
File::copy()
$f1 = $f.copy();
Table 4.29. Return Value for File::copy()
Return Type | Description |
---|---|
n/a | The new File object created with the same character encoding specification as the original object. |
Changes the file's user and group owner (if the user has sufficient permissions to do so).
File::chown(user_id, group_id
)
$f.chown(0, 0);
Table 4.30. Arguments for File::chown()
Argument | Type | Description |
---|---|---|
| Integer | The user id of the user to change to. |
| Integer | The group id of the user to change to. |
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()
$f.close();
EVENT_CHANNEL_CLOSED
Table 4.34. Return Value for File::close()
Return Type | Description |
---|---|
Integer | 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:format, [args ...]
)
$f.f_printf("%5s\n", "long string"); # will print "long \n", respecting the 5-character field width
Table 4.35. Arguments for File::f_printf()
Argument | Type | Description |
---|---|---|
| String | The format string, see String Formatting for a specification. |
| Any | The remainder of the arguments are arguments to the format string. |
Table 4.36. Return Value for File::f_printf()
Return Type | Description |
---|---|
Integer | 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(format_string, [arg_list]
)
$f.f_vprintf("%5s %3d\n", ("a long string", 5000)); # outputs "a lon 500", truncating output
Table 4.38. Arguments for File::f_vprintf()
Argument | Type | Description |
---|---|---|
| String | The format string, see String Formatting for a specification. |
| List | This list will be used as the argument list or the format string. |
Table 4.39. Return Value for File::f_vprintf()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Reads one character from the file and returns it as a one-character string.
File::getchar()
$char = $f.getchar();
Table 4.41. Arguments for File::getchar()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.42. Return Value for File::getchar()
Return Type | Description |
---|---|
String | The single character read from the file. |
Returns the character encoding for the file.
File::getCharset()
$encoding = $f.getCharset();
Table 4.43. Arguments for File::getCharset()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.44. Return Value for File::getCharset()
Return Type | Description |
---|---|
String | 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()
my $hash = $f.getLockInfo();
Table 4.45. Arguments for File::getLockInfo()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.46. Return Value for File::getLockInfo()
Return Type | Description |
---|---|
Hash | 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. |
Table 4.47. 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()
$pos = $f.getPos();
Table 4.48. Arguments for File::getPos()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.49. Return Value for File::getPos()
Return Type | Description |
---|---|
Integer | 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
)
my $termios = new TermIOS(); $f.getTerminalAttributes($termios);
Table 4.50. Arguments for File::getTerminalAttributes()
Argument | Type | Description |
---|---|---|
| The method writes the current terminal attributes for the file to the object passed. |
Table 4.51. Return Value for File::getTerminalAttributes()
Return Type | Description |
---|---|
Integer | Always returns 0; if an error is encountered, an exception is raised. |
Table 4.52. 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([timeout_ms]
)
$bool = $file.isDataAvailable(0); # returns True if data is available now
Table 4.53. Arguments for File::isDataAvailable()
Argument | Type | Description |
---|---|---|
| Integer or Relative Date/Time | An optional timeout in milliseconds (1/1000 second). If no timeout is given, the method assumes a timeout of zero and returns immediately. |
Table 4.54. Return Values for File::isDataAvailable()
Return Type | Description |
---|---|
Boolean | True if data becomes available for reading from the file within the timeout period, False if not. |
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(type, [start, [len]]
)
# 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.56. Arguments for File::lock()
Argument | Type | Description |
---|---|---|
| Integer | Type of lock (or unlock), see File locking constants. |
| Integer | Start byte for lock, 0 is the default (start of file). |
| Integer | Length in bytes for range to lock, 0 is the default (rest of file). |
Table 4.57. Return Value for File::lock()
Return Type | Description |
---|---|
Integer | Returns 0 for success, EACCES if the lock would block (only in the case that the lock would block is no exception thrown and EACCES returned). |
Table 4.58. 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(type, [start, [len]]
)
# 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.59. Arguments for File::lockBlocking()
Argument | Type | Description |
---|---|---|
| Integer | Type of lock (or unlock), see File locking constants. |
| Integer | Start byte for lock, 0 is the default (start of file). |
| Integer | Length in bytes for range to lock, 0 is the default (rest of file). |
Table 4.60. 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.61. 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:format, [args ...]
)
$f.printf("%5s\n", "hello there"); # outputs "hello there\n", exceeding field width
EVENT_DATA_WRITTEN
Table 4.62. Arguments for File::printf()
Argument | Type | Description |
---|---|---|
| String | The format string, see String Formatting for a specification. |
| Any | The remainder of the arguments are arguments to the format string. |
Table 4.63. Return Value for File::printf()
Return Type | Description |
---|---|
Integer | 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.
For a version of this method that throws an exception when errors occur opening the file, see File::open2().
File::open(string:filename, [integer:flags, [integer:mode, [string:charset]]]
)
# 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");
EVENT_OPEN_FILE, EVENT_FILE_OPENED
Table 4.65. Arguments for File::open()
Argument | Type | Description |
---|---|---|
| String | The Filename of the file. |
| Integer | Flags that determine the way the file is accessed, see File Constants for more information. If this argument is not given, O_RDONLY will be used as the default value. |
| Integer | Permission bits for when the file is to be created (default: 0777) |
| String | The name of the default character encoding for this file. |
Table 4.66. Return Values for File::open()
Return Type | Description |
---|---|
Integer | 0 = no error, -1 = see errno() and strerror() for the error message |
Table 4.67. 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.
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:filename, [integer:flags, [integer:mode, [string:charset]]]
)
# 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");
EVENT_OPEN_FILE, EVENT_FILE_OPENED
Table 4.68. Arguments for File::open2()
Argument | Type | Description |
---|---|---|
| String | The Filename of the file. |
| Integer | Flags that determine the way the file is accessed, see File Constants for more information. If this argument is not given, O_RDONLY will be used as the default value. |
| Integer | Permission bits for when the file is to be created (default: 0777) |
| String | The name of the default character encoding for this file. |
Table 4.69. Return Values for File::open2()
Return Type | Description |
---|---|
n/a | This method does not return any value; if an error occurs, an exception is thrown. |
Table 4.70. 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(integer:size, [timeout_ms]
)
$data = $f.read(-1); # read an entire text file into a variable
EVENT_DATA_READ
Table 4.71. Arguments for File::read()
Argument | Type | Description |
---|---|---|
| Integer | The number of bytes to read of the file, -1 will read the entire 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.72. Return Value for File::read()
Return Type | Description |
---|---|
String | The data read from the file, returned as a string. NOTHING is returned if end-of-file is encountered, however, if data has been read before EOF, the data read will be returned and NOTHING (signifying EOF) will be returned on the next call to this method. |
Table 4.73. 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()
$int = $f.readi1();
EVENT_DATA_READ
Table 4.74. Arguments for File::readi1()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method does not take any arguments. |
Table 4.75. Return Value for File::readi1()
Return Type | Description |
---|---|
Integer | Returns a 1-byte signed integer as read from the file in binary format. |
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()
$int = $f.readi2();
EVENT_DATA_READ
Table 4.77. Arguments for File::readi2()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method does not take any arguments. |
Table 4.78. Return Value for File::readi2()
Return Type | Description |
---|---|
Integer | Returns a 2-byte signed integer as read from the file in big-endian format. |
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()
$int = $f.readi4();
EVENT_DATA_READ
Table 4.80. Arguments for File::readi4()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method does not take any arguments. |
Table 4.81. Return Value for File::readi4()
Return Type | Description |
---|---|
Integer | Returns a 4-byte signed integer as read from the file in big-endian format. |
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()
$int = $f.readi8();
EVENT_DATA_READ
Table 4.83. Arguments for File::readi8()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method does not take any arguments. |
Table 4.84. Return Value for File::readi8()
Return Type | Description |
---|---|
Integer | Returns a 4-byte signed integer as read from the file in big-endian format. |
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()
$int = $f.readi2LSB();
EVENT_DATA_READ
Table 4.86. Arguments for File::readi2LSB()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method does not take any arguments. |
Table 4.87. Return Value for File::readi2LSB()
Return Type | Description |
---|---|
Integer | Reads a 2-byte signed integer from the file in little-endian format. |
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()
$int = $f.readi4LSB();
EVENT_DATA_READ
Table 4.89. Arguments for File::readi4LSB()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method does not take any arguments. |
Table 4.90. Return Value for File::readi4LSB()
Return Type | Description |
---|---|
Integer | Reads a 4-byte signed integer from the file in little-endian format. |
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()
$int = $f.readi8LSB();
EVENT_DATA_READ
Table 4.92. Arguments for File::readi8LSB()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method does not take any arguments. |
Table 4.93. Return Value for File::readi8LSB()
Return Type | Description |
---|---|
Integer | Reads a 4-byte signed integer from the file in little-endian format. |
Reads a 1-byte unsigned integer from the file and returns the integer value read.
File::readu1()
$int = $f.readu1();
EVENT_DATA_READ
Table 4.95. Arguments for File::readu1()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method does not take any arguments. |
Table 4.96. Return Value for File::readu1()
Return Type | Description |
---|---|
Integer | Returns a 1-byte unsigned integer as read from the file in binary format. |
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()
$int = $f.readu2();
EVENT_DATA_READ
Table 4.98. Arguments for File::readu2()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method does not take any arguments. |
Table 4.99. Return Value for File::readu2()
Return Type | Description |
---|---|
Integer | Returns a 2-byte signed integer as read from the file in big-endian format. |
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()
$int = $f.readu4();
EVENT_DATA_READ
Table 4.101. Arguments for File::readu4()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method does not take any arguments. |
Table 4.102. Return Value for File::readu4()
Return Type | Description |
---|---|
Integer | Returns a 4-byte signed integer as read from the file in big-endian format. |
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()
$int = $f.readu2LSB();
EVENT_DATA_READ
Table 4.104. Arguments for File::readu2LSB()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method does not take any arguments. |
Table 4.105. Return Value for File::readu2LSB()
Return Type | Description |
---|---|
Integer | Reads a 2-byte signed integer from the file in little-endian format. |
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.
File::readu4LSB()
$int = $f.readu4LSB();
EVENT_DATA_READ
Table 4.107. Arguments for File::readu4LSB()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method does not take any arguments. |
Table 4.108. Return Value for File::readu4LSB()
Return Type | Description |
---|---|
Integer | Reads a 4-byte unsigned integer from the file in little-endian format. |
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(integer:size, [timeout_ms]
)
$data = $f.readBinary(-1); # reads an entire binary file into a variable
EVENT_DATA_READ
Table 4.110. Arguments for File::readBinary()
Argument | Type | Description |
---|---|---|
| Integer | 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.111. Return Value for File::readBinary()
Return Type | Description |
---|---|
Binary | A binary object containing the data read from the file. NOTHING is returned if end-of-file is encountered, however, if data has been read before EOF, the data read will be returned and NOTHING (signifying EOF) will be returned on the next call to this method. |
Table 4.112. 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()
while (exists (my $line = $f.readLine())) { # remove EOL marker chomp $line; # print out the line just read printf("%s\n", $line); }
EVENT_DATA_READ
Table 4.113. Arguments for File::readLine()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.114. Return Value for File::readLine()
Return Type | Description |
---|---|
String | The line read from the file. NOTHING is returned if end-of-file is encountered, however, if data has been read before EOF, the data read will be returned and NOTHING (signifying EOF) will be returned on the next call to this method. |
Sets the characte encoding for the file.
File::setCharset(string:encoding
)
$f.setCharset("ISO-8859-1");
Table 4.116. Arguments for File::setCharset()
Argument | Type | Description |
---|---|---|
| String | The character encoding for the file. |
Table 4.117. Return Value for File::setCharset()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Sets the current file position in bytes starting with zero.
File::setPos(integer:position
)
$f.setPos(0); # go to the beginning of the file
Table 4.118. Arguments for File::setPos()
Argument | Type | Description |
---|---|---|
| Integer | The position in the file as offset from position 0. |
Table 4.119. Return Value for File::setPos()
Return Type | Description |
---|---|
Integer | 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(termios
)
my $termios = new TermIOS(); my $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.121. Return Value for File::setTerminalAttributes()
Return Type | Description |
---|---|
Integer | Always returns 0; if an error is encountered, an exception is raised. |
Table 4.122. 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()
$f.sync();
Table 4.123. Arguments for File::sync()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method does not take any arguments. |
Table 4.124. Return Value for File::sync()
Return Type | Description |
---|---|
Integer | 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:format, [arg_list]
)
$f.vprintf("%5s\n", "hello");
EVENT_DATA_WRITTEN
Table 4.125. Arguments for File::vprintf()
Argument | Type | Description |
---|---|---|
| String | The format string, see String Formatting for a specification. |
| List | This list will be used as the argument list or the format string. |
Table 4.126. Return Value for File::vprintf()
Return Type | Description |
---|---|
Integer | 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(arg
)
$f.write($data);
EVENT_DATA_WRITTEN
Table 4.128. Arguments for File::write()
Argument | Type | Description |
---|---|---|
| String or Binary | Writes the data to the file. |
Table 4.129. Return Value for File::write()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Table 4.130. 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(integer
)
$f.writei1($val);
EVENT_DATA_WRITTEN
Table 4.131. Arguments for File::writei1()
Argument | Type | Description |
---|---|---|
| Integer | The integer to write; only the least-significant 8 bits will be written to the file. |
Table 4.132. Return Value for File::writei1()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Writes a 2-byte integer in big-endian format.
File::writei2(integer
)
$f.writei2($val);
EVENT_DATA_WRITTEN
Table 4.134. Arguments for File::writei2()
Argument | Type | Description |
---|---|---|
| Integer | The integer to write; writes a 2-byte integer in big-endian format. |
Table 4.135. Return Value for File::writei2()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Writes a 4-byte integer in big-endian format.
File::writei4(integer
)
$f.writei4($val);
EVENT_DATA_WRITTEN
Table 4.137. Arguments for File::writei4()
Argument | Type | Description |
---|---|---|
| Integer | The integer to write; writes a 4-byte integer in big-endian format. |
Table 4.138. Return Value for File::writei4()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Writes an 8-byte integer in big-endian format.
File::writei8(integer
)
$f.writei8($val);
EVENT_DATA_WRITTEN
Table 4.140. Arguments for File::writei8()
Argument | Type | Description |
---|---|---|
| Integer | The integer to write; writes an 8-byte integer in big-endian format. |
Table 4.141. Return Value for File::writei8()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Writes a 2-byte integer in little-endian format.
File::writei2LSB(integer
)
$f.writei2LSB($val);
EVENT_DATA_WRITTEN
Table 4.143. Arguments for File::writei2LSB()
Argument | Type | Description |
---|---|---|
| Integer | The integer to write; writes a 2-byte integer in little-endian format. |
Table 4.144. Return Value for File::writei2LSB()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Writes a 4-byte integer in little-endian format.
File::writei4LSB(integer
)
$f.writei4LSB($val);
EVENT_DATA_WRITTEN
Table 4.146. Arguments for File::writei4LSB()
Argument | Type | Description |
---|---|---|
| Integer | The integer to write; writes a 4-byte integer in little-endian format. |
Table 4.147. Return Value for File::writei4LSB()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Writes an 8-byte integer to the file in little-endian (LSB) format.
File::writei8LSB(integer
)
$f.writei8LSB($val);
EVENT_DATA_WRITTEN
Table 4.149. Arguments for File::writei8LSB()
Argument | Type | Description |
---|---|---|
| Integer | The integer to write; writes an 8-byte integer in little-endian format. |
Table 4.150. Return Value for File::writei8LSB()
Return Type | Description |
---|---|
Integer | 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.152. Dir Method Overview
Method | Except? | Description |
---|---|---|
N | Create a Directory object with the 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 not necessarily needs to exist. | |
N | Return the current path of the object. The path is stripped of all '.' and '..' entries. | |
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. | |
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. | |
Y | Create a subdirectory with the name in the directory. | |
Y | Delete an empty subdirectory with the name in the directory. | |
Y | Get all entries in this directory, except '.' and '..' directories (takes an optional regular expression filter). | |
Y | Get all entries in the directory which are not subdirectories (takes an optional regular expression filter). | |
Y | Get all entries in the directory which are subdirectories, except '.' and '..' directories (takes an optional regular expression filter). | |
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.
new Dir([string:encoding]
)
$d = new Dir("UTF-8");
Table 4.153. Arguments for Dir::constructor()
Argument | Type | Description |
---|---|---|
| String | The character encoding for the directory. Any entry of the directory will be converted to this character encoding if necessary. |
Creates a new Dir object with the same character encoding specification and path as the original.
Dir::copy()
$d2 = $d.copy();
Table 4.156. Return Value for Dir::copy()
Return Type | Description |
---|---|
n/a | The new Dir object created with the same character encoding specification and path as the original object. |
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(newdir)
if($d.chdir("../doc")) { printf("the directory does not exist or is not readable\n"); }
Table 4.158. Return Value for Dir::chdir()
Return Type | Description |
---|---|
Boolean | True if the new path is openable as directory (see exists()). |
Return the path of the Dir object. This path needs not necessarily to exist. The path is stripped from all '.' and '..' directories.
Dir::path()
$mypath = $d.path();
Return if the path in the Dir object points to a directory which is openable by the Program.
Dir::exists()
if(!$d.exists()) { printf("the directory %s does not exist\n", $d.path()); exit(-1); }
Table 4.161. Arguments for Dir::exists()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.162. Return Value for Dir::exists()
Return Type | Description |
---|---|
Boolean | True if the directory is openable. |
Create the whole directory tree the Dir object points to, if it does not exist till now.
Dir::create([mode])
if (!$d.exists()) { printf("directory '%s' does not exist, so i create it\n", $d.path()); $cnt = $d.create(); }
Table 4.163. Arguments for Dir::create()
Argument | Type | Description |
---|---|---|
[mode] | Integer | The mode of the directory. |
Table 4.165. 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(uid|username)
$d.chown("nobody");
Table 4.166. Arguments for Dir::chown()
Argument | Type | Description |
---|---|---|
uid | Integer | The userid to be used. |
username | String | A username which is known by the system. |
Table 4.167. Return Value for Dir::chown()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Table 4.168. 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(gid|groupname)
$d.chgrp("nogroup");
Table 4.169. Arguments for Dir::chgrp()
Argument | Type | Description |
---|---|---|
gid | Integer | The groupid to be set for the directory. |
groupname | String | The name of the group to be set. Must be known in the system. |
Table 4.170. Return Value for Dir::chgrp()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Table 4.171. 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([mode])
$d.chmod(0711); # set mode to u(rwx) and go(x)
Table 4.173. Return Value for Dir::chmod()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Table 4.174. 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(subdir, [mode])
$d.mkdir("newSubDir", 0755);
Table 4.175. Arguments for Dir::mkdir()
Argument | Type | Description |
---|---|---|
subdir | String | The name of the subdirectory. |
mode | Integer | The mode of the new directory. |
Table 4.176. Return Value for Dir::mkdir()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Table 4.177. 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(dirname)
$d.rmdir("emptySubdir");
Table 4.178. Arguments for Dir::rmdir()
Argument | Type | Description |
---|---|---|
dirname | String | The name of the directory to be removed. |
Table 4.179. Return Value for Dir::rmdir()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Table 4.180. 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.
Dir::list([regex, [regex_option]])
foreach my $e in ( $d.list() ) { printf("entry: %s\n"); }
Table 4.181. Arguments for Dir::list()
Argument | Type | Description |
---|---|---|
[regex] | string | A regular expression string used to filter the arguments. |
[regex_option] | Integer | For valid options, see Regex Constants |
Table 4.182. Return Value for Dir::list()
Return Type | Description |
---|---|
List | A list of Strings with the directories content. |
Table 4.183. 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()
foreach my $e in ( $d.listFiles() ) { printf("file: %s\n"); }
Table 4.184. Arguments for Dir::listFiles()
Argument | Type | Description |
---|---|---|
[regex] | string | A regular expression string used to filter the arguments. |
[regex_option] | Integer | For valid options, see Regex Constants |
Table 4.185. Return Value for Dir::listFiles()
Return Type | Description |
---|---|
List | A list of Strings with the directories content. |
Table 4.186. 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, which are subdirectories. It supresses 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()
foreach my $e in ( $d.listDirs() ) { printf("entry: %s\n"); }
Table 4.187. Arguments for Dir::listDirs()
Argument | Type | Description |
---|---|---|
[regex] | string | A regular expression string used to filter the arguments. |
[regex_option] | Integer | For valid options, see Regex Constants |
Table 4.188. Return Value for Dir::listDirs()
Return Type | Description |
---|---|
List | A list of Strings with the directories content. |
Table 4.189. 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:dirname, [string:charset]
)
# open a subdir for working with. $sd = $d.openDir("mysubdir", "ISO-8859-1"); $sd_list = $sd.list();
Table 4.190. Arguments for Dir::openDir()
Argument | Type | Description |
---|---|---|
| String | The name of the subdirectory. The directory must not exist and can be created with create() afterwards. |
| String | The name of the default character encoding for this directory. |
Table 4.191. Return Value for Dir::openDir()
Return Type | Description |
---|---|
Object | The Dir object created for the directory. |
Table 4.192. 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:filename, [integer:flags, [integer:mode, [string:charset]]]
)
# 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.193. Arguments for Dir::openFile()
Argument | Type | Description |
---|---|---|
| String | The Filename of the file. |
| Integer | Flags that determine the way the file is accessed, see File Constants for more information. If this argument is not given, O_RDONLY will be used as the default value. |
| Integer | Permission bits for when the file is to be created (default: 0666) |
| String | The name of the default character encoding for this file. |
Table 4.194. Return Value for Dir::openFile()
Return Type | Description |
---|---|
Object | The File object created or opened in the directory. |
Table 4.195. 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(filename)
$d.removeFile("myTestFile.dat");
Table 4.196. Arguments for Dir::removeFile()
Argument | Type | Description |
---|---|---|
filename | String | The name of the file in the directory. |
Table 4.197. Return Value for Dir::removeFile()
Return Type | Description |
---|---|
Boolean | True if the file was present and could be removed. False if the file did not exist. |
Table 4.198. 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 $t = new TermIOS(); stdin.getTerminalAttributes($t); my $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.199. 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. | |
N | Gets the value of a control character for the object. | |
N | 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. |
Table 4.200. TermIOS Static Method Overview
Method | Except? | Description |
---|---|---|
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.
new TermIOS()
my $termios = new TermIOS(); stdin.getTerminalAttributes($termios);
Table 4.201. Arguments for TermIOS::constructor()
Argument | Type | Description |
---|---|---|
n/a | n/a | The constructor takes no arguments. |
Table 4.202. Return Values for TermIOS::constructor()
Return Type | Description |
---|---|
TermIOS Object | The new TermIOS object. |
Destroys the TermIOS object.
delete lvalue
delete $termios;
This method does not throw any exceptions.
Returns a copy of the object.
This method does not throw any exceptions.
Returns the local mode flag for the object
TermIOS::getLFlag()
Table 4.203. Arguments for TermIOS::getLFlag()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.204. Return Values for TermIOS::getLFlag()
Return Type | Description |
---|---|
Integer | The local mode flag for the object |
Returns the control mode flag for the object
TermIOS::getCFlag()
Table 4.205. Arguments for TermIOS::getCFlag()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.206. Return Values for TermIOS::getCFlag()
Return Type |
Description |
---|---|
Integer |
The control mode flag for the object |
Returns the input mode flag for the object
TermIOS::getIFlag()
Table 4.207. Arguments for TermIOS::getIFlag()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.208. Return Values for TermIOS::getIFlag()
Return Type |
Description |
---|---|
Integer |
The input mode flag for the object |
Returns the output mode flag for the object
TermIOS::getOFlag()
Table 4.209. Arguments for TermIOS::getOFlag()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.210. Return Values for TermIOS::getOFlag()
Return Type |
Description |
---|---|
Integer |
The output mode flag for the object |
Sets the local mode flag for the object
TermIOS::setLFlag(lflag
)
Table 4.211. Arguments for TermIOS::setLFlag()
Argument |
Type |
Description |
---|---|---|
|
Integer |
The local mode to set for the object. |
Table 4.212. Return Values for TermIOS::setLFlag()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Sets the control mode flag for the object
TermIOS::setCFlag(cflag
)
Table 4.213. Arguments for TermIOS::setCFlag()
Argument |
Type |
Description |
---|---|---|
|
Integer |
The control mode to set for the object. |
Table 4.214. Return Values for TermIOS::setCFlag()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Sets the input mode flag for the object
TermIOS::setIFlag(iflag
)
Table 4.215. Arguments for TermIOS::setIFlag()
Argument |
Type |
Description |
---|---|---|
|
Integer |
The input mode to set for the object. |
Table 4.216. Return Values for TermIOS::setIFlag()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Sets the output mode flag for the object
TermIOS::setOFlag(oflag
)
Table 4.217. Arguments for TermIOS::setOFlag()
Argument |
Type |
Description |
---|---|---|
|
Integer |
The output mode to set for the object. |
Table 4.218. Return Values for TermIOS::setOFlag()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Returns the value of the control character corresponding to the argument passed.
TermIOS::getCC(cc
)
Table 4.219. Arguments for TermIOS::getCC()
Argument |
Type |
Description |
---|---|---|
| Integer | The control character to get from th object. |
Table 4.220. Return Values for TermIOS::getCC()
Return Type |
Description |
---|---|
Integer |
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(cc, val
)
Table 4.221. Arguments for TermIOS::setCC()
Argument |
Type |
Description |
---|---|---|
|
Integer |
The control character to set. |
|
Integer |
The value to set |
Table 4.222. Return Values for TermIOS::setCC()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
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
)
Table 4.223. Arguments for TermIOS::isEqual()
Argument |
Type |
Description |
---|---|---|
|
TermIOS |
The object to compare to the current object. |
Table 4.224. Return Values for TermIOS::isEqual()
Return Type |
Description |
---|---|
Boolean |
The result of comparing the current object to the argument |
Table 4.225. 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
.
TermIOS::getWindowSize()
$hash = TermIOS::getWindowSize()
Table 4.226. Arguments for TermIOS::getWindowSize()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.227. Return Values for TermIOS::getWindowSize()
Return Type | Description |
---|---|
Hash | 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.228. 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. |
Creates the GetOpt object and sets the option hash with the single required argument.
new GetOpt(option_hash
)
const program_options =
( "url" : "url,u=s",
"xml" : "xml,x",
"lxml" : "literal-xml,X",
"verb" : "verbose,v",
"help" : "help,h" );
$getopt = new GetOpt(program_options);
Table 4.229. Arguments for GetOpt::constructor()
Argument | Type | Description |
---|---|---|
| Hash | 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.230. 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.231. Return Values for GetOpt::constructor()
Return Type | Description |
---|---|
Object | The GetOpt object created. |
Table 4.232. Exceptions Thrown by GetOpt::constructor()
err | desc |
---|---|
| There was a syntax or format error in the option specification. |
Destroys the GetOpt object.
delete lvalue
delete $getopt;
Throws an exception; objects of this class cannot be copied.
Table 4.233. Arguments for GetOpt::copy()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.234. Return Values for GetOpt::copy()
Return Type | Description |
---|---|
n/a | This method returns no value because it throws an exception. |
Table 4.235. 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).
GetOpt::parse(list_reference
)
$o = $getopt.parse(\$ARGV);
Table 4.236. Arguments for GetOpt::parse()
Argument | Type | Description |
---|---|---|
| List Reference | The entire command line to process (ex: $ARGV). |
Table 4.237. Return Values for GetOpt::parse()
Return Type | Description |
---|---|
Hash | 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 "_ERRORS_" will contain any errors. |
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.238. FtpClient::constructor() Default URL Parameters
Field | Default Value |
---|---|
| FTP (unencrypted) |
| anonymous |
| qore@nohost.com |
| 21 |
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.
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.239. 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.240. 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. | |
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 True if the control connection is a secure TLS/SSL connection. | |
N |
Returns True if the data connections are secure TLS/SSL connections. | |
N |
Returns the name of the cipher for an encrypted connection. | |
N |
Returns the version string of the cipher for encrypted connections. | |
N |
Returns a string code giving the result of verifying the remote certificate. | |
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. | |
Y | Gets a list of file names from the FTP server. | |
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. | |
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. | |
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 | |
N | Sets the port to connect to | |
Y | Sets the URL | |
N | Gets the current user name | |
N | Gets the current password | |
N | Gets the current hostname | |
N | Gets the current port | |
N | Gets the current FTP URL | |
N | Sets a Queue object to receive socket and FtpClient events on both the data and control connections. | |
N | Sets a Queue object to receive socket and FtpClient events on the data connection. | |
N | Sets a Queue object to receive socket and FtpClient events on the control connection. |
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.
new FtpClient([string_value
])
$ftp = new FtpClient("ftp://user:pass@hostname");
Table 4.241. Arguments for FtpClient::constructor()
Argument | Type | Description |
---|---|---|
| String | The entire command line to process. |
Table 4.242. Return Values for FtpClient::constructor()
Return Type | Description |
---|---|
Object | The FtpClient object created |
Table 4.243. 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 lvalue
delete $ftp;
EVENT_CHANNEL_CLOSED, EVENT_DELETED
Throws an exception; objects of this class cannot be copied.
Table 4.244. Arguments for FtpClient::copy()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.245. Return Values for FtpClient::copy()
Return Type | Description |
---|---|
n/a | This method returns no value because it throws an exception. |
Table 4.246. Exceptions Thrown by FtpClient::copy()
err | desc |
---|---|
| Objects of this class cannot be copied. |
Connects to the FTP server and attempts a login.
FtpClient::connect(optional:string_value
)
$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.247. Arguments for FtpClient::connect()
Argument | Type | Description |
---|---|---|
| String | The URL of the FTP connection. |
Table 4.248. Return Values for FtpClient::connect()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Table 4.249. 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()
$ftp.disconnect();
EVENT_CHANNEL_CLOSED
Table 4.250. Arguments for FtpClient::disconnect()
Argument | Type | Description |
---|---|---|
n/a | n/a | No arguments are accepted by this method |
Table 4.251. Return Values for FtpClient::disconnect()
Return Type | Description |
---|---|
Integer | Always returns 0 for success, on errors an exception is thrown. |
Make an FTPS connection to the server on the next connect.
FtpClient::setSecure()
$ftp.setSecure();
Table 4.252. Arguments for FtpClient::setSecure()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.253. Return Values for FtpClient::setSecure()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Table 4.254. 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()
$ftp.setInsecure();
Table 4.255. Arguments for FtpClient::setInsecure()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.256. Return Values for FtpClient::setInsecure()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Table 4.257. 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()
$ftp.setInsecureData();
Table 4.258. Arguments for FtpClient::setInsecureData()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.259. Return Values for FtpClient::setInsecureData()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Table 4.260. 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()
$bool = $ftp.isSecure();
Table 4.261. Arguments for FtpClient::isSecure()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.262. Return Values for FtpClient::isSecure()
Return Type |
Description |
---|---|
Boolean |
True if the control connection is encrypted. |
Returns True if the data connections are secure TLS/SSL connections.
FtpClient::isDataSecure()
$bool = $ftp.isDataSecure();
Table 4.263. Arguments for FtpClient::isDataSecure()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.264. Return Values for FtpClient::isDataSecure()
Return Type |
Description |
---|---|
Boolean |
True if data connections are encrypted. |
Returns the name of the cipher for an encrypted connection.
FtpClient::getSSLCipherName()
$str = $ftp.getSSLCipherName();
Table 4.265. Arguments for FtpClient::getSSLCipherName()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.266. Return Values for FtpClient::getSSLCipherName()
Return Type |
Description |
---|---|
String |
The name of the cipher for an encrypted connection. |
Returns the version string of the cipher for encrypted connections.
FtpClient::getSSLCipherVersion()
$str = $ftp.getSSLCipherVersion();
Table 4.267. Arguments for FtpClient::getSSLCipherVersion()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.268. Return Values for FtpClient::getSSLCipherVersion()
Return Type |
Description |
---|---|
String |
The version string of the cipher for encrypted connections. |
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()
$str = $ftp.verifyPeerCertificate();
Table 4.269. Arguments for FtpClient::verifyPeerCertificate()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.270. Return Values for FtpClient::verifyPeerCertificate()
Return Type |
Description |
---|---|
String |
A string code giving the result of verifying the peer's certificate. No value is returned if no secure connection has been established. |
Sets the object to automatically try to negotiate the data connections in EPSV, PASV, and PORT modes, in this order.
FtpClient::setModeAuto()
$ftp.setModeAuto();
Table 4.271. Arguments for FtpClient::setModeAuto()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.272. Return Values for FtpClient::setModeAuto()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Sets the object to only try to make data connections using EPSV (RFC-2428 extended passive) mode.
FtpClient::setModeEPSV()
$ftp.setModeEPSV();
Table 4.273. Arguments for FtpClient::setModeEPSV()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.274. Return Values for FtpClient::setModeEPSV()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Sets the object to only try to make data connections using PASV (RFC-959 passive) mode.
FtpClient::setModePASV()
$ftp.setModePASV();
Table 4.275. Arguments for FtpClient::setModePASV()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.276. Return Values for FtpClient::setModePASV()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Sets the object to only try to make data connections using PORT mode.
FtpClient::setModePORT()
$ftp.setModePORT();
Table 4.277. Arguments for FtpClient::setModePORT()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.278. Return Values for FtpClient::setModePORT()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Gets a list of files from the FTP server in the server's long format in the current working directory.
FtpClient::list()
$list = $ftp.list();
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT
Table 4.279. Arguments for FtpClient::list()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method does not take any arguments. |
Table 4.280. Return Values for FtpClient::list()
Return Type | Description |
---|---|
String | The string returned by the server without any translations or processing. |
Table 4.281. 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()
$str = $ftp.nlst();
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT
Table 4.282. Arguments for FtpClient::nlst()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method does not take any arguments. |
Table 4.283. Return Values for FtpClient::nlst()
Return Type | Description |
---|---|
String | The string returned by the server without any translations or processing. |
Table 4.284. 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()
$str = $ftp.pwd();
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT
Table 4.285. Arguments for FtpClient::pwd()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method does not take any arguments. |
Table 4.286. Return Values for FtpClient::pwd()
Return Type | Description |
---|---|
String | The server-side current working directory. |
Table 4.287. 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(path
)
$ftp.cwd("/pub/gnu");
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT
Table 4.288. Arguments for FtpClient::cwd()
Argument | Type | Description |
---|---|---|
| String | The directory to change to. |
Table 4.289. Return Values for FtpClient::cwd()
Return Type | Description |
---|---|
Integer | Always returns 0, on errors exceptions are raised. |
Table 4.290. 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.
FtpClient::get(server_path
, [local_path
])
$ftp.get("file.txt", "/tmp/file-1.txt");
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT
Table 4.291. Arguments for FtpClient::get()
Argument | Type | Description |
---|---|---|
| String | The path on the server to the file to get. |
[ | String | If given, where to save the local file. |
Table 4.292. Return Values for FtpClient::get()
Return Type | Description |
---|---|
Integer | Always returns 0, on errors exceptions are raised. |
Table 4.293. 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(server_path
)
my $b = $ftp.getAsBinary("file.bin");
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT
Table 4.294. Arguments for FtpClient::getAsBinary()
Argument | Type | Description |
---|---|---|
| String | The path on the server to the file to get. |
Table 4.295. Return Values for FtpClient::getAsBinary()
Return Type | Description |
---|---|
Binary | The file retrieved; if any errors occur an exception is raised. |
Table 4.296. 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(server_path
)
my $str = $ftp.getAsString("file.txt");
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT
Table 4.297. Arguments for FtpClient::getAsString()
Argument | Type | Description |
---|---|---|
| String | The path on the server to the file to get. |
Table 4.298. Return Values for FtpClient::getAsString()
Return Type | Description |
---|---|
String | The file retrieved; if any errors occur an exception is raised. |
Table 4.299. 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.
FtpClient::put(local_path
, [server_path
])
$ftp.put("/tmp/file-1.txt", "file.txt");
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT
Table 4.300. Arguments for FtpClient::put()
Argument | Type | Description |
---|---|---|
| String | The path on the local system of the file to send. |
[ | String | If given, where to save the file on the server. |
Table 4.301. Return Values for FtpClient::put()
Return Type | Description |
---|---|
Integer | Always returns 0, on errors exceptions are raised. |
Table 4.302. 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.
FtpClient::del(server_path
)
$ftp.del("file-2.txt");
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT
Table 4.303. Arguments for FtpClient::del()
Argument | Type | Description |
---|---|---|
| String | The path on the server to the file to delete. |
Table 4.304. Return Values for FtpClient::del()
Return Type | Description |
---|---|
Integer | Always returns 0, on errors exceptions are raised. |
Table 4.305. 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
)
$ftp.setUserName("ftp");
Table 4.306. Arguments for FtpClient::setUserName()
Argument | Type | Description |
---|---|---|
| String | The username to use when logging in to the FTP server. |
Table 4.307. Return Values for FtpClient::setUserName()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Table 4.308. 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
)
$ftp.setPassword("ftp");
Table 4.309. Arguments for FtpClient::setPassword()
Argument | Type | Description |
---|---|---|
| String | The password to use when logging in to the FTP server. |
Table 4.310. Return Values for FtpClient::setPassword()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Table 4.311. 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
)
$ftp.setHostName("hostname");
Table 4.312. Arguments for FtpClient::setHostName()
Argument | Type | Description |
---|---|---|
| String | The hostname to use when connecting to the FTP server. |
Table 4.313. Return Values for FtpClient::setHostName()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Table 4.314. Exceptions Thrown by FtpClient::setHostName()
err | desc |
---|---|
| Missing argument to the method. |
Sets the control port value (default is 21).
FtpClient::setPort(integer
)
$ftp.setPort(21);
Table 4.315. Arguments for FtpClient::setPort()
Argument | Type | Description |
---|---|---|
| Integer | The port to use when connecting to the FTP server. |
Table 4.316. Return Values for FtpClient::setPort()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Table 4.317. 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
)
$ftp.setURL("ftps://user:pass@host");
Table 4.318. Arguments for FtpClient::setURL()
Argument | Type | Description |
---|---|---|
| String | The URL to use to set connection and login parameters for the FTP server. |
Table 4.319. Return Values for FtpClient::setURL()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Table 4.320. 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()
$user = $ftp.getUserName();
Table 4.321. Arguments for FtpClient::getUserName()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.322. Return Values for FtpClient::getUserName()
Return Type | Description |
---|---|
String | The current username value. |
Retrieves the current login password value for this object.
FtpClient::getPassword()
$pass = $ftp.getPassword();
Table 4.323. Arguments for FtpClient::getPassword()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.324. Return Values for FtpClient::getPassword()
Return Type | Description |
---|---|
String | The current password value. |
Retrieves the current hostname value for this object.
FtpClient::getHostName()
$host = $ftp.getHostName();
Table 4.325. Arguments for FtpClient::getHostName()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.326. Return Values for FtpClient::getHostName()
Return Type | Description |
---|---|
String | The current hostname value. |
Retrieves the current connection port value for this object.
FtpClient::getPort()
$port = $ftp.getPort();
Table 4.327. Arguments for FtpClient::getPort()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.328. Return Values for FtpClient::getPort()
Return Type | Description |
---|---|
Integer | The current connection port value. |
Retrieves the current connection URL string for this object.
FtpClient::getURL()
$url = $ftp.getURL();
Table 4.329. Arguments for FtpClient::getURL()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.330. Return Values for FtpClient::getURL()
Return Type | Description |
---|---|
String | The current URL value. |
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([queue]
)
$ftp.setEventQueue($queue);
Table 4.332. Return Values for FtpClient::setEventQueue()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
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([queue]
)
$ftp.setDataEventQueue($queue);
Table 4.334. Return Values for FtpClient::setDataEventQueue()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
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([queue]
)
$ftp.setControlEventQueue($queue);
Table 4.336. Return Values for FtpClient::setControlEventQueue()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
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.337. Parse Options
Constant | Details | Description |
---|---|---|
PO_NO_GLOBAL_VARS | Disallows the use of global variables. | |
PO_NO_SUBROUTINE_DEFS | Disallows subroutine (function) definitions. | |
PO_NO_THREADS | 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). | |
PO_NO_THREAD_CLASSES | Disallows access to any thread classes. | |
PO_NO_THREAD_CONTROL | Disallows access to any thread-control functions and thread-relevant statements and operators (for example the background operator and the thread_exit statement). | |
PO_NO_TOP_LEVEL_STATEMENTS | Disallows top level code. | |
PO_NO_CLASS_DEFS | Disallows class definitions. | |
PO_NO_NAMESPACE_DEFS | Disallows new namespace definitions. | |
PO_NO_CONSTANT_DEFS | Disallows constant definitions. | |
PO_NO_NEW | Disallows use of the new operator. | |
PO_NO_SYSTEM_CLASSES | n/a | Prohibits system classes from being imported into the new Program object. |
PO_NO_USER_CLASSES | n/a | Prohibits user classes from being imported into the new Program object. |
PO_NO_CHILD_PO_RESTRICTIONS | Allows child program objects to have fewer parse restrictions than the parent object. | |
PO_NO_EXTERNAL_PROCESS | Disallows any access to external processes (with system(), backquote(), exec(), etc). | |
PO_REQUIRE_OUR | Requires global variables to be declared with our before use. | |
PO_NO_PROCESS_CONTROL | Disallows access to functions that would affect the current process (exit(), exec(), fork(), etc). | |
PO_NO_NETWORK | Disallows access to network functions. | |
PO_NO_FILESYSTEM | Disallows access to the filesystem. | |
PO_LOCK_WARNINGS | Disallows changes to the warning mask. | |
PO_NO_DATABASE | Disallows access to database functionality. | |
PO_NO_GUI | Disallows access to functionality that draws graphics to the display. | |
PO_NO_TERMINAL_IO | Disallows access to reading from and/or writing to the terminal. |
Table 4.338. 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 (if any). | |
N | Returns the current script name (if any). | |
N | Returns the current script directory and filename (if any). | |
N | Returns a list 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 | |
Y | Commits all pending changes to the program object. | |
Y | Performs a 1st stage parse of the string passed | |
Y | 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 the script path (directory and filename) for the object. |
Creates the Program object. It accepts one optional argument that will set the program capabilities for the program object.
new Program([integer:parse_options
])
$pgm = new Program();
Table 4.339. Arguments for Program::constructor()
Argument | Type | Description |
---|---|---|
| Integer | A binary OR'ed product of parse options. |
Table 4.340. Return Values for Program::constructor()
Return Type | Description |
---|---|
Object | The Program object created. |
Destroys the object. If any threads are running in the program, the destructor will block until the threads terminate.
delete lvalue
delete $pgm;
Throws an exception; objects of this class cannot be copied.
Table 4.341. Arguments for Program::copy()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.342. Return Values for Program::copy()
Return Type | Description |
---|---|
n/a | This method returns no value because it throws an exception. |
Table 4.343. 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:function_name, [args ...]
)
$result = $pgm.callFunction("func_name", $arg1, $arg2);
Table 4.344. Arguments for Program::callFunction()
Argument | Type | Description |
---|---|---|
| String | The name of the function to call. |
| Any | The remaining arguments passed to the method are passed to the function to be called. |
Table 4.345. Return Values for Program::callFunction()
Return Type | Description |
---|---|
Any | Depends on the function being called. |
Table 4.346. 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:function_name, [arg_list]
)
$result = $pgm.callFunctionArgs("func_name", $arg_list);
Table 4.347. Arguments for Program::callFunctionArgs()
Argument | Type | Description |
---|---|---|
| String | The name of the function to call. |
| List | Argument list to be passed to the function. |
Table 4.348. Return Values for Program::callFunctionArgs()
Return Type | Description |
---|---|
Any | Depends on the function being called. |
Table 4.349. 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(options
)
# allow threading and GUI operations $pgm.disableParseOptions(PO_NO_THREADS | PO_NO_GUI);
Table 4.350. Arguments for Program::disableParseOptions()
Argument | Type | Description |
---|---|---|
| Integer | A single parse option or binary-or combination of parse options to disable in the parse option mask for the current object. |
Table 4.351. Return Values for Program::disableParseOptions()
Return Type | Description |
---|---|
n/a | This method returns no value; if an error occurs an exception is raised. |
Table 4.352. 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
)
$bool = $pgm.existsFunction("func_name");
Table 4.353. Arguments for Program::existsFunction()
Argument | Type | Description |
---|---|---|
| String | The name of the function to check. |
Table 4.354. Return Values for Program::existsFunction()
Return Type | Description |
---|---|
Boolean | Returns True if the function exists, False if not. |
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(var_name, [exists_ref]
)
$val = $pgm.getGlobalVariable("error_count", \$exists);
Table 4.355. Arguments for Program::getGlobalVariable()
Argument | Type | Description |
---|---|---|
| String | The string name of the variable to find, not including the leading "$" character. |
| Reference | If a reference is passed in this position, it will contain a boolean value after the method exits: if this value is True, that means that the variable exists in the Program object, False means that the variable does not exist. |
Table 4.356. Return Values for Program::getParseOptions()
Return Type | Description |
---|---|
Any | The value of the global variable (or NOTHING if it does not exist; note that also the variable could exist and return NOTHING as well; use a reference as the second argument to the method to determine if the variable exists or not). |
This method does not throw any exceptions.
Returns the current binary-or parse option mask for the Program object.
Program::getParseOptions()
$mask = $pgm.getParseOptions();
Table 4.357. Arguments for Program::getParseOptions()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.358. Return Values for Program::getParseOptions()
Return Type | Description |
---|---|
Integer | 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()
my $dir = $pgm.getScriptDir();
Table 4.359. Arguments for Program::getScriptDir()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.360. Return Values for Program::getScriptDir()
Return Type | Description |
---|---|
String | The current script directory. |
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()
my $name = $pgm.getScriptName();
Table 4.361. Arguments for Program::getScriptName()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.362. Return Values for Program::getScriptName()
Return Type | Description |
---|---|
String | The current script name if known, otherwise returns NOTHING. |
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()
my $path = $pgm.getScriptPath();
Table 4.363. Arguments for Program::getScriptPath()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.364. Return Values for Program::getScriptPath()
Return Type | Description |
---|---|
String | The current script directory and filename if known, otherwise returns NOTHING. |
This method does not throw any exceptions.
Returns a list of all user functions defined in the Program object.
Program::getUserFunctionList()
$list = $pgm.getUserFunctionList();
Table 4.365. Arguments for Program::getUserFunctionList()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.366. Return Values for Program::getUserFunctionList()
Return Type | Description |
---|---|
List | 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(function_name
)
$pgm.importFunction("function");
Table 4.367. Arguments for Program::importFunction()
Argument | Type | Description |
---|---|---|
| String | The name of the function to import. |
Table 4.368. Return Values for Program::importFunction()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Table 4.369. 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, [boolean:read_only]
)
$pgm.importGlobalVariable("var");
Table 4.370. Arguments for Program::importGlobalVariable()
Argument | Type | Description |
---|---|---|
| String | The name of the global variable without the $ |
| Boolean | If this argument is present and is True, then the variable will be imported read-only, and cannot be changed by the subprogram. |
Table 4.371. Return Values for Program::importGlobalVariable()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Table 4.372. 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::lockParseOptions()
$pgm.lockParseOptions();
Table 4.373. Arguments for Program::lockParseOptions()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.374. Return Values for Program::lockOptions()
Return Type | Description |
---|---|
n/a | This method does not return any value; it always succeeds. |
This method does not throw any exceptions.
Parses the string argument and adds the code to the program object.
Program::parse(string
,label
)
$pgm.parse($code, "label");
Table 4.375. Arguments for Program::parse()
Argument | Type | Description |
---|---|---|
| String | The code to parse. |
| String | The code to parse. |
Table 4.376. Return Values for Program::parse()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Table 4.377. 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.
Program::parseCommit()
$pgm.parseCommit();
Table 4.378. Arguments for Program::parseCommit()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.379. Return Values for Program::parseCommit()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Table 4.380. 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.
Program::parsePending(string
,label
)
$pgm.parsePending($code, "label");
Table 4.381. Arguments for Program::parsePending()
Argument | Type | Description |
---|---|---|
| String | The code to parse. |
| String | The code to parse. |
Table 4.382. Return Values for Program::parsePending()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Table 4.383. 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()
$pgm.parseRollback();
Table 4.384. Arguments for Program::parseRollback()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.385. Return Values for Program::parseRollback()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Runs the program and optionally returns a value if the top-level code exits with a return statement.
Program::run()
$pgm.run();
Table 4.386. Arguments for Program::run()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.387. Return Values for Program::run()
Return Type | Description |
---|---|
Any | Depends on the program - any final return statement 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(options
)
# disallow threading and GUI operations $pgm.setParseOptions(PO_NO_THREADS | PO_NO_GUI);
Table 4.388. Arguments for Program::setParseOptions()
Argument | Type | Description |
---|---|---|
| Integer | A single parse option or binary-or combination of parse options to set in the parse option mask for the current object. |
Table 4.389. Return Values for Program::setParseOptions()
Return Type | Description |
---|---|
n/a | This method returns no value; if an error occurs an exception is raised. |
Table 4.390. 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(path_string
)
$pgm.setScriptPath("/users/test/test.q");
Table 4.391. Arguments for Program::setScriptPath()
Argument | Type | Description |
---|---|---|
| String | The path (directory and filename) for the current script. If the directory component is missing, then "./" is assumed. |
Table 4.392. Return Values for Program::setScriptPath()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
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.393. 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.394. 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 or UNIX domain socket file. | |
Y |
Connects to a remote socket and attempts to establish a TLS/SSL connection. | |
Y | Binds the socket to a 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). | |
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 | |
N | Returns True or False depending on whether there is data to be read on the socket | |
N | Returns True or False depending on whether all data has been written to the socket | |
Y | Sends string or binary data over the socket | |
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 | |
Y | Sends an HTTP response with user-defined headers given as a hash | |
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 | |
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. | |
N |
Returns the version string of the cipher for encrypted connections. | |
N |
Returns True if the connection is a secure TLS/SSL connection. | |
N |
Returns True if the socket is open. | |
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. | |
N | Sets a Queue object to receive socket events. |
Creates the socket object.
new Socket()
$sock = new Socket();
Table 4.395. Arguments for Socket::constructor()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.396. Return Values for Socket::constructor()
Return Type | Description |
---|---|
Object | The new Socket object created. |
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 lvalue
delete $sock;
EVENT_CHANNEL_CLOSED, EVENT_DELETED
Creates a new Socket object, not based on the original.
Socket::copy()
$new_sock = $sock.copy();
Table 4.397. Arguments for Socket::copy()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.398. Return Values for Socket::copy()
Return Type | Description |
---|---|
Socket Object | A new Socket object, not based on the original. |
Binds the socket to a 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(port, [reuse_addr]
)
Socket::bind(host_and_port, [reuse_addr]
)
Socket::bind(filename, [reuse_addr]
)
# 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 and do not reuse the address $sock.bind("192.168.2.23");
# bind to UNIX domain socket file "/tmp/socket" $sock.bind("/tmp/socket");
Table 4.399. Arguments for Socket::bind()
Argument | Type | Description |
---|---|---|
| Integer | A single integer will be taken as a port number on the local machine; all network interfaces will be bound with this port number. |
| String | 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. |
| String | 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. |
| Boolean | If this optional argument evaluates to True, the SO_REUSEADDR option will be set on the socket, which will allow the socket to be bound to a port that is not yet closed (for example, in a TIME_WAIT state). |
Table 4.400. Return Values for Socket::bind()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Table 4.401. Exceptions Thrown by Socket::bind()
err | desc |
---|---|
| No argument was passed to the method. |
Accepts connections on a listening socket (see Socket::listen()).
Socket::accept()
$new_socket = $sock.accept();
Table 4.402. Arguments for Socket::accept()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.403. Return Values for Socket::accept()
Return Type | Description |
---|---|
Socket Object | 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.
Socket::acceptSSL()
$new_sock = $sock.acceptSSL();
EVENT_START_SSL, EVENT_SSL_ESTABLISHED
Table 4.405. Arguments for Socket::acceptSSL()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.406. Return Values for Socket::acceptSSL()
Return Type |
Description |
---|---|
Object |
A new socket object is returned for the new connection. |
Table 4.407. Exceptions thrown by Socket::acceptSSL()
err |
desc |
---|---|
|
An error occurred establishing the TLS/SSL connection. |
Connects the socket to a remote 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.
Socket::connect(string:host_and_port, [timeout_ms]
)
Socket::connect(string:filename
)
$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.408. Arguments for Socket::connect()
Argument | Type | Description |
---|---|---|
| String, Integer or Relative Date/Time | If a colon appears in the string, the string will be assumed to be a hostname:port specification to connect to. If a timeout value is passed and the connection takes longer to establish than the timeout, an exception is thrown. |
| String | 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. |
Table 4.409. Return Values for Socket::connect()
Return Type | Description |
---|---|
n/a | This method does not return any value; if an error occurs, an exception is thrown. |
Table 4.410. Exceptions Thrown by Socket::connect()
err | desc |
---|---|
| No argument was passed to the method. |
| An error occured connecting to the remote socket (cannot resolve hostname, no listener, timeout exceeded, etc). |
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.
Socket::connectSSL(remote, [timeout_ms]
)
$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.411. Arguments for Socket::connectSSL()
Argument |
Type |
Description |
---|---|---|
| String | The remote socket, i.e. 'hostname:port', 'filename' (for UNIX domain sockets), etc. |
| Integer or Date/Time | An optional timeout value for the connection; if the connection cannot be established in the timeout period, an exception is thrown. |
Table 4.412. Return Values for Socket::connectSSL()
Return Type |
Description |
---|---|
n/a |
This method returns no value; if an error occurs, an exception is thrown. |
Table 4.413. Exceptions thrown by Socket::connectSSL()
err |
desc |
---|---|
|
missing remote socket |
| 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()
$sock.listen();
Table 4.414. Arguments for Socket::listen()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.415. Return Values for Socket::listen()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Shuts down the SSL connection on a secure connection.
Socket::shutdownSSL()
$sock.shutdownSSL();
Table 4.417. Arguments for Socket::shutdownSSL()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.418. Return Values for Socket::shutdownSSL()
Return Type |
Description |
---|---|
Integer |
Returns 0 if successful. |
Table 4.419. 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.
Socket::getSSLCipherName()
$str = $sock.getSSLCipherName();
Table 4.420. Arguments for Socket::getSSLCipherName()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.421. Return Values for Socket::getSSLCipherName()
Return Type |
Description |
---|---|
String |
The name of the cipher for an encrypted connection. |
Returns the version string of the cipher for encrypted connections.
Socket::getSSLCipherVersion()
$str = $sock.getSSLCipherVersion();
Table 4.422. Arguments for Socket::getSSLCipherVersion()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.423. Return Values for Socket::getSSLCipherVersion()
Return Type |
Description |
---|---|
String |
The version string of the cipher for encrypted connections. |
Returns True if the connection is a secure TLS/SSL connection.
Socket::isSecure()
$bool = $sock.isSecure();
Table 4.424. Arguments for Socket::isSecure()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.425. Return Values for Socket::isSecure()
Return Type |
Description |
---|---|
Boolean |
True if the connection is encrypted. |
Returns True if the socket is open.
Socket::isOpen()
$bool = $sock.isOpen();
Table 4.426. Arguments for Socket::isOpen()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.427. Return Values for Socket::isOpen()
Return Type |
Description |
---|---|
Boolean |
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.
Socket::setCertificate(certificate
)
$sock.setCertificate($cert);
Table 4.428. Arguments for Socket::setCertificate()
Argument |
Type |
Description |
---|---|---|
|
SSLCertificate Object |
This must be an SSL Certificate object. |
Table 4.429. Return Values for Socket::setCertificate()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
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.
Socket::setPrivateKey(private_key_object
)
$sock.setPrivateKey($pkey);
Table 4.430. Arguments for Socket::setPrivateKey()
Argument |
Type |
Description |
---|---|---|
|
SSLPrivateKey Object |
The private key for the certificate. |
Table 4.431. Return Values for Socket::setPrivateKey()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
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()
$str = $sock.verifyPeerCertificate();
Table 4.432. Arguments for Socket::verifyPeerCertificate()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.433. Return Values for Socket::verifyPeerCertificate()
Return Type |
Description |
---|---|
String |
A string code giving the result of verifying the peer's certificate. No value is returned if no secure connection has been established. |
Sets a Queue object to receive socket events. To remove the event queue and stop monitoring socket events, pass NOTHING
to the method. See Event Handling for more information.
Socket::setEventQueue([queue]
)
$sock.setEventQueue($queue);
Table 4.435. Return Values for Socket::setEventQueue()
Return Type |
Description |
---|---|
n/a | This method does not return any value. |
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([timeout_ms]
)
$bool = $sock.isDataAvailable(0); # returns True if data is available now
Table 4.436. Arguments for Socket::isDataAvailable()
Argument | Type | Description |
---|---|---|
| Integer | An optional timeout in milliseconds (1/1000 second). If no timeout is given, the method returns immediately. |
Table 4.437. Return Values for Socket::isDataAvailable()
Return Type | Description |
---|---|
Boolean | True if data is available on the socket, False if not. |
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([timeout_ms]
)
$bool = $sock.isWriteFinished(0);
Table 4.438. Arguments for Socket::isWriteFinished()
Argument | Type | Description |
---|---|---|
| Integer | An optional timeout in milliseconds (1/1000 second). If no timeout is given, the method returns immediately. |
Table 4.439. Return Values for Socket::isWriteFinished()
Return Type | Description |
---|---|
Boolean | True if data is available on the socket, False if not. |
Sends string or binary data over a connected socket. If the argument is not present, or is neither a String or Binary type, an exception will be thrown. String data will be converted to the encoding set for the socket if necessary.
Socket::send(data
)
$sock.send($data);
EVENT_PACKET_SENT
Table 4.440. Arguments for Socket::send()
Argument | Type | Description |
---|---|---|
| String | Sends the string data over the socket without the trailing null ('\0') character. |
| Binary | Sends the binary data over the socket. |
Table 4.441. Return Values for Socket::send()
Return Type | Description |
---|---|
Integer | 0 for success, -1 for error. |
Table 4.442. Exceptions Thrown by Socket::send()
err | desc |
---|---|
| No argument was passed to the method. |
| The socket is not connected. |
Sends a 1-byte integer over the socket.
Socket::sendi1(integer
)
$sock.sendi1($val);
EVENT_PACKET_SENT
Table 4.443. Arguments for Socket::sendi1()
Argument | Type | Description |
---|---|---|
| Integer | The integer to send; only the least-significant byte will be sent. |
Table 4.444. Return Values for Socket::sendi1()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Table 4.445. 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.
Socket::sendi2(integer
)
$sock.sendi2($val);
EVENT_PACKET_SENT
Table 4.446. Arguments for Socket::sendi2()
Argument | Type | Description |
---|---|---|
| Integer | The integer to send; only the least-significant 2-bytes will be sent. |
Table 4.447. Return Values for Socket::sendi2()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Table 4.448. 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.
Socket::sendi4(integer
)
$sock.sendi4($val);
EVENT_PACKET_SENT
Table 4.449. Arguments for Socket::sendi4()
Argument | Type | Description |
---|---|---|
| Integer | The integer to send; only the least-significant 4-bytes will be sent. |
Table 4.450. Return Values for Socket::sendi4()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Table 4.451. 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.
Socket::sendi8(integer
)
$sock.sendi8($val);
EVENT_PACKET_SENT
Table 4.452. Arguments for Socket::sendi8()
Argument | Type | Description |
---|---|---|
| Integer | The integer to send. |
Table 4.453. Return Values for Socket::sendi8()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Table 4.454. Exceptions Thrown by Socket::sendi8()
err | desc |
---|---|
| The socket is not connected. |
Sends a 2-byte integer in little-endian format over the socket.
Socket::sendi2LSB(integer
)
$sock.sendi2LSB($val);
EVENT_PACKET_SENT
Table 4.455. Arguments for Socket::sendi2LSB()
Argument | Type | Description |
---|---|---|
| Integer | The integer to send; only the least-significant 2-bytes will be sent. |
Table 4.456. Return Values for Socket::sendi2LSB()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Table 4.457. Exceptions Thrown by Socket::sendi2LSB()
err | desc |
---|---|
| The socket is not connected. |
Sends a 4-byte integer in little-endian format over the socket.
Socket::sendi4LSB(integer
)
$sock.sendi4LSB($val);
EVENT_PACKET_SENT
Table 4.458. Arguments for Socket::sendi4LSB()
Argument | Type | Description |
---|---|---|
| Integer | The integer to send; only the least-significant 4-bytes will be sent. |
Table 4.459. Return Values for Socket::sendi4LSB()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Table 4.460. 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.
Socket::sendi8LSB(integer
)
$sock.sendi8LSB($val);
EVENT_PACKET_SENT
Table 4.461. Arguments for Socket::sendi8LSB()
Argument | Type | Description |
---|---|---|
| Integer | The integer to send. |
Table 4.462. Return Values for Socket::sendi8LSB()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Table 4.463. 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, [body]
)
$sock.sendHTTPMessage("POST", "/RPC2", "1.1", ("Content-Type" : "text/xml"), $xml);
EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE
Table 4.464. Arguments for Socket::sendHTTPMessage()
Argument | Type | Description |
---|---|---|
| String | The HTTP method name to send (i.e. POST, HEAD, etc) |
| String | The path component of the URL. |
| String | The HTTP protocol version (1.0 or 1.1). |
| Hash | A hash of additional headers to send (key-value pairs). |
| String | If present, the body to be sent with the message (if present, the Content-Length header will be automatically set). |
| Binary | If present, the body to be sent with the message (if present, the Content-Length header will be automatically set). |
Table 4.465. Return Values for Socket::sendHTTPMessage()
Return Type | Description |
---|---|
n/a | This method returns no value. If any errors occur, exceptions are raised. |
Table 4.466. 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(status_code, string:description, string:http_version, hash:headers, [body]
)
$sock.sendHTTPResponse(200, "OK", "1.1", ("Connection":"Keep-Alive"));
EVENT_PACKET_SENT, EVENT_HTTP_SEND_MESSAGE
Table 4.467. Arguments for Socket::sendHTTPMessage()
Argument | Type | Description |
---|---|---|
| Integer | The HTTP status code to send (i.e. 200, 404, etc) |
| String | The descriptive text for the status code. |
| String | The HTTP protocol version (1.0 or 1.1). |
| Hash | A hash of additional headers to send (key-value pairs). |
| String | If present, the body to be sent with the message (if present, the Content-Length header will be automatically set). |
| Binary | If present, the body to be sent with the message (if present, the Content-Length header will be automatically set). |
Table 4.468. Return Values for Socket::sendHTTPResponse()
Return Type | Description |
---|---|
n/a | This method returns no value. If any errors occur, exceptions are raised. |
Table 4.469. 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.
Socket::recv(size, [timeout_ms]
)
$data = $sock.recv(-1); # read all data available
EVENT_PACKET_READ
Table 4.470. Arguments for Socket::recv()
Argument | Type | Description |
---|---|---|
| Integer | The amount of data to read in bytes. To read until the remote closes the connection, use -1. |
| Integer | 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.471. Return Values for Socket::recv()
Return Type | Description |
---|---|
String | The data read, returned as a string. |
Table 4.472. 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.
Socket::recvBinary(size, [timeout_ms]
)
$bin = $sock.recvBinary(-1); # read all data available
EVENT_PACKET_READ
Table 4.473. Arguments for Socket::recvBinary()
Argument | Type | Description |
---|---|---|
| Integer | The amount of data to read in bytes. To read until the remote closes the connection, use -1. |
| Integer | 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.474. Return Values for Socket::recvBinary()
Return Type | Description |
---|---|
Binary | The data read, returned as a binary object. |
Table 4.475. 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.
Socket::recvi1([timeout_ms]
)
$int = $sock.recvi1();
EVENT_PACKET_READ
Table 4.476. Arguments for Socket::recvi1()
Argument | Type | Description |
---|---|---|
| Integer | 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.477. Return Values for Socket::recvi1()
Return Type | Description |
---|---|
Integer | The 1-byte signed integer read. |
Table 4.478. 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.
Socket::recvi2([timeout_ms]
)
$int = $sock.recvi2();
EVENT_PACKET_READ
Table 4.479. Arguments for Socket::recvi2()
Argument | Type | Description |
---|---|---|
| Integer | 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.480. Return Values for Socket::recvi2()
Return Type | Description |
---|---|
Integer | The 2-byte signed integer read. |
Table 4.481. 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.
Socket::recvi4([timeout_ms]
)
$int = $sock.recvi4();
EVENT_PACKET_READ
Table 4.482. Arguments for Socket::recvi4()
Argument | Type | Description |
---|---|---|
| Integer | 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.483. Return Values for Socket::recvi4()
Return Type | Description |
---|---|
Integer | The 4-byte signed integer read. |
Table 4.484. 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.
Socket::recvi8([timeout_ms]
)
$int = $sock.recvi8();
EVENT_PACKET_READ
Table 4.485. Arguments for Socket::recvi8()
Argument | Type | Description |
---|---|---|
| Integer | 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.486. Return Values for Socket::recvi8()
Return Type | Description |
---|---|
Integer | The 8-byte (64-bit) signed integer read. |
Table 4.487. 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.
Socket::recvi2LSB([timeout_ms]
)
$int = $sock.recvi2LSB();
EVENT_PACKET_READ
Table 4.488. Arguments for Socket::recvi2LSB()
Argument | Type | Description |
---|---|---|
| Integer | 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.489. Return Values for Socket::recvi2LSB()
Return Type | Description |
---|---|
Integer | The 2-byte signed integer read. |
Table 4.490. 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.
Socket::recvi4LSB([timeout_ms]
)
$int = $sock.recvi4LSB(1250ms); # timeout in 1.25 seconds
EVENT_PACKET_READ
Table 4.491. Arguments for Socket::recvi4LSB()
Argument | Type | Description |
---|---|---|
| Integer | 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.492. Return Values for Socket::recvi4LSB()
Return Type | Description |
---|---|
Integer | The 4-byte signed integer read. |
Table 4.493. 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.
Socket::recvi8LSB([timeout_ms]
)
$int = $sock.recvi8LSB();
EVENT_PACKET_READ
Table 4.494. Arguments for Socket::recvi8LSB()
Argument | Type | Description |
---|---|---|
| Integer | 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.495. Return Values for Socket::recvi8LSB()
Return Type | Description |
---|---|
Integer | The 8-byte (64-bit) signed integer read. |
Table 4.496. 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.
Socket::recvu1([timeout_ms]
)
$int = $sock.recvu1();
EVENT_PACKET_READ
Table 4.497. Arguments for Socket::recvu1()
Argument | Type | Description |
---|---|---|
| Integer | 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.498. Return Values for Socket::recvu1()
Return Type | Description |
---|---|
Integer | The 1-byte unsigned integer read. |
Table 4.499. 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.
Socket::recvu2([timeout_ms]
)
$int = $sock.recvu2();
EVENT_PACKET_READ
Table 4.500. Arguments for Socket::recvu2()
Argument | Type | Description |
---|---|---|
| Integer | 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.501. Return Values for Socket::recvu2()
Return Type | Description |
---|---|
Integer | The 2-byte unsigned integer read. |
Table 4.502. 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.
Socket::recvu4([timeout_ms]
)
$int = $sock.recvu4();
EVENT_PACKET_READ
Table 4.503. Arguments for Socket::recvu4()
Argument | Type | Description |
---|---|---|
| Integer | 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.504. Return Values for Socket::recvu4()
Return Type | Description |
---|---|
Integer | The 4-byte unsigned integer read. |
Table 4.505. 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.
Socket::recvu2LSB([timeout_ms]
)
$int = $sock.recvu2LSB();
EVENT_PACKET_READ
Table 4.506. Arguments for Socket::recvu2LSB()
Argument | Type | Description |
---|---|---|
| Integer | 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.507. Return Values for Socket::recvu2LSB()
Return Type | Description |
---|---|
Integer | The 2-byte unsigned integer read. |
Table 4.508. 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.
Socket::recvu4LSB([timeout_ms]
)
$int = $sock.recvu4LSB();
EVENT_PACKET_READ
Table 4.509. Arguments for Socket::recvu4LSB()
Argument | Type | Description |
---|---|---|
| Integer | 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.510. Return Values for Socket::recvu4LSB()
Return Type | Description |
---|---|
Integer | The 4-byte unsigned integer read. |
Table 4.511. 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. 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.512. 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([timeout_ms]
)
$hash = $sock.readHTTPHeader();
EVENT_PACKET_READ, EVENT_HTTP_MESSAGE_RECEIVED
Table 4.513. Arguments for Socket::readHTTPHeader()
Argument | Type | Description |
---|---|---|
| Integer | 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.514. Return Values for Socket::readHTTPHeader()
Return Type | Description |
---|---|
Hash | 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: status_code, status_message. For outgoing HTTP messages, the following keys will be populated: method, path. |
Table 4.515. 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()
$port = $sock.getPort();
Table 4.516. Arguments for Socket::getPort()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.517. Return Values for Socket::getPort()
Return Type | Description |
---|---|
Integer | 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()).
Socket::shutdown()
$sock.shutdown();
Table 4.518. Arguments for Socket::shutdown()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.519. Return Values for Socket::shutdown()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Closes an open socket. Also deletes the UNIX domain socket file if it was created by a call to Socket::bind()
Socket::close()
$sock.close();
EVENT_CHANNEL_CLOSED
Table 4.520. Arguments for Socket::close()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.521. Return Values for Socket::close()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Returns the character encoding for the socket.
Socket::getCharset()
$enc = $sock.getCharset();
Table 4.522. Arguments for Socket::getCharset()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.523. Return Value for Socket::getCharset()
Return Type | Description |
---|---|
String | 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
)
$sock.setCharset("ISO-8859-1");
Table 4.524. Arguments for Socket::setCharset()
Argument | Type | Description |
---|---|---|
| String | The character encoding for the socket. |
Table 4.525. Return Value for Socket::setCharset()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Returns the TCP_NODELAY
setting for the socket. See also Socket::setNoDelay().
Socket::getNoDelay()
$nodelay = $sock.getNoDelay();
Table 4.526. Arguments for Socket::getNoDelay()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.527. Return Value for Socket::getNoDelay()
Return Type | Description |
---|---|
Boolean | 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(boolean
)
$sock.setNoDelay(True);
Table 4.528. Arguments for Socket::setNoDelay()
Argument | Type | Description |
---|---|---|
| boolean | The |
Table 4.529. Return Value for Socket::setNoDelay()
Return Type | Description |
---|---|
Integer | 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()
$sock = $sock.getSocket();
Table 4.530. Arguments for Socket::getSocket()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.531. Return Values for Socket::getSocket()
Return Type | Description |
---|---|
Integer | 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.532. 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.533. 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.534. 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.535. 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.536. 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. | |
Y | Sets 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. 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 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 response. 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 optionally the 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 True, or an unencrypted cleartext connection if it is not True or if no argument is passed. This method overrides the default behaviour for the protocol set for the object. | |
N |
Returns True if the current connection is encrypted, False if not. | |
N |
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. | |
N |
Returns the name of the cipher for an encrypted connection. | |
N |
Returns the version of the cipher for an encrypted connection. | |
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. | |
N | Returns the | |
N | Sets the | |
N | Returns True or False giving the current connection state. |
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().
new HTTPClient([opts]
)
$httpclient = new HTTPClient(("url":"http://hostname:8080/path"));
Table 4.537. Arguments for HTTPClient::constructor()
Argument |
Type |
Description |
---|---|---|
|
Hash |
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.538. 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.539. Return Values for HTTPClient::constructor()
Return Type |
Description |
---|---|
Object |
The HTTPClient object is returned |
Table 4.540. 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 lvalue
delete $httpclient;
EVENT_CHANNEL_CLOSED, EVENT_DELETED
Table 4.541. Arguments for HTTPClient::destructor()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.542. Return Values for HTTPClient::destructor()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Copying objects of this class is not supported, an exception will be thrown.
Table 4.543. Arguments for HTTPClient::copy()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.544. Return Values for HTTPClient::copy()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Table 4.545. 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()
$url = $httpclient.getURL();
Table 4.546. Arguments for HTTPClient::getURL()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Sets the URL value for the object. To retrieve the current URL value, use the HTTPClient::getURL() method.
HTTPClient::setURL(url
)
$httpclient.setURL("https://user:password@hostname:8080/path");
Table 4.548. Arguments for HTTPClient::setURL()
Argument | Type | Description |
---|---|---|
| String | The new URL for the object. |
Table 4.549. Return Values for HTTPClient::set()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Table 4.550. 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()
$proxy_url = $httpclient.getProxyURL();
Table 4.551. Arguments for HTTPClient::getProxyURL()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.552. Return Values for HTTPClient::getProxyURL()
Return Type | Description |
---|---|
String | The current proxy URL value. |
Sets the proxy URL value for the object. To retrieve the current URL value, use the HTTPClient::getProxyURL() method.
HTTPClient::setProxyURL(url
)
$httpclient.setProxyURL("http://user:password@proxy_host:8080/path");
Table 4.553. Arguments for HTTPClient::setProxyURL()
Argument | Type | Description |
---|---|---|
| String | The new proxy URL for the object. |
Table 4.554. Return Values for HTTPClient::setProxyURL()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Table 4.555. 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()
$httpclient.clearProxyURL();
Table 4.556. Arguments for HTTPClient::clearProxyURL()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.557. Return Values for HTTPClient::clearProxyURL()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Sets the SSL/TLS flag for the next proxy connection. To check the flag, use the HTTPClient::isProxySecure() method.
HTTPClient::setProxySecure(boolean
)
$httpclient.setProxySecure(True);
Table 4.558. Arguments for HTTPClient::setProxySecure()
Argument | Type | Description |
---|---|---|
| Boolean | sets the SSL/TLS flag for the next proxy connection |
Table 4.559. Return Values for HTTPClient::setProxySecure()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Returns the SSL/TLS flag for proxy connection. To set the flag, use the HTTPClient::setProxySecure() method.
HTTPClient::isProxySecure()
$bool = $httpclient.isProxySecure();
Table 4.560. Arguments for HTTPClient::isProxySecure()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.561. Return Values for HTTPClient::isProxySecure()
Return Type | Description |
---|---|
Boolean | 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()
$num = $httpclient.getMaxRedirects();
Table 4.562. Arguments for HTTPClient::getMaxRedirects()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.563. Return Values for HTTPClient::getMaxRedirects()
Return Type | Description |
---|---|
Integer | 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(max_redirects
)
$httpclient.setMaxRedirects(0); # disable redirections
Table 4.564. Arguments for HTTPClient::setMaxRedirects()
Argument | Type | Description |
---|---|---|
| Integer | The maximum number of HTTP redirects allowed for hte object before an exception is thrown. |
Table 4.565. Return Values for HTTPClient::setMaxRedirects()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
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()
$httpclient.connect();
EVENT_CONNECTING, EVENT_CONNECTED,EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED
Table 4.566. Arguments for HTTPClient::connect()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.567. Return Values for HTTPClient::connect()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Table 4.568. 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()
$httpclient.disconnect();
EVENT_CHANNEL_CLOSED
Table 4.569. Arguments for HTTPClient::disconnect()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.570. Return Values for HTTPClient::disconnect()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
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(path, [headers], [info_reference]
)
$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.571. Arguments for HTTPClient::get()
Argument |
Type |
Description |
---|---|---|
|
String |
The path for the message (i.e. '/path/resource?method¶m=value') |
| Hash | An optional hash of headers to include in the message. |
| LValue Reference | 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.572. Return Values for HTTPClient::get()
Return Type |
Description |
---|---|
String |
The message body returned. |
Table 4.573. 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(path, [headers]
)
$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.574. Arguments for HTTPClient::head()
Argument |
Type |
Description |
---|---|---|
|
String |
The path for the message (i.e. '/path/resource?method¶m=value') |
|
Hash |
An optional hash of headers to include in the message. |
Table 4.575. Return Values for HTTPClient::head()
Return Type |
Description |
---|---|
Hash |
The headers received from the HTTP server with all key names converted to lower-case. |
Table 4.576. 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 the HTTPClient::send() method instead. If necessary, a connection will be established via an implicit call to HTTPClient::connect() before sending the message.
HTTPClient::post(path, message, [headers], [info_reference]
)
Table 4.577. Arguments for HTTPClient::post()
Argument |
Type |
Description |
---|---|---|
|
String |
The path for the message (i.e. '/path/resource?method¶m=value') |
|
String or Binary |
The message body to send. |
|
Hash |
An optional hash of headers to include in the message. |
| LValue Reference | 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.578. Return Values for HTTPClient::post()
Return Type |
Description |
---|---|
String |
The message body returned. |
Table 4.579. 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(message, method, path, [headers], [get_body], [info_reference]
)
$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.580. Arguments for HTTPClient::send()
Argument |
Type |
Description |
---|---|---|
|
String or Binary |
The message body to send. |
|
String |
The name of the HTTP method ( |
|
String |
The path for the message (i.e. '/path/resource?method¶m=value') |
|
Hash |
An optional hash of headers to include in the message. |
|
Boolean |
if set to True (default is False), then even if the server did not return a 'Content-Length' header in the response, the object will try to read a message body from the socket anyway. Use this only with broken servers that send messages bodies without a 'Content-Length' header. |
| LValue Reference | 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.581. Return Values for HTTPClient::send()
Return Type |
Description |
---|---|
Hash |
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.582. 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(timeout
)
$httpclient.setConnectTimeout(2m); # sets timeout to 2 minutes
Table 4.583. Arguments for HTTPClient::setConnectTimeout()
Argument |
Type |
Description |
---|---|---|
|
Integer or Relative Date/Time |
Connect timeout in milliseconds, 0 = immediate timeout (do not use), negative numbers = use system default connect timeout. |
Table 4.584. Return Values for HTTPClient::setConnectTimeout()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
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(timeout
)
$httpclient.setTimeout(2m); # sets timeout to 2 minutes
Table 4.585. Arguments for HTTPClient::setTimeout()
Argument |
Type |
Description |
---|---|---|
|
Integer or Relative Date/Time |
Read timeout in milliseconds, 0 = immediate timeout, negative numbers = never timeout. |
Table 4.586. Return Values for HTTPClient::setTimeout()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Returns the connect timeout as an integer in milliseconds. Negative numbers mean the default system timeout is used instead.
HTTPClient::getConnectTimeout()
$timeout = $httpclient.getConnectTimeout();
Table 4.587. Arguments for HTTPClient::getConnectTimeout()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.588. Return Values for HTTPClient::getConnectTimeout()
Return Type |
Description |
---|---|
Integer |
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()
$timeout = $httpclient.getTimeout();
Table 4.589. Arguments for HTTPClient::getTimeout()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.590. Return Values for HTTPClient::getTimeout()
Return Type |
Description |
---|---|
Integer |
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(version
)
$httpclient.setHTTPVersion("1.1");
Table 4.591. Arguments for HTTPClient::setHTTPVersion()
Argument |
Type |
Description |
---|---|---|
|
String |
either '1.0' or '1.1' for the HTTP protocol compliance version. |
Table 4.592. Return Values for HTTPClient::setHTTPVersion()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Table 4.593. 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()
$version = $httpclient.getHTTPVersion();
Table 4.594. Arguments for HTTPClient::getHTTPVersion()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.595. Return Values for HTTPClient::getHTTPVersion()
Return Type |
Description |
---|---|
String |
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 not True or if no argument is passed. This method overrides the default behaviour for the protocol set for the object.
HTTPClient::setSecure([secure]
)
$httpclient.setSecure(True);
Table 4.596. Arguments for HTTPClient::setSecure()
Argument |
Type |
Description |
---|---|---|
|
Boolean |
If True, a SSL/TLS connection will be attempted on the next connection. If not True or missing, an unencrypted cleartext connection will be established. |
Table 4.597. Return Values for HTTPClient::setSecure()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Returns True if the current connection is encrypted, False if not.
HTTPClient::isSecure()
$bool = $httpclient.isSecure();
Table 4.598. Arguments for HTTPClient::isSecure()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.599. Return Values for HTTPClient::isSecure()
Return Type |
Description |
---|---|
Boolean |
Returns True if the current connection is encrypted, False if not. |
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.
HTTPClient::verifyPeerCertificate()
$str = $httpclient.verifyPeerCertificate();
Table 4.600. Arguments for HTTPClient::verifyPeerCertificate()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.601. Return Values for HTTPClient::verifyPeerCertificate()
Return Type |
Description |
---|---|
String |
A string code giving the result of verifying the peer's certificate. No value is returned if no secure connection has been established. |
Returns the name of the cipher for an encrypted connection.
HTTPClient::getSSLCipherName()
$str = $httpclient.getSSLCipherName();
Table 4.602. Arguments for HTTPClient::getSSLCipherName()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.603. Return Values for HTTPClient::getSSLCipherName()
Return Type |
Description |
---|---|
String |
The name of the cipher for a secure connection. No value is returned if no secure connection has been established. |
Returns the version of the cipher for an encrypted connection.
HTTPClient::getSSLCipherVersion()
$str = $httpclient.getSSLCipherVersion();
Table 4.604. Arguments for HTTPClient::getSSLCipherVersion()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.605. Return Values for HTTPClient::getSSLCipherVersion()
Return Type |
Description |
---|---|
String |
The version of the cipher for a secure connection. No value is returned if no secure connection has been established. |
Sets the string encoding for the object; any strings deserialized with this object will be tagged with this character encoding.
HTTPClient::setEncoding(encoding
)
$httpclient.setEncoding("ISO-8859-1");
Table 4.606. Arguments for HTTPClient::setEncoding()
Argument |
Type |
Description |
---|---|---|
|
String |
The string encoding to use for this object. |
Table 4.607. Return Values for HTTPClient::setEncoding()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Table 4.608. Exceptions thrown by HTTPClient::setEncoding()
err |
desc |
---|---|
|
missing encoding parameter from method call |
Returns the character encoding used for the object
HTTPClient::getEncoding()
$str = $httpclient.getEncoding();
Table 4.609. Arguments for HTTPClient::getEncoding()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.610. Return Values for HTTPClient::getEncoding()
Return Type |
Description |
---|---|
String |
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([queue]
)
$httpclient.setEventQueue($queue);
Table 4.612. Return Values for HTTPClient::setEventQueue()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Returns the TCP_NODELAY
setting for the HTTPClient object. See also HTTPClient::setNoDelay().
HTTPClient::getNoDelay()
$nodelay = $httpclient.getNoDelay();
Table 4.613. Arguments for HTTPClient::getNoDelay()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.614. Return Value for HTTPClient::getNoDelay()
Return Type | Description |
---|---|
Boolean | 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(boolean
)
$httpclient.setNoDelay(True);
Table 4.615. Arguments for HTTPClient::setNoDelay()
Argument | Type | Description |
---|---|---|
| boolean | The |
Table 4.616. Return Value for HTTPClient::setNoDelay()
Return Type | Description |
---|---|
Integer | 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()
$connected = $httpclient.isConnected();
Table 4.617. Arguments for HTTPClient::isConnected()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.618. Return Value for HTTPClient::isConnected()
Return Type | Description |
---|---|
Boolean | 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.619. 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.620. XmlRpcClient Default, but Overridable Headers
Header | Default Value |
---|---|
|
|
|
|
|
|
|
|
Table 4.621. 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. |
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.
new XmlRpcClient([opts, noconnect]
)
$xrc = new XmlRpcClient(("url":"http://hostname/RPC2"));
Table 4.622. Arguments for XmlRpcClient::constructor()
Argument |
Type |
Description |
---|---|---|
|
Hash |
an option hash, see HTTPClient::constructor() Option Hash Keys for valid keys in this hash. |
| Boolean | If this optional argument is passed with a value of True, then the object will not attempt to make a connection immediately to the remote socket, but instead will wait until a connection is required or manually established with the parent class' HTTPClient::connect() method. |
Table 4.623. Return Values for XmlRpcClient::constructor()
Return Type |
Description |
---|---|
Object |
The XmlRpcClient object is returned |
Destroys the XmlRpcClient object and closes any open connections.
delete lvalue
delete $xrc;
Table 4.624. Arguments for XmlRpcClient::destructor()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.625. Return Values for XmlRpcClient::destructor()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Copying objects of this class is not supported, an exception will be thrown.
Table 4.626. Arguments for XmlRpcClient::copy()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.627. Return Values for XmlRpcClient::copy()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Table 4.628. 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(method_name, [args...]
)
$result = $xrc.call("method.name", $arg1, $arg2);
Table 4.629. Arguments for XmlRpcClient::call()
Argument |
Type |
Description |
---|---|---|
|
String |
The XML-RPC method name to call |
|
Any |
Optional arguments for the method. |
Table 4.630. Return Values for XmlRpcClient::call()
Return Type |
Description |
---|---|
Hash |
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(method_name, [arg_list]
)
$result = $xrc.callArgs("method.name", $arg_list);
Table 4.631. Arguments for XmlRpcClient::callArgs()
Argument |
Type |
Description |
---|---|---|
|
String |
The XML-RPC method name to call |
|
List or Any |
An optional list (or single value) of arguments for the method. |
Table 4.632. Return Values for XmlRpcClient::callArgs()
Return Type |
Description |
---|---|
Hash |
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(lvalue_ref, method_name, [args...]
)
$result = $xrc.callWithInfo(\$info, "method.name", $arg1, $arg2);
Table 4.633. Arguments for XmlRpcClient::callWithInfo()
Argument |
Type |
Description |
---|---|---|
| LValue Reference | 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. |
|
String |
The XML-RPC method name to call |
|
Any |
Optional arguments for the method. |
Table 4.634. Return Values for XmlRpcClient::callWithInfo()
Return Type |
Description |
---|---|
Hash |
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(lvalue_ref, method_name, [arg_list]
)
$result = $xrc.callArgsWithInfo(\$info, "method.name", $arg_list);
Table 4.635. Arguments for XmlRpcClient::callArgsWithInfo()
Argument |
Type |
Description |
---|---|---|
| LValue Reference | 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. |
|
String |
The XML-RPC method name to call |
|
List or Any |
An optional list (or single value) of arguments for the method. |
Table 4.636. Return Values for XmlRpcClient::callArgswithInfo()
Return Type |
Description |
---|---|
Hash |
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. |
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.637. 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.638. JsonRpcClient Default, but Overridable Headers
Header | Default Value |
---|---|
|
|
|
|
|
|
|
|
Table 4.639. 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. | |
N |
Calls a remote method using a variable number of arguments for the method arguments and returns the response as qore data structure. | |
N |
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. |
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.
new JsonRpcClient([opts, noconnect]
)
$jrc = new JsonRpcClient(("url":"http://hostname/json"));
Table 4.640. Arguments for JsonRpcClient::constructor()
Argument | Type | Description |
---|---|---|
| Hash | an option hash, see HTTPClient::constructor() Option Hash Keys for valid keys in this hash. |
| Boolean | If this optional argument is passed with a value of True, then the object will not attempt to make a connection immediately to the remote socket, but instead will wait until a connection is required or manually established with the parent class' HTTPClient::connect() method. |
Table 4.641. Return Values for JsonRpcClient::constructor()
Return Type |
Description |
---|---|
Object |
The JsonRpcClient object is returned |
Destroys the JsonRpcClient object and closes any open connections.
delete lvalue
delete $jrc;
Table 4.642. Arguments for JsonRpcClient::destructor()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.643. Return Values for JsonRpcClient::destructor()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Copying objects of this class is not supported, an exception will be thrown.
Table 4.644. Arguments for JsonRpcClient::copy()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.645. Return Values for JsonRpcClient::copy()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Table 4.646. 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(method_name, [arg1, arg2...
)
$result = $jrc.call("method_name", $arg1, $arg2);
Table 4.647. Arguments for JsonRpcClient::call()
Argument |
Type |
Description |
---|---|---|
|
String |
The JSON-RPC method name to call |
|
List or Any |
An optional list (or single value) of arguments for the method. |
Table 4.648. Return Values for JsonRpcClient::call()
Return Type |
Description |
---|---|
Hash |
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(method_name, [arg_list]
)
$result = $jrc.callArgs("method_name", $arg_list);
Table 4.649. Arguments for JsonRpcClient::callArgs()
Argument |
Type |
Description |
---|---|---|
|
String |
The JSON-RPC method name to call |
|
List or Any |
An optional list (or single value) of arguments for the method. |
Table 4.650. Return Values for JsonRpcClient::callArgs()
Return Type |
Description |
---|---|
Any |
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(lvalue_reference, method_name, [arg1, arg2...
)
$result = $jrc.callWithInfo(\$info, "method_name", $arg1, $arg2);
Table 4.651. Arguments for JsonRpcClient::callWithInfo()
Argument |
Type |
Description |
---|---|---|
| LValue Reference | 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. |
| String | The JSON-RPC method name to call |
|
List or Any |
An optional list (or single value) of arguments for the method. |
Table 4.652. Return Values for JsonRpcClient::callWithInfo()
Return Type |
Description |
---|---|
Hash |
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(lvalue_reference, method_name, [arg_list]
)
$result = $jrc.callArgsWithInfo(\$info, "method_name", $arg_list);
Table 4.653. Arguments for JsonRpcClient::callArgsWithInfo()
Argument |
Type |
Description |
---|---|---|
| LValue Reference | 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. |
|
String |
The JSON-RPC method name to call |
|
List or Any |
An optional list (or single value) of arguments for the method. |
Table 4.654. Return Values for JsonRpcClient::callArgsWithInfo()
Return Type |
Description |
---|---|
Any |
The information returned by the JSON-RPC method. |
SSLPrivateKey objects are containers for private key data.
Table 4.655. SSLPrivateKey Class Method Overview
Method |
Except? |
Description |
---|---|---|
Y |
Creates the SSLPrivateKey object from the filename argument passed. | |
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 filename argument passed.
new SSLPrivateKey(filename, [passphrase]
)
$pkey = new SSLPrivateKey("/etc/keys/key.pem");
Table 4.656. Arguments for SSLPrivateKey::constructor()
Argument |
Type |
Description |
---|---|---|
|
String |
The filename of the PEM-encoded private key file |
|
String |
The passphrase required to decrypt the private key |
Table 4.657. Return Values for SSLPrivateKey::constructor()
Return Type |
Description |
---|---|
Object |
The SSLPrivateKey object is returned |
Table 4.658. Exceptions thrown by SSLPrivateKey::constructor()
err |
desc |
---|---|
|
missing filename argument, can't open file, unable to parse file, etc |
Destroys the SSLPrivateKey object.
delete lvalue
delete $pkey;
Table 4.659. Arguments for SSLPrivateKey::destructor()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.660. Return Values for SSLPrivateKey::destructor()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Copying objects of this class is not supported, an exception will be thrown.
Table 4.661. 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()
$str = $pkey.getType();
Table 4.662. Arguments for SSLPrivateKey::getType()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.663. Return Values for SSLPrivateKey::getType()
Return Type |
Description |
---|---|
String |
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()
$int = $pkey.getVersion();
Table 4.664. Arguments for SSLPrivateKey::getVersion()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.665. Return Values for SSLPrivateKey::getVersion()
Return Type |
Description |
---|---|
Integer |
The version of the private key. |
Returns the bit length of the private key.
SSLPrivateKey::getBitLength()
$int = $pkey.getBitLength();
Table 4.666. Arguments for SSLPrivateKey::getBitLength()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.667. Return Values for SSLPrivateKey::getBitLength()
Return Type |
Description |
---|---|
Integer |
The bit length of the private key. |
Returns a hash of all information for the private key.
SSLPrivateKey::getInfo()
$hash = $pkey.getInfo();
Table 4.668. Arguments for SSLPrivateKey::getInfo()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.669. Return Values for SSLPrivateKey::getInfo()
Return Type |
Description |
---|---|
Hash |
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.670. SSLCertificate Class Method Overview
Method |
Except? |
Description |
---|---|---|
Y |
Creates the SSLCertificate object from the filename argument passed. | |
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. | |
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.
new SSLCertificate(string|binary
)
$cert = new SSLCertificate($pem_cert_string);
Table 4.671. Arguments for SSLCertificate::constructor()
Argument |
Type |
Description |
---|---|---|
|
String|Binary |
The certificate data in either PEM (string argument) or DER (binary argument) format. See above for the deprecated option of passing a filename argument. |
Table 4.672. Return Values for SSLCertificate::constructor()
Return Type |
Description |
---|---|
Object |
The SSLCertificate object is returned |
Table 4.673. Exceptions thrown by SSLCertificate::constructor()
err |
desc |
---|---|
|
missing or invalid argument, unable to parse file, etc |
Destroys the SSLCertificate object.
delete lvalue
delete $cert;
Table 4.674. Arguments for SSLCertificate::destructor()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.675. Return Values for SSLCertificate::destructor()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Copying objects of this class is not supported, an exception will be thrown.
Table 4.676. 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()
$pem_str = $cert.getPEM();
Table 4.677. Arguments for SSLCertificate::getPEM()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.678. Return Values for SSLCertificate::getPEM()
Return Type |
Description |
---|---|
String |
A string in PEM format representing the certificate. |
Returns the version of the certificate as an integer.
SSLCertificate::getVersion()
$int = $cert.getVersion();
Table 4.679. Arguments for SSLCertificate::getVersion()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.680. Return Values for SSLCertificate::getVersion()
Return Type |
Description |
---|---|
Integer |
The version of the certificate. |
Returns the signature type of the certificate.
SSLCertificate::getSignatureType()
$str = $cert.getSignatureType();
Table 4.681. Arguments for SSLCertificate::getSignatureType()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.682. Return Values for SSLCertificate::getSignatureType()
Return Type |
Description |
---|---|
String |
The signature type of the certificate. |
Returns a binary object representing the signature of the certificate.
SSLCertificate::getSignature()
$bin = $cert.getSignature();
Table 4.683. Arguments for SSLCertificate::getSignature()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.684. Return Values for SSLCertificate::getSignature()
Return Type |
Description |
---|---|
Binary |
The signature data for the certificate. |
Returns name of the public key algorithm of the certificate.
SSLCertificate::getPublicKeyAlgorithm()
$str = $cert.getPublicKeyAlgorithm();
Table 4.685. Arguments for SSLCertificate::getPublicKeyAlgorithm()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.686. Return Values for SSLCertificate::getPublicKeyAlgorithm()
Return Type |
Description |
---|---|
String |
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()
$bin = $cert.getPublicKey();
Table 4.687. Arguments for SSLCertificate::getPublicKey()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.688. Return Values for SSLCertificate::getPublicKey()
Return Type |
Description |
---|---|
Binary |
The public key of the certificate in DER format. |
Returns a hash of strings representing the subject information of the certificate.
SSLCertificate::getSubjectHash()
$hash = $cert.getSubjectHash();
Table 4.689. Arguments for SSLCertificate::getSubjectHash()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.690. Return Values for SSLCertificate::getSubjectHash()
Return Type |
Description |
---|---|
Hash |
Key-value pairs representing the subject information of the certificate. |
Returns a hash of strings representing the issuer information of the certificate.
SSLCertificate::getIssuerHash()
$hash = $cert.getIssuerHash();
Table 4.691. Arguments for SSLCertificate::getIssuerHash()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.692. Return Values for SSLCertificate::getIssuerHash()
Return Type |
Description |
---|---|
Hash |
Key-value pairs representing the issuer information of the certificate. |
Returns the integer serial number of the certificate.
SSLCertificate::getIssuerHash()
$hash = $cert.getIssuerHash();
Table 4.693. Arguments for SSLCertificate::getSerialNumber()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.694. Return Values for SSLCertificate::getSerialNumber()
Return Type |
Description |
---|---|
Integer |
The serial number of the certificate. |
Returns a hash of booleans representing the allowed purposes of the certificate.
SSLCertificate::getPurposeHash()
$hash = $cert.getPurposeHash();
Table 4.695. Arguments for SSLCertificate::getPurposeHash()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.696. Return Values for SSLCertificate::getPurposeHash()
Return Type |
Description |
---|---|
Hash |
Key-value pairs representing the allowed purposes of the certificate. |
Returns a date/time value representing the start date of the certificate.
SSLCertificate::getNotBeforeDate()
$date = $cert.getNotBeforeDate();
Table 4.697. Arguments for SSLCertificate::getNotBeforeDate()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.698. Return Values for SSLCertificate::getNotBeforeDate()
Return Type |
Description |
---|---|
Date |
The start date of the certificate. |
Returns a date/time value representing the end date of the certificate.
SSLCertificate::getNotAfterDate()
$date = $cert.getNotAfterDate();
Table 4.699. Arguments for SSLCertificate::getNotAfterDate()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.700. Return Values for SSLCertificate::getNotAfterDate()
Return Type |
Description |
---|---|
Date |
The end date of the certificate. |
Returns a hash of all information for the certificate.
SSLCertificate::getInfo()
$hash = $cert.getInfo();
Table 4.701. Arguments for SSLCertificate::getInfo()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.702. Return Values for SSLCertificate::getInfo()
Return Type |
Description |
---|---|
Hash |
Keys are 'version', 'serialNumber', 'subject', 'issuer', 'purposes', 'notBefore', 'notAfter', 'signatureType', 'signature', and 'publicKey' corresponding to the respective attributes of the certificate. |
Table 4.703. Database Driver Constants in the SQL Namespace
Constant | Description |
---|---|
| Indicates an Oracle database to Datasource::constructor() and DatasourcePool::constructor() |
| Indicates a MySQL database to Datasource::constructor() and DatasourcePool::constructor() |
| Indicates a PostgreSQL database to Datasource::constructor() and DatasourcePool::constructor() |
| Indicates a Sybase database to Datasource::constructor() and DatasourcePool::constructor() |
| Indicates a Microsoft SQL Server database to Datasource::constructor() and DatasourcePool::constructor() |
Table 4.704. 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.705. 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.
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 = $db.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() 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.706. 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. | |
N | Closes the connection to the database. | |
Y | Commits the transaction and releases the transaction lock. | |
Y | Rolls back the transaction and releases the transaction lock. | |
N | Turns autocommit on or off for this object. | |
Y | Executes SQL code on the DB connection. | |
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. | |
N | Sets the password parameter for the next open. | |
N | Returns the password parameter. | |
N | Sets the DB name parameter for the next open. | |
N | Returns the dbname parameter. | |
N | Sets the charset parameter for the next open. | |
N | Returns the DBI driver specific charset name for the current connection. | |
N | Returns the Qore charset name for the current connection. | |
N | Sets the hostname parameter for the next open. | |
N | Returns the hostname parameter. | |
N | Sets the port parameter for the next open. | |
N | Returns the port parameter. | |
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. | |
N | Returns the driver-specific client library version data. Not implemented by all drivers. |
Creates a Datasource object. The constructor requires the datasource type as the first argument
new Datasource(driver_name, [username], [password], [dbname], [charset_name], [hostname], [port]
)
$db = new Datasource(DSPGSQL, "user", "pass", "database", "utf8", "localhost", 5432);
Table 4.707. Arguments for Datasource::constructor()
Argument | Type | Description |
---|---|---|
| String | 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. |
| String | The user name for the new connection. Also see Datasource::setUserName() for a method that allows this parameter to be set after the constructor. |
| String | The password for the new connection. Also see Datasource::setPassword() for a method that allows this parameter to be set after the constructor. |
| String | The database name for the new connection. Also see Datasource::setDBName() for a method that allows this parameter to be set after the constructor. |
| String | 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. |
| String | The host name for the new connection (not used by some DBI drivers). Also see Datasource::setHostName() for a method that allows this parameter to be set after the constructor. |
| Integer | The port number for the new connection (not used by some DBI drivers). Also see Datasource::setPort() for a method that allows this parameter to be set after the constructor. |
Table 4.708. Return Values for Datasource::constructor()
Return Type | Description |
---|---|
Object | The Datasource object created |
Table 4.709. 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 lvalue
delete $db;
Table 4.710. 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.
Datasource::copy()
$new_ds = $db.copy();
Table 4.711. Arguments for Datasource::copy()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.712. Return Values for Datasource::copy()
Return Type | Description |
---|---|
Datasource Object | Returns a new Datasource object with the same driver as the original and copies of all the connection parameters. |
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()
$db.beginTransaction();
Table 4.713. Arguments for Datasource::beginTransaction()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.714. Return Values for Datasource::beginTransaction()
Return Type | Description |
---|---|
n/a | This method return no value. |
Table 4.715. 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.
Datasource::open()
$db.open();
Table 4.716. Arguments for Datasource::open()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.717. Return Values for Datasource::open()
Return Type | Description |
---|---|
Integer | Returns 0 for success, -1 for error. |
Table 4.718. 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.
Datasource::close()
$db.close();
Table 4.719. Arguments for Datasource::close()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.720. Return Values for Datasource::close()
Return Type | Description |
---|---|
Integer | 0 for success, -1 for not open. |
Commits the current transaction and releases the transaction lock.
Datasource::commit()
$db.commit();
Table 4.721. Arguments for Datasource::commit()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.722. Return Values for Datasource::commit()
Return Type | Description |
---|---|
Integer | 0 for success, -1 for not open. |
Table 4.723. 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. |
Rolls back the current transaction and releases the transaction lock.
Datasource::rollback()
$db.rollback();
Table 4.724. Arguments for Datasource::rollback()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.725. Return Values for Datasource::rollback()
Return Type | Description |
---|---|
Integer | 0 for success, -1 for not open. |
Table 4.726. 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(status
)
$db.setAutoCommit(False);
Table 4.727. Arguments for Datasource::setAutoCommit()
Argument | Type | Description |
---|---|---|
| Boolean | True to turn on autocommit (a commit will be executed after every Datasource::exec()), False to turn off autocommit (commits must be manually triggered). |
Table 4.728. Return Values for Datasource::setAutoCommit()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
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(sql_command, [arg1, ...]
)
$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.729. Arguments for Datasource::exec()
Argument | Type | Description |
---|---|---|
| String | The SQL command to execute on the server. |
| Any | Include any values to be bound (using |
Table 4.730. Return Values for Datasource::exec()
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.731. 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. |
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(sql_command, [list]
)
$rows = $db.vexec("insert into example_table value (%v, %v, %v)", $arg_list);
Table 4.732. Arguments for Datasource::vexec()
Argument | Type | Description |
---|---|---|
| String | The SQL command to execute on the server. |
| List | Include any values to be bound (using |
Table 4.733. Return Values for Datasource::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.734. 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(select_statement, [arg1, ...]
)
# 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.735. Arguments for Datasource::select()
Argument | Type | Description |
---|---|---|
| String | SQL select statement to execute on the server. |
| Any | Arguments to bind by value in %v positions in the SQL string. |
Table 4.736. Return Values for Datasource::select()
Return Type | Description |
---|---|
Hash | Returns a hash (the keys are the column names) of lists (each hash key's value is a list giving the row data). |
Table 4.737. 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(select_statement, [list]
)
$query = $db.vselect("select * from example_table where id = %v and name = %v", $arg_list);
Table 4.738. Arguments for Datasource::vselect()
Argument | Type | Description |
---|---|---|
| String | SQL select statement to execute on the server. |
| List | A list of arguments to bind by value in %v positions in the SQL string. |
Table 4.739. Return Values for Datasource::vselect()
Return Type | Description |
---|---|
Hash | Returns a hash (the keys are the column names) of lists (each hash key's value is a list giving the row data). |
Table 4.740. 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(select_statement, [arg1, ...]
)
$list = $db.selectRow("select * from example_table");
Table 4.741. Arguments for Datasource::selectRow()
Argument | Type | Description |
---|---|---|
| String | SQL select statement to execute on the server. |
| Any | Arguments to bind by value in %v positions in the SQL string. |
Table 4.742. Return Values for Datasource::selectRow()
Return Type | Description |
---|---|
Hash or NOTHING | Returns a hash (column values) of the first row, NOTHING if no rows are returned. |
Table 4.743. 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(select_statement, [list]
)
$list = $db.vselectRow("select * from example_table where id = %v and name = %v", $arg_list);
Table 4.744. Arguments for Datasource::vselectRow()
Argument | Type | Description |
---|---|---|
| String | SQL select statement to execute on the server. |
| List | A list of arguments to bind by value in %v positions in the SQL string. |
Table 4.745. Return Values for Datasource::vselectRow()
Return Type | Description |
---|---|
Hash or NOTHING | Returns a hash of the first row (column values). If no rows are returned by the query, then NOTHING is returned. |
Table 4.746. 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(select_statement, [arg1, ...]
)
$list = $db.selectRows("select * from example_table");
Table 4.747. Arguments for Datasource::selectRows()
Argument | Type | Description |
---|---|---|
| String | SQL select statement to execute on the server. |
| Any | Arguments to bind by value in %v positions in the SQL string. |
Table 4.748. Return Values for Datasource::selectRows()
Return Type | Description |
---|---|
List | Returns a list (the rows returned) of hashes (column values). |
Table 4.749. 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(select_statement, [list]
)
$list = $db.vselectRows("select * from example_table where id = %v and name = %v", $arg_list);
Table 4.750. Arguments for Datasource::vselectRows()
Argument | Type | Description |
---|---|---|
| String | SQL select statement to execute on the server. |
| List | A list of arguments to bind by value in %v positions in the SQL string. |
Table 4.751. Return Values for Datasource::vselectRows()
Return Type | Description |
---|---|
List | Returns a list (the rows returned) of hashes (column values). |
Table 4.752. 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(timeout_ms
)
$db.setTransactionLockTimeout(5m); # transaction lock timeout set to 5 minutes
Table 4.753. Arguments for Datasource::setTransactionLockTimeout()
Argument | Type | Description |
---|---|---|
| Integer | 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: |
Table 4.754. Return Values for Datasource::setTransactionLockTimeout()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Retrieves the transaction lock timeout value as an integer in milliseconds.
Datasource::getTransactionLockTimeout()
$int = $db.getTransactionLockTimeout();
Table 4.755. Arguments for Datasource::getTransactionLockTimeout()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.756. Return Values for Datasource::getTransactionLockTimeout()
Return Type | Description |
---|---|
Integer | 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(username
)
$db.setUserName("user");
Table 4.757. Arguments for Datasource::setUserName()
Argument | Type | Description |
---|---|---|
| String | The username to be used for the connection. |
Table 4.758. Return Values for Datasource::setUserName()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Retrieves the username parameter for connections to the database.
Datasource::getUserName()
$str = $db.getUserName();
Table 4.759. Arguments for Datasource::getUserName()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.760. Return Values for Datasource::getUserName()
Return Type | Description |
---|---|
String | The username connection parameter. |
Sets the password to use for the connection. Invalid passwords will cause an exception to be thrown when the connection is opened.
Datasource::setPassword()
$db.setPassword("pass");
Table 4.761. Arguments for Datasource::setPassword()
Argument | Type | Description |
---|---|---|
| String | The password name to be used for the connection. |
Table 4.762. Return Values for Datasource::setPassword()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Retrieves the password connection parameter.
Datasource::getPassword()
$str = $db.getPassword();
Table 4.763. Arguments for Datasource::getPassword()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.764. Return Values for Datasource::getPassword()
Return Type | Description |
---|---|
String | Retrieves the password connection parameter. |
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(dbname
)
$db.setDBName("database");
Table 4.765. Arguments for Datasource::setDBName()
Argument | Type | Description |
---|---|---|
| String | The database name to be used for the connection. |
Table 4.766. Return Values for Datasource::setDBName()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Retrieves the dbname connection parameter.
Datasource::getDBName()
$str = $db.getDBName();
Table 4.767. Arguments for Datasource::getDBName()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.768. Return Values for Datasource::getDBName()
Return Type | Description |
---|---|
String | Retrieves the password connection parameter. |
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(encoding
)
$db.setDBCharset("ALU32UTF8"); # Oracle UTF-8 encoding equivalent
Table 4.769. Arguments for Datasource::setDBCharset()
Argument | Type | Description |
---|---|---|
| String | The database-specific name for the encoding to be used for the connection. |
Table 4.770. Return Values for Datasource::setDBCharset()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
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(hostname
)
$db.setHostName("localhost");
Table 4.771. Arguments for Datasource::setHostName()
Argument | Type | Description |
---|---|---|
| String | The hostname to be used for the connection. |
Table 4.772. Return Values for Datasource::setHostName()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
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(port
)
$db.setPort(5432);
Table 4.773. Arguments for Datasource::setPort()
Argument | Type | Description |
---|---|---|
| Integer | The port number to be used for the connection. |
Table 4.774. Return Values for Datasource::setPort()
Return Type | Description |
---|---|
n/a | This method does not return any value. |
Retrieves the database-specific charset set encoding for the current connection.
Datasource::getDBCharset()
$str = $db.getDBCharset();
Table 4.775. Arguments for Datasource::getDBCharset()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.776. Return Values for Datasource::getDBCharset()
Return Type | Description |
---|---|
String | Retrieves the database-specific charset set encoding for the current connection. |
Retrieves the Qore charset set encoding for the current connection.
Datasource::getOSCharset()
$str = $db.getOSCharset();
Table 4.777. Arguments for Datasource::getOSCharset()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.778. Return Values for Datasource::getOSCharset()
Return Type | Description |
---|---|
String | Retrieves the Qore charset set encoding for the current connection. |
Retrieves the hostname connection parameter.
Datasource::getHostName()
$str = $db.getHostName();
Table 4.779. Arguments for Datasource::getHostName()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.780. Return Values for Datasource::getHostName()
Return Type | Description |
---|---|
String | Retrieves the hostname connection parameter. |
Retrieves the port connection parameter.
Datasource::getPort()
$port = $db.getPort();
Table 4.781. Arguments for Datasource::getPort()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.782. Return Values for Datasource::getPort()
Return Type | Description |
---|---|
Integer or NOTHING | Retrieves the port connection parameter or no value if no port is set. |
Returns the name of the DBI driver used for this object.
Datasource::getDriverName()
$name = $db.getDriverName();
Table 4.783. Arguments for Datasource::getDriverName()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.784. Return Values for Datasource::getDriverName()
Return Type | Description |
---|---|
String | The name of the database driver used for this object. |
Retrieves the driver-specific server version information for the current connection.
Datasource::getServerVersion()
$data = $db.getServerVersion();
Table 4.785. Arguments for Datasource::getServerVersion()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.786. Return Values for Datasource::getServerVersion()
Return Type | Description |
---|---|
Driver-Specific | 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()
$data = $db.getClientVersion();
Table 4.787. Arguments for Datasource::getClientVersion()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.788. Return Values for Datasource::getClientVersion()
Return Type | Description |
---|---|
Driver-Specific | 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(), 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(), or DatasourcePool::beginTransaction().
Table 4.789. 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 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. | |
N | Returns the password parameter. | |
N | Returns the dbname parameter. | |
N | Returns the DBI driver specific charset name for the current connection. | |
N | Returns the Qore charset name for the current connection. | |
N | Returns the hostname parameter. | |
N | Returns the port parameter. | |
N | Returns the name of the database driver used for this object. | |
Y | Returns the driver-specific server version data for the current connection. | |
N | Returns the driver-specific client library version data. Not implemented by all drivers. |
Creates a DatasourcePool object. The constructor 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.
new DatasourcePool(driver_name, [username], [password], [dbname], [charset_name], [hostname], [min], [max], [port]
)
# 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
$pool = new DatasourcePool(DSPGSQL, "user", "pass", "database", "utf8", "localhost", 5, 20, 5432);
Table 4.790. Arguments for DatasourcePool::constructor()
Argument | Type | Description |
---|---|---|
| String | 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. |
| String | The user name for the new connection. |
| String | The password for the new connection. |
| String | The database name for the new connection. |
| String | The database-specific name of the character encoding to use for the new connection. 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. |
| String | The host name for the new connection (not used by some DBI drivers). |
| Integer | The minimum number of connections to open immediately (default=5). |
| Integer | The maximum number of connections to open (default=20). |
| Integer | The port number to use for the connection. |
Table 4.791. Return Values for DatasourcePool::constructor()
Return Type | Description |
---|---|
Object | The DatasourcePool object created |
Table 4.792. Exceptions Thrown by DatasourcePool::constructor()
err | desc |
---|---|
| Missing DBI driver identifier as first argument, 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 lvalue
delete $pool;
Table 4.793. 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()
$pool.beginTransaction();
Table 4.794. Arguments for DatasourcePool::beginTransaction()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.795. Return Values for DatasourcePool::beginTransaction()
Return Type | Description |
---|---|
n/a | This method return no value. |
Commits the current transaction and releases the connection to the pool.
DatasourcePool::commit()
$pool.commit();
Table 4.796. Arguments for DatasourcePool::commit()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.797. Return Values for DatasourcePool::commit()
Return Type | Description |
---|---|
Integer | 0 for success, -1 for not open. |
Table 4.798. Exceptions Thrown by DatasourcePool::commit()
err | desc |
---|---|
depends on DBI driver | See documentation for the DBI driver for driver-specific exceptions. |
Rolls back the current transaction and releases the connection to the pool.
DatasourcePool::rollback()
$pool.rollback();
Table 4.799. Arguments for DatasourcePool::rollback()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.800. Return Values for DatasourcePool::rollback()
Return Type | Description |
---|---|
Integer | 0 for success, -1 for failure (driver-specific). |
Table 4.801. 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(sql_command, [arg1, ...]
)
$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.802. Arguments for DatasourcePool::exec()
Argument | Type | Description |
---|---|---|
| String | The SQL command to execute on the server. |
| Any | Include any values to be bound (using |
Table 4.803. Return Values for DatasourcePool::exec()
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.804. Exceptions Thrown by DatasourcePool::exec()
err | desc |
---|---|
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(sql_command, [list]
)
$rows = $pool.vexec("insert into example_table value (%v, %v, %v)", $arg_list);
Table 4.805. Arguments for DatasourcePool::vexec()
Argument | Type | Description |
---|---|---|
| String | The SQL command to execute on the server. |
| List | Include any values to be bound (using |
Table 4.806. 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.807. Exceptions Thrown by DatasourcePool::vexec()
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 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(), or DatasourcePool::beginTransaction().
DatasourcePool::select(select_statement, [arg1, ...]
)
# 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.808. Arguments for DatasourcePool::select()
Argument | Type | Description |
---|---|---|
| String | SQL select statement to execute on the server. |
| Any | Arguments to bind by value in %v positions in the SQL string. |
Table 4.809. Return Values for DatasourcePool::select()
Return Type | Description |
---|---|
Hash | Returns a hash (the keys are the column names) of lists (each hash key's value is a list giving the row data). |
Table 4.810. 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(), or DatasourcePool::beginTransaction().
DatasourcePool::vselect(select_statement, [list]
)
$query = $pool.vselect("select * from example_table where id = %v and name = %v", $arg_list);
Table 4.811. Arguments for DatasourcePool::vselect()
Argument | Type | Description |
---|---|---|
| String | SQL select statement to execute on the server. |
| List | A list of arguments to bind by value in %v positions in the SQL string. |
Table 4.812. Return Values for DatasourcePool::vselect()
Return Type | Description |
---|---|
Hash | Returns a hash (the keys are the column names) of lists (each hash key's value is a list giving the row data). |
Table 4.813. 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(), or DatasourcePool::beginTransaction().
DatasourcePool::selectRow(select_statement, [arg1, ...]
)
$list = $pool.selectRow("select * from example_table");
Table 4.814. Arguments for DatasourcePool::selectRow()
Argument | Type | Description |
---|---|---|
| String | SQL select statement to execute on the server. |
| Any | Arguments to bind by value in %v positions in the SQL string. |
Table 4.815. Return Values for DatasourcePool::selectRow()
Return Type | Description |
---|---|
Hash or NOTHING | Returns a hash (column values) of the first row, NOTHING if no rows are returned. |
Table 4.816. 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(), or DatasourcePool::beginTransaction().
DatasourcePool::vselectRow(select_statement, [list]
)
$list = $pool.vselectRow("select * from example_table where id = %v and name = %v", $arg_list);
Table 4.817. Arguments for DatasourcePool::vselectRow()
Argument | Type | Description |
---|---|---|
| String | SQL select statement to execute on the server. |
| List | A list of arguments to bind by value in %v positions in the SQL string. |
Table 4.818. Return Values for DatasourcePool::vselectRow()
Return Type | Description |
---|---|
Hash or NOTHING | Returns a hash of the first row (column values). If no rows are returned by the query, then NOTHING is returned. |
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(), or DatasourcePool::beginTransaction().
DatasourcePool::selectRows(select_statement, [arg1, ...]
)
$list = $pool.selectRows("select * from example_table");
Table 4.819. Arguments for DatasourcePool::selectRows()
Argument | Type | Description |
---|---|---|
| String | SQL select statement to execute on the server. |
| Any | Arguments to bind by value in %v positions in the SQL string. |
Table 4.820. Return Values for DatasourcePool::selectRows()
Return Type | Description |
---|---|
List | Returns a list (the rows returned) of hashes (column values). |
Table 4.821. 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(), or DatasourcePool::beginTransaction().
DatasourcePool::vselectRows(select_statement, [list]
)
$list = $pool.vselectRows("select * from example_table where id = %v and name = %v", $arg_list);
Table 4.822. Arguments for DatasourcePool::vselectRows()
Argument | Type | Description |
---|---|---|
| String | SQL select statement to execute on the server. |
| List | A list of arguments to bind by value in %v positions in the SQL string. |
Table 4.823. Return Values for DatasourcePool::vselectRows()
Return Type | Description |
---|---|
List | Returns a list (the rows returned) of hashes (column values). |
Table 4.824. 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()
$str = $pool.getUserName();
Table 4.825. Arguments for DatasourcePool::getUserName()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.826. Return Values for DatasourcePool::getUserName()
Return Type | Description |
---|---|
String | The username connection parameter. |
Retrieves the password connection parameter.
DatasourcePool::getPassword()
$str = $pool.getPassword();
Table 4.827. Arguments for DatasourcePool::getPassword()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.828. Return Values for DatasourcePool::getPassword()
Return Type | Description |
---|---|
String | Retrieves the password connection parameter. |
Retrieves the dbname connection parameter.
DatasourcePool::getDBName()
$str = $pool.getDBName();
Table 4.829. Arguments for DatasourcePool::getDBName()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.830. Return Values for DatasourcePool::getDBName()
Return Type | Description |
---|---|
String | Retrieves the password connection parameter. |
Retrieves the database-specific charset set encoding for the current connection.
DatasourcePool::getDBCharset()
$str = $pool.getDBCharset();
Table 4.831. Arguments for DatasourcePool::getDBCharset()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.832. Return Values for DatasourcePool::getDBCharset()
Return Type | Description |
---|---|
String | Retrieves the database-specific charset set encoding for the current connection. |
Retrieves the Qore charset set encoding for the current connection.
DatasourcePool::getOSCharset()
$str = $pool.getOSCharset();
Table 4.833. Arguments for DatasourcePool::getOSCharset()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.834. Return Values for DatasourcePool::getOSCharset()
Return Type | Description |
---|---|
String | Retrieves the Qore charset set encoding for the current connection. |
Retrieves the hostname connection parameter.
DatasourcePool::getHostName()
$str = $pool.getHostName();
Table 4.835. Arguments for DatasourcePool::getHostName()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.836. Return Values for DatasourcePool::getHostName()
Return Type | Description |
---|---|
String | Retrieves the hostname connection parameter. |
Retrieves the port connection parameter.
DatasourcePool::getPort()
$port = $db.getPort();
Table 4.837. Arguments for DatasourcePool::getPort()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.838. Return Values for DatasourcePool::getPort()
Return Type | Description |
---|---|
Integer or NOTHING | Retrieves the port connection parameter or no value if no port is set. |
Returns the name of the DBI driver used for this object.
DatasourcePool::getDriverName()
$name = $pool.getDriverName();
Table 4.839. Arguments for DatasourcePool::getDriverName()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.840. Return Values for DatasourcePool::getDriverName()
Return Type | Description |
---|---|
String | The name of the database driver used for this object. |
Retrieves the driver-specific server version information for the current connection.
DatasourcePool::getServerVersion()
$data = $pool.getServerVersion();
Table 4.841. Arguments for DatasourcePool::getServerVersion()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.842. Return Values for DatasourcePool::getServerVersion()
Return Type | Description |
---|---|
Driver-Specific | 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()
$data = $pool.getClientVersion();
Table 4.843. Arguments for DatasourcePool::getClientVersion()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.844. Return Values for DatasourcePool::getClientVersion()
Return Type | Description |
---|---|
Driver-Specific | 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.
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 = new 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 $ag = new AutoGate($gate); if ($error) throw "ERROR", "sorry, an error happened"; return "OK"; }
Table 4.845. 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().
new AutoGate(gate_object
)
my $gate = new AutoGate($gate);
Table 4.846. Arguments for AutoGate::constructor()
Argument | Type | Description |
---|---|---|
| The Gate object to enter for the lifetime of the AutoGate object. |
Table 4.847. Return Values for AutoGate::constructor()
Return Type | Description |
---|---|
AutoGate Object | The new AutoGate object. |
Calls Gate::exit() on the saved Gate object and destroys the AutoGate object.
delete lvalue
delete $ag;
Throws an exception; objects of this class cannot be copied.
Table 4.848. Arguments for AutoGate::copy()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.849. Return Values for AutoGate::copy()
Return Type | Description |
---|---|
n/a | This method returns no value because it throws an exception. |
Table 4.850. Exceptions Thrown by AutoGate::copy()
err | desc |
---|---|
| Objects of this class cannot be copied. |
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 = new 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 $am = new AutoLock($mutex); if ($error) throw "ERROR", "sorry, an error happened"; return "OK"; }
Table 4.851. 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.
new AutoLock(mutex_object
)
my $al = new AutoLock($mutex);
Table 4.852. Arguments for AutoLock::constructor()
Argument | Type | Description |
---|---|---|
| The Mutex object to manage for the lifetime of this object. |
Table 4.853. Return Values for AutoLock::constructor()
Return Type | Description |
---|---|
AutoLock Object | The new AutoLock object. |
Calls Mutex::unlock() on the saved Mutex and destroys the AutoLock object.
delete lvalue
delete $al;
Throws an exception; objects of this class cannot be copied.
Table 4.854. Arguments for AutoLock::copy()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.855. Return Values for AutoLock::copy()
Return Type | Description |
---|---|
n/a | This method returns no value because it throws an exception. |
Table 4.856. Exceptions Thrown by AutoLock::copy()
err | desc |
---|---|
| Objects of this class cannot be copied. |
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 $rwl = new RWLock(); 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 $arl = new AutoReadLock($rwl); if ($error) throw "ERROR", "sorry, an error happened"; return "OK"; }
Table 4.857. 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.
new AutoReadLock(rwlock_object
)
my $arl = new AutoReadLock($rwlock);
Table 4.858. Arguments for AutoReadLock::constructor()
Argument | Type | Description |
---|---|---|
| The RWLock object to manage for the lifetime of this object. |
Table 4.859. Return Values for AutoReadLock::constructor()
Return Type | Description |
---|---|
AutoReadLock Object | The new AutoReadLock object. |
Calls RWLock::readUnlock() on the saved RWLock and destroys the AutoReadLock object.
delete lvalue
delete $arl;
Throws an exception; objects of this class cannot be copied.
Table 4.860. Arguments for AutoReadLock::copy()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.861. Return Values for AutoReadLock::copy()
Return Type | Description |
---|---|
n/a | This method returns no value because it throws an exception. |
Table 4.862. Exceptions Thrown by AutoReadLock::copy()
err | desc |
---|---|
| Objects of this class cannot be copied. |
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 $rwl = new RWLock(); 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 $arl = new AutoWriteLock($rwl); if ($error) throw "ERROR", "sorry, an error happened"; return "OK"; }
Table 4.863. 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.
new AutoWriteLock(rwlock_object
)
my $awl = new AutoWriteLock($rwlock);
Table 4.864. Arguments for AutoWriteLock::constructor()
Argument | Type | Description |
---|---|---|
| The RWLock object to manage for the lifetime of this object. |
Table 4.865. Return Values for AutoWriteLock::constructor()
Return Type | Description |
---|---|
AutoWriteLock Object | The new AutoWriteLock object. |
Calls RWLock::writeUnlock() on the saved RWLock and destroys the AutoWriteLock object.
delete lvalue
delete $awl;
Throws an exception; objects of this class cannot be copied.
Table 4.866. Arguments for AutoWriteLock::copy()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.867. Return Values for AutoWriteLock::copy()
Return Type | Description |
---|---|
n/a | This method returns no value because it throws an exception. |
Table 4.868. Exceptions Thrown by AutoWriteLock::copy()
err | desc |
---|---|
| Objects of this class cannot be copied. |
Note: This class is not available with the PO_NO_THREAD_CLASSES
parse option.
Condition objects, when used along with a Mutex object, allow Qore threads to sleep until a certain condition becomes true.
Table 4.869. 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. | |
N | Returns the number of threads currently blocked on this object. |
Creates the Condition object.
new Condition()
$cond = new Condition();
Table 4.870. Arguments for Condition::constructor()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.871. Return Values for Condition::constructor()
Return Type | Description |
---|---|
Condition Object | The new Condition object. |
Creates a new Condition object, not based on the original.
Condition::copy()
$new_cond = $cond.copy();
Table 4.872. Arguments for Condition::copy()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.873. Return Values for Condition::copy()
Return Type | Description |
---|---|
Condition Object | A new Condition object, not based on the original. |
Signals a single blocked thread to wake up. Normally this method call will be made while the same Mutex object used for Condition::wait() calls is locked. Then, when the thread calling this method unlocks the Mutex object, the thread(s) woken up by this call can continue executing.
Condition::signal()
$cond.signal();
Table 4.874. Arguments for Condition::signal()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.875. Return Values for Condition::signal()
Return Type | Description |
---|---|
n/a | This method returns no values. |
Table 4.876. 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 Mutex object used for Condition::wait() calls is locked. Then, when the thread calling this method unlocks the Mutex object, the thread(s) woken up by this call can continue executing.
Condition::broadcast()
$cond.broadcast();
Table 4.877. Arguments for Condition::broadcast()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.878. Return Values for Condition::broadcast()
Return Type | Description |
---|---|
n/a | This method returns no value. |
Table 4.879. 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 a Mutex argument, and the Mutex must be locked before the call. This method will atomically unlock the Mutex 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 Mutex will be reacquired 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 Mutex will also be acquired when the Condition::wait() call returns and a non-zero return value will be returned.
Condition::wait(mutex, [timeout_ms]
)
$mutex.lock(); while ($num > 0) $cond.wait($mutex); # ... do something $mutex.unlock();
Table 4.880. Arguments for Condition::wait()
Argument | Type | Description |
---|---|---|
| Mutex Object | The Mutex object to use for synchronization on this Condition object. The Mutex must be locked before calling this method. |
| Integer or Relative Date/Time | An optional timeout value; integers are interpreted as milliseconds; relative date/time values are interpreted literally. |
Table 4.881. Return Values for Condition::wait()
Return Type | Description |
---|---|
Integer | 0 for success, -1 for errors (timeout). |
Table 4.882. 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.
Condition::wait_count()
$num_threads = $cond.wait_count();
Table 4.883. Arguments for Condition::wait_count()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.884. Return Values for Condition::wait_count()
Return Type | Description |
---|---|
Integer | 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.885. 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. | |
N | Returns the current counter value. | |
N | Returns the number of threads currently blocked on this object. |
Creates the Counter object.
new Counter()
$counter = new Counter();
Table 4.886. Arguments for Counter::constructor()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.887. Return Values for Counter::constructor()
Return Type | Description |
---|---|
Counter Object | The new object created. |
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 lvalue
delete $counter;
Table 4.888. 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.
Counter::copy()
$new_counter = $counter.copy();
Table 4.889. Arguments for Counter::copy()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.890. Return Values for Counter::copy()
Return Type | Description |
---|---|
Counter Object | A new Counter object, not based on the original. |
Atomically increments the counter value.
Counter::inc()
$counter.inc();
Table 4.891. Arguments for Counter::inc()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
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()
$counter.dec();
Table 4.893. Arguments for Counter::dec()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.895. 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).
Counter::waitForZero([timeout_ms]
)
$counter.waitForZero();
Table 4.896. Arguments for Counter::waitForZero()
Argument | Type | Description |
---|---|---|
| Integer or Relative Date/Time | A value giving the number of milliseconds to wait for the Counter to reach zero. |
Table 4.897. Return Values for Counter::waitForZero()
Return Type | Description |
---|---|
Integer | If a timeout value was passed, -1 means that the call timed out, 0 means that the counter reached zero. |
Table 4.898. Exceptions Thrown by Counter::dec()
err | desc |
---|---|
| Object deleted in another thread. |
Returns the current counter value.
Counter::getCount()
$count = $counter.getCount();
Table 4.899. Arguments for Counter::getCount()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.900. Return Values for Counter::getCount()
Return Type | Description |
---|---|
Integer | The current counter value. |
Returns the number of threads currently blocked on this object.
Counter::getWaiting()
$threads = $counter.getWaiting();
Table 4.901. Arguments for Counter::getWaiting()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.902. Return Values for Counter::getWaiting()
Return Type | Description |
---|---|
Integer | 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.903. 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. | |
Y | Blocks until at least one entry is available on the queue, then returns the last entry in the queue. | |
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.
new Queue()
$queue = new Queue();
Table 4.904. Arguments for Queue::constructor()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.905. Return Values for Queue::constructor()
Return Type | Description |
---|---|
Queue Object | The new object created. |
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 lvalue
delete $queue;
Table 4.906. 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.
Queue::copy()
$new_queue = $queue.copy();
Table 4.907. Arguments for Queue::copy()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.908. Return Values for Queue::copy()
Return Type | Description |
---|---|
Queue Object | A new Queue object with the same elements as the original. |
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). Note that this function will throw an exception on timeout, in order to enable the case where NOTHING was pushed on the queue from a timeout.
Queue::get([timeout_ms]
)
$data = $queue.get();
Table 4.909. Arguments for Queue::get()
Argument | Type | Description |
---|---|---|
| Integer or Relative Date/Time | If present, a timeout value in milliseconds (1/1000 second). If no data is available in the timeout period, a QUEUE-TIMEOUT exception is thrown. |
Table 4.910. Return Values for Queue::get()
Return Type | Description |
---|---|
Any | Depends on the value put on the queue. |
Table 4.911. 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). Note that this function will throw an exception on timeout, in order to enable the case where NOTHING was pushed on the queue from a timeout.
Queue::pop([timeout_ms]
)
$data = $queue.pop();
Table 4.912. Arguments for Queue::pop()
Argument | Type | Description |
---|---|---|
| Integer or Relative Date/Time | If present, a timeout value in ms (1/1000 second). If no data is available in the timeout period, a QUEUE-TIMEOUT exception is thrown. |
Table 4.913. Return Values for Queue::pop()
Return Type | Description |
---|---|
Any | Depends on the value put on the queue. |
Table 4.914. 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(value
)
$queue.push($value);
Table 4.915. Arguments for Queue::push()
Argument | Type | Description |
---|---|---|
| Any | Value to be put on the queue. |
Returns the number of elements in the queue.
Queue::size()
$size = $queue.size();
Table 4.917. Arguments for Queue::size()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.918. Return Values for Queue::size()
Return Type | Description |
---|---|
Integer | The number of elements in the queue. |
Returns the number of threads currently blocked on this queue.
Queue::getWaiting()
$num = $queue.getWaiting();
Table 4.919. Arguments for Queue::getWaiting()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.920. Return Values for Queue::getWaiting()
Return Type | Description |
---|---|
Integer | The number of threads currently blocked on this queue. |
Note: This class is not available with the PO_NO_THREAD_CLASSES
parse option.
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.921. 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. | |
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. | |
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.
new RWLock()
$rwl = new RWLock();
Table 4.922. Arguments for RWLock::constructor()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.923. Return Values for RWLock::constructor()
Return Type | Description |
---|---|
RWLock Object | The object created. |
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 lvalue
delete $rwl;
Table 4.924. 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.
RWLock::copy()
$new_rwl = $rwl.copy();
Table 4.925. Arguments for RWLock::copy()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.926. Return Values for RWLock::copy()
Return Type | Description |
---|---|
RWLock Object | A new RWLock object, not based on the original. |
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([timeout_ms]
)
$rwl.readLock();
Table 4.927. Arguments for RWLock::readLock()
Argument | Type | Description |
---|---|---|
| Integer or Relative Date/Time | If an argument is present, it is interpreted as a timeout in milliseconds. Note that it's recommended to use a relative time value (i.e. |
Table 4.928. Return Values for RWLock::readLock()
Return Type | Description |
---|---|
Integer | 0 for success, -1 for failure (only returned with a timeout) |
Table 4.929. 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()
$rwl.readUnlock();
Table 4.930. Arguments for RWLock::readUnlock()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.931. Return Values for RWLock::readUnlock()
Return Type | Description |
---|---|
n/a | This method return no value. |
Table 4.932. 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([timeout_ms]
)
$rwl.writeLock();
Table 4.933. Arguments for RWLock::writeLock()
Argument | Type | Description |
---|---|---|
| Integer or Relative Time | If an argument is present, it is interpreted as a timeout in milliseconds. Note that it's recommended to use a relative time value (i.e. |
Table 4.934. Return Values for RWLock::writeLock()
Return Type | Description |
---|---|
Integer | 0 for lock acquired, -1 for timeout (only when a timeout argument is passed) |
Table 4.935. 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()
$rwl.writeUnlock();
Table 4.936. Arguments for RWLock::writeUnlock()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.937. Return Values for RWLock::writeUnlock()
Return Type | Description |
---|---|
n/a | This method return no value. |
Table 4.938. 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()
$bool = $rwl.tryReadLock();
Table 4.939. Arguments for RWLock::writeUnlock()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.940. Return Values for RWLock::writeUnlock()
Return Type | Description |
---|---|
Integer | 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()
$bool = $rwl.tryWriteLock();
Table 4.941. Arguments for RWLock::tryWriteLock()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.942. Return Values for RWLock::tryWriteLock()
Return Type | Description |
---|---|
Integer | Returns 0 for success (write lock acquired) or -1 if the call would block. |
Returns the read lock count.
RWLock::numReaders()
$num = $rwl.numReaders();
Table 4.943. Arguments for RWLock::numReaders()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.944. Return Values for RWLock::numReaders()
Return Type | Description |
---|---|
Integer | The read lock count. |
Returns the number of threads blocked on the read lock (only non-zero while the write lock is held).
RWLock::getReadWaiting()
$num = $rwl.getReadWaiting();
Table 4.945. Arguments for RWLock::getReadWaiting()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.946. Return Values for RWLock::getReadWaiting()
Return Type | Description |
---|---|
Integer | The number of threads blocked on the read lock. |
Returns the number of threads blocked on the write lock.
RWLock::getWriteWaiting()
$num = $rwl.getWriteWaiting();
Table 4.947. Arguments for RWLock::getWriteWaiting()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.948. Return Values for RWLock::getWriteWaiting()
Return Type | Description |
---|---|
Integer | The number of threads blocked on the write lock. |
Note: This class is not available with the PO_NO_THREAD_CLASSES
parse option.
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.949. 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. | |
N | Acquires the lock only if it is not already held by another thread. Returns 0 for success (lock acquired) or -1 if the call would block. |
Creates the Mutex object.
new Mutex()
$mutex = new Mutex();
Table 4.950. Arguments for Mutex::constructor()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.951. Return Values for Mutex::constructor()
Return Type | Description |
---|---|
Mutex Object | The new object created. |
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 lvalue
delete $mutex;
Table 4.952. 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.
Mutex::copy()
$new_mutex = $mutex.copy();
Table 4.953. Arguments for Mutex::copy()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.954. Return Values for Mutex::copy()
Return Type | Description |
---|---|
Mutex Object | A new Mutex object, not based on the original. |
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([timeout_ms]
)
$mutex.lock();
Table 4.955. Arguments for Mutex::lock()
Argument | Type | Description |
---|---|---|
| Integer or Relative Date/Time | If an argument is present, it is interpreted as a timeout in milliseconds. Note that it's recommended to use a relative time value (i.e. |
Table 4.956. Return Values for Mutex::lock()
Return Type | Description |
---|---|
Integer | 0 for lock acquired, -1 for timeout (only when a timeout argument is passed) |
Table 4.957. 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()
$mutex.unlock();
Table 4.958. Arguments for Mutex::unlock()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.960. 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 by another thread.
Mutex::trylock()
$bool = $mutex.trylock();
Table 4.961. Arguments for Mutex::trylock()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.962. Return Values for Mutex::trylock()
Return Type | Description |
---|---|
Integer | 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.963. 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.
new Sequence([start]
)
$seq = new Sequence();
Table 4.964. Arguments for Sequence::constructor()
Argument | Type | Description |
---|---|---|
| Integer | Optional start number for the sequence (default = 0). |
Table 4.965. Return Values for Sequence::constructor()
Return Type | Description |
---|---|
Sequence Object | The new object created. |
Creates a new Sequence object, not based on the original.
Sequence::copy()
$new_seq = $seq.copy();
Table 4.966. Arguments for Sequence::copy()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.967. Return Values for Sequence::copy()
Return Type | Description |
---|---|
Sequence Object | A new Sequence object, not based on the original. |
Atomically increments the counter and returns the last value.
Sequence::next()
$seq.next();
Table 4.968. Arguments for Sequence::next()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.969. Return Values for Sequence::next()
Return Type | Description |
---|---|
Integer | The last value of the sequence. |
Returns the current value of the counter.
Sequence::getCurrent()
$num = $seq.getCurrent();
Table 4.970. Arguments for Sequence::getCurrent()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.971. Return Values for Sequence::getCurrent()
Return Type | Description |
---|---|
Integer | 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.972. 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. | |
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. | |
N | Returns the current lock count. | |
N | Returns the number of threads blocked on the Gate. |
Creates a new Gate object.
new Gate()
$gate = new Gate();
Table 4.973. Arguments for Gate::constructor()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.974. Return Values for Gate::constructor()
Return Type | Description |
---|---|
Gate Object | The new object created. |
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 lvalue
delete $gate;
Table 4.975. 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.
Gate::copy()
$new_gate = $gate.copy();
Table 4.977. Return Values for Gate::copy()
Return Type | Description |
---|---|
Gate Object | A new Gate object, not based on the original. |
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([timeout_ms]
)
$gate.enter();
Table 4.978. Arguments for Gate::enter()
Argument | Type | Description |
---|---|---|
| Integer or Relative Date/Time | An optional timeout value in milliseconds for acquiring the lock. |
Table 4.979. Return Values for Gate::enter()
Return Type | Description |
---|---|
Integer | 0 for lock acquired, -1 for timeout (only when a timeout argument is passed) |
Table 4.980. 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([timeout_ms]
)
$gate.tryEnter();
Table 4.981. Arguments for Gate::tryEnter()
Argument | Type | Description |
---|---|---|
| Integer or Relative Date/Time | An optional timeout value in milliseconds for acquiring the lock. |
Table 4.982. Return Values for Gate::tryEnter()
Return Type | Description |
---|---|
Integer | 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()
$gate.exit();
Table 4.985. 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()
$num = $gate.numInside();
Table 4.986. Arguments for Gate::numInside()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.987. Return Values for Gate::numInside()
Return Type | Description |
---|---|
Integer | Returns the current lock count. |
Returns the number of threads blocked on this object.
Gate::numWaiting()
$num = $gate.numWaiting();
Table 4.988. Arguments for Gate::numWaiting()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.989. Return Values for Gate::numWaiting()
Return Type | Description |
---|---|
Integer | Returns the number of threads blocked on this object. |
The following constants are defined in the Qore namespace.
Table 4.990. 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.991. ElementTypeMap Constant Hash
Key | Value |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Table 4.992. 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.993. 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.995. 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. | |
N | Returns an XmlNode object representing the root element of the document, if any exists. | |
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.
new XmlDoc(string | hash
)
$xd = new XmlDoc($xml);
Table 4.996. Arguments for XmlDoc::constructor()
Argument | Type | Description |
---|---|---|
| String | The XML string to use to create the XmlDoc object. |
| Hash | 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.997. Return Values for XmlDoc::constructor()
Return Type | Description |
---|---|
XmlDoc Object | The new object created. |
Table 4.998. 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 lvalue
delete $xd;
This method does not throw any exceptions.
Creates a new XmlDoc object, not based on the original.
XmlDoc::copy()
$new_gate = $gate.copy();
Table 4.999. Arguments for XmlDoc::copy()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.1000. Return Values for XmlDoc::copy()
Return Type | Description |
---|---|
XmlDoc Object | A new XmlDoc object, not based on the original. |
Table 4.1001. Arguments for XmlDoc::evalXPath()
Argument | Type | Description |
---|---|---|
| String | The XPath expression to evaluate on the XmlDoc object. |
Table 4.1002. Return Values for XmlDoc::evalXPath()
Return Type | Description |
---|---|
List | Returns a list of XmlNode objects that match the XPath expression. |
Table 4.1003. 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.
XmlDoc::getRootElement()
my $node = $xd.getRootElement();
Table 4.1004. Arguments for XmlDoc::getRootElement()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
This method does not throw any exceptions.
Returns the XML version of the contained XML document.
XmlDoc::getVersion()
my $xmlver = $xd.getVersion();
Table 4.1006. Arguments for XmlDoc::getVersion()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.1007. Return Values for XmlDoc::getVersion()
Return Type | Description |
---|---|
String | 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 collapsiong 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()
my $h = $xd.toQore();
Table 4.1008. Arguments for XmlDoc::toQore()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.1009. Return Values for XmlDoc::toQore()
Return Type | Description |
---|---|
String | The Qore hash corresponding to the data contained in the XML document with out-oforder 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()
my $h = $xd.toQoreData();
Table 4.1010. Arguments for XmlDoc::toQoreData()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.1011. Return Values for XmlDoc::toQoreData()
Return Type | Description |
---|---|
String | 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()
my $xmlstr = $xd.toString();
Table 4.1012. Arguments for XmlDoc::toString()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.1013. Return Values for XmlDoc::toString()
Return Type | Description |
---|---|
String | 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(relaxng_schema
)
$xd.validateRelaxNG($relaxng);
Table 4.1014. Arguments for XmlDoc::validateRelaxNG()
Argument | Type | Description |
---|---|---|
| String | The RelaxNG schema to use to validate the XmlDoc object. |
Table 4.1015. Return Values for XmlDoc::validateRelaxNG()
Return Type | Description |
---|---|
n/a | This method does not return any value; if there are any errors, an appropriate exception is thrown. |
Table 4.1016. 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(xsd
)
$xd.validateSchema($xsd);
Table 4.1017. Arguments for XmlDoc::validateSchema()
Argument | Type | Description |
---|---|---|
| String | The XSD schema to use to validate the XmlDoc object. |
Table 4.1018. Return Values for XmlDoc::validateSchema()
Return Type | Description |
---|---|
n/a | This method does not return any value; if there are any errors, an appropriate exception is thrown. |
Table 4.1019. 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.1020. 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; 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. | |
N |
Returns a string representing a structured path for the current node. | |
Y |
Returns the value of the given property anchored in the given namespace, or NOTHING if no such property exists in the current XmlNode. | |
Y |
Returns the value of the given property, or NOTHING if no such property exists in the current XmlNode. | |
N |
Returns a string of the content of the current node. | |
N |
Returns the name of the current node. | |
N |
Returns the language of the current node, determined by the value of the | |
N |
Returns True if the node is a text node, False if not. | |
N |
Returns True if the node is empty or whitespace only, False if not. | |
N |
Returns XML corresponding to the current node and all its children. |
Cannot be called manually; throws an exception.
XmlNode::constructor()
$xmlnode = new XmlNode();
Table 4.1021. Arguments for XmlNode::constructor()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1022. Return Values for XmlNode::constructor()
Return Type |
Description |
---|---|
n/a |
Currently cannot be used; an exception will be thrown if called manually. |
Table 4.1023. Exceptions thrown by XmlNode::constructor()
err |
desc |
---|---|
|
XmlNode objects cannot be constructed manually |
Destroys the XmlNode object.
delete lvalue
delete $xmlnode;
Creates an independent copy of the XmlNode object.
XmlNode::copy()
$value = $xmlnode.copy();
Table 4.1024. Return Values for XmlNode::copy()
Return Type |
Description |
---|---|
a copy of the current object |
Returns the number of child elements of the XmlNode.
XmlNode::childElementCount()
$value = $xmlnode.childElementCount();
Table 4.1025. Arguments for XmlNode::childElementCount()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1026. Return Values for XmlNode::childElementCount()
Return Type |
Description |
---|---|
Integer |
the number of child elements of the XmlNode |
Returns the space-preserving behavior of the XmlNode object.
XmlNode::getSpacePreserve()
$value = $xmlnode.getSpacePreserve();
Table 4.1027. Arguments for XmlNode::getSpacePreserve()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1028. Return Values for XmlNode::getSpacePreserve()
Return Type |
Description |
---|---|
Integer |
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()
$value = $xmlnode.getElementType();
Table 4.1029. Arguments for XmlNode::getElementType()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1030. Return Values for XmlNode::getElementType()
Return Type |
Description |
---|---|
Integer |
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()
$value = $xmlnode.getElementTypeName();
Table 4.1031. Arguments for XmlNode::getElementTypeName()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1032. Return Values for XmlNode::getElementTypeName()
Return Type |
Description |
---|---|
String |
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()
$value = $xmlnode.firstElementChild();
Table 4.1033. Arguments for XmlNode::firstElementChild()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Returns an XmlNode object for the last child of the current XmlNode object, or NOTHING if there is none.
XmlNode::getLastChild()
$value = $xmlnode.getLastChild();
Table 4.1035. Arguments for XmlNode::getLastChild()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
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()
$value = $xmlnode.lastElementChild();
Table 4.1037. Arguments for XmlNode::lastElementChild()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
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()
$value = $xmlnode.nextElementSibling();
Table 4.1039. Arguments for XmlNode::nextElementSibling()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
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()
$value = $xmlnode.previousElementSibling();
Table 4.1041. Arguments for XmlNode::previousElementSibling()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Returns a string representing a structured path for the current node.
XmlNode::getPath()
$value = $xmlnode.getPath();
Table 4.1043. Arguments for XmlNode::getPath()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1044. Return Values for XmlNode::getPath()
Return Type |
Description |
---|---|
String |
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(prop, namespace
)
$value = $xmlnode.getNsProp($prop, $namespace);
Table 4.1045. Arguments for XmlNode::getNsProp()
Argument |
Type |
Description |
---|---|---|
|
String |
The name of the property to retrieve |
|
String |
The name of the namespace of the property |
Table 4.1046. Return Values for XmlNode::getNsProp()
Return Type |
Description |
---|---|
String |
the value of the property or NOTHING if it does not exist |
Table 4.1047. 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(prop
)
$value = $xmlnode.getProp($prop);
Table 4.1048. Arguments for XmlNode::getProp()
Argument |
Type |
Description |
---|---|---|
|
String |
The name of the property to retrieve |
Table 4.1049. Return Values for XmlNode::getProp()
Return Type |
Description |
---|---|
String |
the value of the property or NOTHING if it does not exist |
Table 4.1050. Exceptions thrown by XmlNode::getProp()
err |
desc |
---|---|
|
missing or invalid argument |
Returns a string of the content of the current node.
XmlNode::getContent()
$value = $xmlnode.getContent();
Table 4.1051. Arguments for XmlNode::getContent()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1052. Return Values for XmlNode::getContent()
Return Type |
Description |
---|---|
String |
a string of the content of the current node |
Returns the name of the current node.
XmlNode::getName()
$value = $xmlnode.getName();
Table 4.1053. Arguments for XmlNode::getName()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1054. Return Values for XmlNode::getName()
Return Type |
Description |
---|---|
String |
the name of the current node |
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()
$value = $xmlnode.getLang();
Table 4.1055. Arguments for XmlNode::getLang()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1056. Return Values for XmlNode::getLang()
Return Type |
Description |
---|---|
String |
the language of the current node, determined by the value of the |
Returns True if the node is a text node, False if not.
XmlNode::isText()
$value = $xmlnode.isText();
Table 4.1057. Arguments for XmlNode::isText()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1058. Return Values for XmlNode::isText()
Return Type |
Description |
---|---|
Boolean |
True if the node is a text node, False if not |
Returns True if the node is empty or whitespace only, False if not.
XmlNode::isBlank()
$value = $xmlnode.isBlank();
Table 4.1059. Arguments for XmlNode::isBlank()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1060. Return Values for XmlNode::isBlank()
Return Type |
Description |
---|---|
Boolean |
True if the node is empty or whitespace only, False if not |
Returns XML corresponding to the current node and all its children.
XmlNode::getXML()
$value = $xmlnode.getXML();
Table 4.1061. Arguments for XmlNode::getXML()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1062. Return Values for XmlNode::getXML()
Return Type |
Description |
---|---|
String |
XML corresponding to the current node and all its children |
The XmlReader class allows XML strings to be iterated and parsed piecewise.
Table 4.1063. 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; 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 True if the node has attributes or False if not. | |
N |
Returns True if the node has a text value or False if not. | |
N |
Returns True if an attribute node was generated from the default value defined in the DTD or schema, False if not. | |
N |
Returns True if the current node is empty or False if not. | |
N |
Returns True if the current node is a namespace declaration rather than a regular attribute or False if not. | |
N |
Returns True if the current reader parser context is valid, False if not | |
Y |
Returns a hash corresponding to the XML string from the current node position, including all its children. | |
Y |
Returns a hash corresponding to the XML string from the current node position, including all its children. | |
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 of the XML string | |
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. | |
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 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. | |
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 | xmlstr
)
$xmlreader = new XmlReader($xml);
Table 4.1064. Arguments for XmlReader::constructor()
Argument |
Type |
Description |
---|---|---|
|
The pre-parsed XML document object to iterate through. | |
|
String |
The XML string to parse. |
Table 4.1065. Return Values for XmlReader::constructor()
Return Type |
Description |
---|---|
Object |
The XmlReader object is returned |
Table 4.1066. Exceptions thrown by XmlReader::constructor()
err |
desc |
---|---|
|
missing or invalid arguments |
Destroys the XmlReader object.
delete lvalue
delete $xmlreader;
Creates an independent copy of the XmlReader object.
XmlReader::copy()
$value = $xmlreader.copy();
Table 4.1067. Return Values for XmlReader::copy()
Return Type |
Description |
---|---|
a copy of the current object |
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()
$value = $xmlreader.read();
Table 4.1068. Arguments for XmlReader::read()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1069. Return Values for XmlReader::read()
Return Type |
Description |
---|---|
Boolean |
True if the read was successful, False if there are no more nodes to read |
Table 4.1070. 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()
$value = $xmlreader.readSkipWhitespace();
Table 4.1071. Arguments for XmlReader::readSkipWhitespace()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1072. Return Values for XmlReader::readSkipWhitespace()
Return Type |
Description |
---|---|
Boolean |
True if the read was successful, False if there are no more nodes to read |
Table 4.1073. 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()
$value = $xmlreader.nodeType();
Table 4.1074. Arguments for XmlReader::nodeType()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1075. Return Values for XmlReader::nodeType()
Return Type |
Description |
---|---|
Integer |
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; for possible return values, see the values of the NodeTypeMap constant.
See also XmlReader::nodeType()
XmlReader::nodeTypeName()
$value = $xmlreader.nodeTypeName();
Table 4.1076. Arguments for XmlReader::nodeTypeName()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1077. Return Values for XmlReader::nodeTypeName()
Return Type |
Description |
---|---|
String |
a string giving the node type of the current node; for possible return values, see the values of the NodeTypeMap constant |
Returns the depth of the node in the tree.
XmlReader::depth()
$value = $xmlreader.depth();
Table 4.1078. Arguments for XmlReader::depth()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1079. Return Values for XmlReader::depth()
Return Type |
Description |
---|---|
Integer |
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()
$value = $xmlreader.name();
Table 4.1080. Arguments for XmlReader::name()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1081. Return Values for XmlReader::name()
Return Type |
Description |
---|---|
String |
the qualified name of the node (prefix:LocalName) or NOTHING if no name is available |
Returns the text value of the node or NOTHING if not available.
XmlReader::value()
$value = $xmlreader.value();
Table 4.1082. Arguments for XmlReader::value()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1083. Return Values for XmlReader::value()
Return Type |
Description |
---|---|
String |
the text value of the node or NOTHING if not available |
Returns True if the node has attributes or False if not.
XmlReader::hasAttributes()
$value = $xmlreader.hasAttributes();
Table 4.1084. Arguments for XmlReader::hasAttributes()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1085. Return Values for XmlReader::hasAttributes()
Return Type |
Description |
---|---|
Boolean |
True if the node has attributes, False if not |
Returns True if the node has a text value or False if not.
XmlReader::hasValue()
$value = $xmlreader.hasValue();
Table 4.1086. Arguments for XmlReader::hasValue()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1087. Return Values for XmlReader::hasValue()
Return Type |
Description |
---|---|
Boolean |
True if the node has a text value, False if not |
Returns True if an attribute node was generated from the default value defined in the DTD or schema, False if not.
XmlReader::isDefault()
$value = $xmlreader.isDefault();
Table 4.1088. Arguments for XmlReader::isDefault()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1089. Return Values for XmlReader::isDefault()
Return Type |
Description |
---|---|
Boolean |
True if the node an attribute node was generated from the default value defined in the DTD or schema, False if not |
Returns True if the current node is empty or False if not.
XmlReader::isEmptyElement()
$value = $xmlreader.isEmptyElement();
Table 4.1090. Arguments for XmlReader::isEmptyElement()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1091. Return Values for XmlReader::isEmptyElement()
Return Type |
Description |
---|---|
Boolean |
True if the current node is empty, False if not |
Returns True if the current node is a namespace declaration rather than a regular attribute or False if not.
XmlReader::isNamespaceDecl()
$value = $xmlreader.isNamespaceDecl();
Table 4.1092. Arguments for XmlReader::isNamespaceDecl()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1093. Return Values for XmlReader::isNamespaceDecl()
Return Type |
Description |
---|---|
Boolean |
True if the current node is a namespace declaration rather than a regular attribute, False if not |
Returns True if the current reader parser context is valid, False if not
XmlReader::isValid()
$value = $xmlreader.isValid();
Table 4.1094. Arguments for XmlReader::isValid()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1095. Return Values for XmlReader::isValid()
Return Type |
Description |
---|---|
Boolean |
True if the current reader parser context is valid, False if not |
Returns a hash corresponding to the XML string from the current node position, including all its 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.
Functionally similar to parseXML()
XmlReader::toQore()
$value = $xmlreader.toQore();
Table 4.1096. Arguments for XmlReader::toQore()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1097. Return Values for XmlReader::toQore()
Return Type |
Description |
---|---|
Hash |
a hash corresponding to the XML string from the current node position, including all its children; maintains XML element order by appending a suffix to key names |
Table 4.1098. Exceptions thrown by XmlReader::toQore()
err |
desc |
---|---|
|
error parsing the XML string (exception description string contains details about the error) |
Returns a hash corresponding to the XML string from the current node position, including all its 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.
Functionally similar to parseXMLAsData()
XmlReader::toQoreData()
$value = $xmlreader.toQoreData();
Table 4.1099. Arguments for XmlReader::toQoreData()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1100. Return Values for XmlReader::toQoreData()
Return Type |
Description |
---|---|
Hash |
a hash corresponding to the XML string from the current node position, including all its 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 |
Table 4.1101. 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()
$value = $xmlreader.attributeCount();
Table 4.1102. Arguments for XmlReader::attributeCount()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1103. Return Values for XmlReader::attributeCount()
Return Type |
Description |
---|---|
Integer |
the number of attributes of the current node |
Returns the base URI of the node if known, NOTHING if not.
XmlReader::baseUri()
$value = $xmlreader.baseUri();
Table 4.1104. Arguments for XmlReader::baseUri()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1105. Return Values for XmlReader::baseUri()
Return Type |
Description |
---|---|
String |
the base URI of the node if known, NOTHING if not |
Returns the encoding of the XML string
XmlReader::encoding()
$value = $xmlreader.encoding();
Table 4.1106. Arguments for XmlReader::encoding()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1107. Return Values for XmlReader::encoding()
Return Type |
Description |
---|---|
String |
the encoding of the XML string |
Returns the local name of the node or NOTHING if no name is available.
XmlReader::localName()
$value = $xmlreader.localName();
Table 4.1108. Arguments for XmlReader::localName()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1109. Return Values for XmlReader::localName()
Return Type |
Description |
---|---|
String |
the local name of the node or NOTHING if no name is available |
Returns the URI defining the namespace associated with the node, or NOTHING if not available.
XmlReader::namespaceUri()
$value = $xmlreader.namespaceUri();
Table 4.1110. Arguments for XmlReader::namespaceUri()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1111. Return Values for XmlReader::namespaceUri()
Return Type |
Description |
---|---|
String |
the URI defining the namespace associated with the node or NOTHING if not available |
Returns the shorthand reference to the namespace associated with the node, or NOTHING if not available.
XmlReader::prefix()
$value = $xmlreader.prefix();
Table 4.1112. Arguments for XmlReader::prefix()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1113. Return Values for XmlReader::prefix()
Return Type |
Description |
---|---|
String |
the shorthand reference to the namespace associated with the node or NOTHING if not available |
Returns the xml:lang scope within which the node resides or NOTHING if there is none.
XmlReader::xmlLang()
$value = $xmlreader.xmlLang();
Table 4.1114. Arguments for XmlReader::xmlLang()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1115. Return Values for XmlReader::xmlLang()
Return Type |
Description |
---|---|
String |
the xml:lang scope within which the node resides or NOTHING if there is none |
Returns a string giving the XML version of the source document (normally "1.0").
XmlReader::xmlVersion()
$value = $xmlreader.xmlVersion();
Table 4.1116. Arguments for XmlReader::xmlVersion()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1117. Return Values for XmlReader::xmlVersion()
Return Type |
Description |
---|---|
String |
a string giving the XML version of the source document (normally "1.0") |
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(name
)
$value = $xmlreader.getAttribute($name);
Table 4.1118. Arguments for XmlReader::getAttribute()
Argument |
Type |
Description |
---|---|---|
|
String |
The qualified name of the attribute to retrieve |
Table 4.1119. Return Values for XmlReader::getAttribute()
Return Type |
Description |
---|---|
String |
the value of the attribute or NOTHING if it does not exist |
Table 4.1120. 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(localname, namespaceuri
)
$value = $xmlreader.getAttributeNs($localname, $namespaceuri);
Table 4.1121. Arguments for XmlReader::getAttributeNs()
Argument |
Type |
Description |
---|---|---|
|
String |
The local name of the attribute to retrieve |
|
String |
The namespace URI of the attribute |
Table 4.1122. Return Values for XmlReader::getAttributeNs()
Return Type |
Description |
---|---|
String |
the value of the attribute or NOTHING if it does not exist |
Table 4.1123. 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(offset
)
$value = $xmlreader.getAttributeOffset($offset);
Table 4.1124. Arguments for XmlReader::getAttributeOffset()
Argument |
Type |
Description |
---|---|---|
|
Integer |
the index of the attribute relative to the containing element |
Table 4.1125. Return Values for XmlReader::getAttributeOffset()
Return Type |
Description |
---|---|
String |
the value of the attribute or NOTHING if it does not exist |
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(prefix
)
$value = $xmlreader.lookupNamespace($prefix);
Table 4.1126. Arguments for XmlReader::lookupNamespace()
Argument |
Type |
Description |
---|---|---|
|
String |
The namespace prefix to resolve; if no value is sent for this argument, the default namespace is returned. |
Table 4.1127. Return Values for XmlReader::lookupNamespace()
Return Type |
Description |
---|---|
String |
The namespace corresponding to the given prefix in the scope of the current element or NOTHING if the prefix could not be resolved. |
Moves the position of the current instance to the attribute with the specified qualified name.
See also XmlReader::moveToAttributeNs()
XmlReader::moveToAttribute(name
)
$value = $xmlreader.moveToAttribute($name);
Table 4.1128. Arguments for XmlReader::moveToAttribute()
Argument |
Type |
Description |
---|---|---|
|
String |
The qualified name of the attribute to move to |
Table 4.1129. Return Values for XmlReader::moveToAttribute()
Return Type |
Description |
---|---|
Boolean | True in case of success, False if not found; if an XML parsing error occurs, an exception is thrown. |
Table 4.1130. 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(localname, namespaceuri
)
$value = $xmlreader.moveToAttributeNs($localname, $namespaceuri);
Table 4.1131. Arguments for XmlReader::moveToAttributeNs()
Argument |
Type |
Description |
---|---|---|
|
String |
The local name of the attribute to move to |
|
String |
The namespace URI of the attribute |
Table 4.1133. 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(offset
)
$value = $xmlreader.moveToAttributeOffset($offset);
Table 4.1134. Arguments for XmlReader::moveToAttributeOffset()
Argument |
Type |
Description |
---|---|---|
|
Integer |
the index of the attribute relative to the containing element to move to |
Table 4.1135. Return Values for XmlReader::moveToAttributeOffset()
Return Type |
Description |
---|---|
Integer |
1 in case of success, -1 in case of error, 0 if not found |
Table 4.1136. 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()
$value = $xmlreader.moveToElement();
Table 4.1137. Arguments for XmlReader::moveToElement()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1138. Return Values for XmlReader::moveToElement()
Return Type |
Description |
---|---|
Boolean | True in case of success, False if not found; if an XML parsing error occurs, an exception is thrown. |
Table 4.1139. 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()
$value = $xmlreader.moveToFirstAttribute();
Table 4.1140. Arguments for XmlReader::moveToFirstAttribute()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1141. Return Values for XmlReader::moveToFirstAttribute()
Return Type |
Description |
---|---|
Boolean | True in case of success, False if not found; if an XML parsing error occurs, an exception is thrown. |
Table 4.1142. 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()
$value = $xmlreader.moveToNextAttribute();
Table 4.1143. Arguments for XmlReader::moveToNextAttribute()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1144. Return Values for XmlReader::moveToNextAttribute()
Return Type |
Description |
---|---|
Boolean | True in case of success, False if not found; if an XML parsing error occurs, an exception is thrown. |
Table 4.1145. 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()
$value = $xmlreader.next();
Table 4.1146. Arguments for XmlReader::next()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1148. 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()
$value = $xmlreader.getInnerXml();
Table 4.1149. Arguments for XmlReader::getInnerXml()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1150. Return Values for XmlReader::getInnerXml()
Return Type |
Description |
---|---|
String |
an XML string of the contents of all the 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 |
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()
$value = $xmlreader.getOuterXml();
Table 4.1151. Arguments for XmlReader::getOuterXml()
Argument |
Type |
Description |
---|---|---|
n/a |
n/a |
This method takes no arguments. |
Table 4.1152. Return Values for XmlReader::getOuterXml()
Return Type |
Description |
---|---|
String |
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 |
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(rng
)
$xmlreader.relaxNGValidate($rng);
Table 4.1153. Arguments for XmlReader::relaxNGValidate()
Argument |
Type |
Description |
---|---|---|
|
String |
The RelaxNG schema string to use for validation |
Table 4.1154. Return Values for XmlReader::relaxNGValidate()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Table 4.1155. 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(xsd
)
$xmlreader.schemaValidate($xsd);
Table 4.1156. Arguments for XmlReader::schemaValidate()
Argument |
Type |
Description |
---|---|---|
|
String |
The XSD schema string to use for validation |
Table 4.1157. Return Values for XmlReader::schemaValidate()
Return Type |
Description |
---|---|
n/a |
This method returns no value |
Table 4.1158. 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 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 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 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 | |
| If the named feature is not already present in Qore, then the |
%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
PO_LOCK_WARNINGS
Prohibits further changes to the warning mask.
%no-child-restrictions
--no-child-restrictions, -I
PO_NO_CHILD_PO_RESTRICTIONS
Allows child program objects to have parse option restrictions that are not a strict subset of the parents'.
%no-class-defs
--no-class-defs
PO_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
PO_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
PO_NO_DATABASE
Disallows access to database functionality. Currently this means that access to the Datasource and DatasourcePool classes is restricted.
%no-external-process
--no-external-process, -E
PO_NO_EXTERNAL_PROCESS
Disallows any access to external processes.
Table 6.2. Unavailable Features with no-external-process
Feature/Function | Description |
---|---|
The backquote operator (``) is not available. | |
The system() function is not available. | |
The kill() function is not available. | |
The exec() function is not available. | |
The backquote() function is not available. |
%no-filesystem
--no-filesystem, -F
PO_NO_FILESYSTEM
Disallows any access to the external filesystem.
Table 6.3. Unavailable Features with no-filesystem
Feature/Function | Description |
---|---|
Dir class | The Dir class is not available. |
File class | The File class is not available. |
The chdir() function is not available. | |
The chmod() function is not available. | |
The chown() function is not available. | |
The glob() function is not available. | |
The hlstat() function is not available. | |
The hstat() function is not available. | |
The is_cdev() function is not available. | |
The is_bdev() function is not available. | |
The is_dev() function is not available. | |
The is_executable() function is not available. | |
The is_dir() function is not available. | |
The is_file() function is not available. | |
The is_pipe() function is not available. | |
The is_link() function is not available. | |
The is_readable() function is not available. | |
The is_socket() function is not available. | |
The is_writeable() function is not available. | |
The lstat() function is not available. | |
The mkdir() function is not available. | |
The mkfifo() function is not available. | |
The rmdir() function is not available. | |
The stat() function is not available. | |
The umask() function is not available. | |
The unlink() function is not available. |
%no-global-vars
--no-global-vars, -G
PO_NO_GLOBAL_VARS
Disallows the use of global variables.
%no-gui
--no-gui, --set-parse-option=no-gui, -pno-gui
PO_NO_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-namespace-defs
--no-namespace-defs, -M
PO_NO_NAMESPACE_DEFS
Disallows new namespace definitions.
%no-network
--no-network, -Y
PO_NO_NETWORK
Disallows any access to the network.
Table 6.4. Unavailable Features with no-network
Feature/Function | Description |
---|---|
FtpClient class | The FtpClient class is not available. |
HTTPClient class | The HTTPClient class is not available. |
XmlRpcClient class | The XmlRpcClient class is not available. |
JsonRpcClient class | The JsonRpcClient class is not available. |
Socket class | The Socket class is not available. |
%no-new
--no-new, -N
PO_NO_NEW
Disallows use of the new operator.
%no-process-control
--no-process-control, -P
PO_NO_PROCESS_CONTROL
Disallows access to functions that would affect the current process.
Table 6.5. Unavailable Features with no-process-control
Feature/Function | Description |
---|---|
The abort() function is not available. | |
The fork() function is not available. | |
The exec() function is not available. | |
The exit() function is not available. | |
The remove_signal_handler() function is not available. | |
The set_signal_handler() function is not available. | |
The setegid() function is not available. | |
The seteuid() function is not available. | |
The setgid() function is not available. | |
The setuid() function is not available. | |
The sleep() function is not available. | |
The usleep() function is not available. |
%no-subroutine-defs
--no-subroutine-defs, -S
PO_NO_SUBROUTINE_DEFS
Disallows subroutine (function) definitions.
%no-terminal-io
--no-terminal-io, --set-parse-option=no-terminal-io, -pno-terminal-io
PO_NO_TERMINAL_IO
Disallows access to terminal input and output.
Table 6.6. Unavailable Features with no-terminal-io
Feature/Function | Description |
---|---|
The flush() function is not available. | |
The f_printf() function is not available. | |
The print() function is not available. | |
The printf() function is not available. | |
The vprintf() function is not available. | |
The stdin constant is not accessible. | |
The stdout constant is not accessible. | |
The stderr constant is not accessible. |
%no-thread-classes
--no-thread-classes
PO_NO_THREAD_CLASSES
Disallows access to thread classes.
Table 6.7. Unavailable Features with no-thread-classes
Feature/Function | Description |
---|---|
AutoGate class | The AutoGate class is not available. |
AutoLock class | The AutoLock class is not available. |
AutoReadLock class | The AutoReadLock class is not available. |
AutoWriteLock class | The AutoWriteLock class is not available. |
Condition class | The Condition class is not available. |
Counter class | The Counter class is not available. |
Mutex class | The Mutex class is not available. |
Queue class | The Queue class is not available. |
RWLock class | The RWLock class is not available. |
%no-thread-control
--no-thread-control, -R
PO_NO_THREAD_CONTROL
Disallows access to thread control operations.
Table 6.8. Unavailable Features with no-thread-control
Feature/Function | Description |
---|---|
background operator | The background operator is not available. |
thread_exit statement | The thread_exit statement is not available. |
The get_thread_data() function is not available. | |
The get_all_thread_data() function is not available. | |
The save_thread_data() function is not available. | |
The delete_thread_data() function is not available. | |
The delete_all_thread_data() function is not available. | |
The getAllThreadCallStacks() function is not available (this function is deprecated and will be removed from a future release). | |
The throwThreadResourceExceptions() function is not available. |
%no-threads
--no-threads, -T
PO_NO_THREADS
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
PO_NO_TOP_LEVEL_STATEMENTS
Disallows top level code.
%require-our
--require-our, -O
PO_REQUIRE_OUR
Requires global variables to be declared with our prior to use (recommended to use for all larger scripts/programs).
%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.
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 | 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). |
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.
Qore's syntax superficially appears to be a mixture of C, Java and perl with some unique features to Qore (such as context statements, etc).
Because no independent comparison of Qore with other languages exists, I'll try to compare Qore to perl and Java as objectively as possible in this section (since I used these two languages to get ideas for the interface for Qore). In my opinion, it's not really possible to make totally objective language comparison (particularly when the author of the language makes it!), but I'll do ma best anyway...
Firs of all, Qore is not perl; perl is a robust, mature, feature-full, and powerful language, and Qore is a new, young, and (compared to perl) relatively limited language and differs philosophically in some areas.
(Some) similarities to perl:
Qore is a weakly-typed scripting language
Qore variable references begin with a dollar sign "$". (ex: $value is a valid variable in both perl and Qore)
In Qore, subroutines are declared with the keyword sub
Qore and perl share many statements (like for, foreach, while, do, if, etc), and operators.
Qore and perl share many basic operators
Qore and perl both use double-precision floating point numbers
Qore uses PCRE to provide perl5-compatible regular expression support
Qore and perl support closures that encapsulate the state of local variables accessed within the closure. Qore additionally provides thread-safe access even to these "persistent" local variables, even when the closure is used in a multi-threaded context.
(Some) differences from perl:
Qore has a clean and powerful threading model, built-in from the start by design
Qore has clean object-oriented features, built-in from the start by design
Qore has transparent UTF-8 support (qore's substr(), string splice, index(), reverse(), etc work on character offsets, not byte offsets according to the character encoding used for the string), perl's wide character support is not as transparent - for example, 'printf("%s\n", substr("ä", 0, 1));' will output an invalid character in perl, but work properly in Qore using UTF-8 variable-width characters
Qore tends to avoid syntactic shortcuts and require more verbose expressions than perl; Qore has a much smaller grammar than perl; Qore has if statements, but no "unless"; etc
A Qore variable can be of any type, whereas in perl the type of variable also depends on the name
perl:
@array = (1, "two"); %hash = ( "a", 1, "b", 2); $scalar = 3.0;
Qore:
$array = (1, "two"); $hash = ( "a" : 1, "b" : 2); $scalar = 3.0;
Qore subroutines can be declared with an optional list of local variables to receive subroutine arguments; the parentheses after the subroutine name are not optional.
Qore accepts a statement or a statement block after if, while, for, foreach, etc, like C, C++, and Java, but unlike perl that requires a block ("{" "}") after such statements.
Qore's splice operator works on strings (respecting character offsets for multi-byte character encodings) as well as lists.
Qore has a switch/case statement, whereas perl has none
Qore hashes must be specified with a specific syntax, ex:
( "key" : expression
)
Qore's object-oriented features are very different from perl's.
Qore's exception handling is more similar to C++ or Java's.
Qore has very tight database integration and syntactic support for processing query results (context statements, find expressions)
Qore uses 64-bit integers by default even on 32-bit platforms.
Qore's operators can change lvalues without references, in Qore a function can change an lvalue only if a reference is passed
there is currently no generic equivalent to perl's references. It is only possible to pass values by reference in Qore if the subroutine includes a local variable argument list
Qore features support for safe signal handling as well.
Complex object-oriented qore programs/scripts are more similar to Java programs than to perl scripts, even though the fact that variable names always begin with a "$" will continue to remind one of perl. This section will attempt to outline the similarities and differences between qore and Java, however, because I'm not a Java expert, it will definitely be incomplete, and may be inaccurate in some cases.
Similarities to Java:
when executed with the --exec-class
or %exec-class
options, a qore program/script will disable the use of top-level statements and instantiate the class with the same name as the input file (stripping the suffix and the path of course) in a manner similar to executing a java program.
Objects in qore are always referenced unless explicitly copied in a manner very similar to java.
qore implements the synchronized keyword in a manner similar to Java, using a reentrant thread lock to ensure that only one thread can execute the function or method at one time (but still allowing recursive invokations in that thread).
qore and Java implement exception handling with try catch blocks (however, see differences below)
qore and Java implement class inheritance (however, see differences below)
Differences from Java
Java is a strongly-typed language and qore is a weakly-typed languange. This means that many programming mistakes in Java can be caught at parse time, while in qore the same mistake may be a run-time error. However, qore's weakly-typed nature can allow much more elegant solutions to some kinds of problems (there are advantages and disadvantages to each approach).
Java's exception handling is strongly typed, supporting multiple catch blocks, requiring methods to declare the exceptions they can throw, etc. Qore supports only one catch block due to the weakly-typed nature of the language.
Qore implements multiple inheritance in a manner more similar to C++; overriding base class constructor arguments is supported. Java implements single class inheritance and multiple interface inheritance.
All methods and members of Qore objects are public by default unless declared private, Java implements finer grained control (the protected
keyword, etc.).
Qore provides no way of overloading methods (including constructor()
methods); Java does
In Qore, any base class method can be overridden in a derived class; also in Qore there is a special syntax that allows explicit calling base class methods from within derived classes. In Java, methods declared as final
cannot be overridden, and for those that can, there is no way to call overridden base class methods (as far as I am aware).
Java uses this
as a reference to the current object, Qore uses $self
Qore has no concept of interfaces; Java does.
Java uses the clone
method and a special interface to provide a mechanism to copy objects; qore uses the copy()
method, which is run in the copy of the object after all members have been copied (although members that are objects get a new reference to the object, so it's not a deep copy -- basically Qore executed an equivalent of Java's Object.clone()
call, and then allows the new object to make changes to the new data). Qore's copy()
methods are inherited and run in the same order as constructor()
methods in class hierarchies.
Java is based on byte code and requires classes to be compiled to byte code before they are run in a virtual machine. Qore parses (very quickly) normal text data to an internal compiled representation which is executed; no virtual machine is necessary (just the qore binary compiled for the target platform), and no formal byte code exists in Qore.
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.