Expressions

An expression can be any of the following (note that expressions are also recursively defined; also note that all examples are given in %new-style):

Expressions

Type | Description | Examples
An immediate value | Qore values that can be expressed directly (see Basic Data Types and Container Data Types for more information) | True 1.2 "a string" 2005-10-27 NULL NOTHING ("key" : val)
A variable reference | Variables see also %allow-bare-refs | var
A variable declaration | Variable Declarations and Lexical Scope, Variables see also %assume-local and %new-style | int var
An in-class object member reference | References to members of an object from within the class see Class Members also allow-bare-refs "%allow-bare-refs" | member
An lvalue assignment | Assigns a value to a lvalue (see Assignment Operator (=)) | var = 1 (a, b, c, date) = (1, "two", 3.3, 2005-10-28)
A function call | Qore function calls (see Functions) | calculate(var1, var2, "string", 4)
A method call | Qore object method calls (see Object Method Calls) see also %allow-bare-refs | object.method("argument")
An in-class method call | Qore in-class object method calls (see Object Method Calls) see also %allow-bare-refs | method("argument")
A static method call | Qore static method calls (see static_methods) | ClassName::static_method("argument")
Expressions with operators | Use of Qore operators | 1 + 2 a || b background my_function()
An expression in parentheses | Use of parentheses for clarity or to specify evaluation precedence | (3 * (2 + a))
A find expression | Finds a value or values in a hash of lists, such as returned by the Qore::SQL::Datasource::select() or Qore::SQL::SQLStatement::fetchColumns() method | find %name, %id in data where (%name =~ /Smith/)
A context reference (`name`) | A contextual reference to the value of a key of the current row being iterated by a context, summarize, subcontext statement, or a find expression | %name
A context row reference (`%%`) | A contextual reference to the current row being iterated by a context, summarize, subcontext statement, or a find expression; this expression returns a hash of the current row | %%
A call reference | 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), while object method references are resolved at run-time | \function_call() \object_expression.method_name()
A closure | An anonymous function used a value; technically 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 | string sub (string a) { return a + b; }
A call reference call | An expression executing a call reference or closure | my_closure(arg1, arg2)
An implicit argument reference (`$1`) | References an implicit argument | $1
A reference to the entire implicit argument list (`$$`) | References the implicit argument list | $$
An implicit index reference | Gives the list index position when implicitly iterating a list | $#

# Static Method Calls

Synopsis
  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.

Syntax
  class_name::method_name `(`[argument_expressions...]`)`

Description
  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.

Example
  TimeZone::setRegion("Europe/Prague");

# Find Expressions

Synopsis
  The find expression can be used to quickly find data in a hash of lists (such as a query result set returned by the Qore::SQL::Datasource::select() or Qore::SQL::SQLStatement::fetchColumns() methods). 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 values can be referred to by preceding the name with a `"%"` character (as with context statements).

Syntax
  `find` result_expression `in` data_expression `where (`where_expression``)

Description
  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.

Example
  rlist = find %fname, %id in data where (%lname =~ /^Smith/);

See also
  - context
  - summarize
  - subcontext

# Call References

Synopsis
  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 the empty parentheses after the call are required to identify the expression as a call reference.

Syntax
  `\`function_name`()`
  `\`class`::`static_method`()`
  `\`object.method`()`

Description
  `\` function_name `()`
  This makes a call reference to a function. Call references to functions are resolved at parse time; if the function does not exist a parse exception will be thrown.
  `\` class `::` static_method `()`
  This makes a call reference to a static method. Call references to static methods are resolved at parse time; if the static method does not exist a parse exception will be thrown.
  `\` object `.` method `()`
  - object: can be any valid Qore expression that evaluates to an object
  - method: must be an unquoted string (see example below) and must represent a valid method name of the object's class.
  This makes a call reference to an object method call, binding the object and the method in the call reference. 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 an `OBJECT-ALREADY-DELETED` exception to be thrown.

Example
  code c = \printf();
  code c = \MyClass::method();
  code c = \obj.method();

Note
  - The backslash at the beginning and the empty parentheses at the end; these are required when specifying a call reference.
  - call reference is a code data type; see Call Reference Type for more information

# Closures

Synopsis
  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.

Syntax
  [deprecated] [public] [synchronized] [return_type] `sub ([`[type] variable1`, ...]) {` [code] `}`
  or the alternate (deprecated) syntax with the `returns` keyword after the parameters:
  [deprecated] [public] [synchronized] `sub ([` [type] variable1`, ...]) returns` return_type `{` [code] `}`

Description
  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 `$.`member from within closures created from objects) and additionally prolongs the scope of the object for the lifetime of the closure.
  Note that parameter and return types are required when the Qore::PO_REQUIRE_TYPES or Qore::PO_REQUIRE_PROTOTYPES parse options are set.

Example
  # 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
  code closure = int sub (int a) { return a + b; };

Note
  closure is a code data type; see Closure Type for more information

# Implicit Argument References

Synopsis
  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.

Syntax
  `$`int (for a single implicit argument; int is the argument number, where `1` is the first argument)
  `$$` (for the entire implicit argument list)

Description
  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, foldl, 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.

Example
  # extract a list of even numbers from a list
  list l = select list, !($1 % 2);

# Implicit Index

Synopsis
  The current list index position when implicitly iterating through lists can be referenced using the implicit index reference characters: `$#`.

Syntax
  `$#`

Description
  The implicit index reference expression (`$#`) can be used whenever a list is iterated implicitly, such as with foreach statements and the map, foldl, foldr, and select operators.

Example
  # create a list of indexes with negative values
  list l = map $#, list, ($1 < 0);