| Qore Programming Language Reference Manual 2.2.0

Loading...
Searching...
No Matches
Variables

Unless parse option %allow-bare-refs or %new-style are set, variables are Qore identifiers prefixed by a `"$"` sign, similar to Perl. If a variable is declared without any type restriction, then it is assumed to have type any. In this case, variables so declared can hold any data type.

# Special Variables

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.

Special Qore Variables

Variable | Scope | Data Type | Explanation
`argv` | Local | *list | automatically assigned local variable containing the list of function or method arguments that were not assigned to parameter variables (see Implicit Argument References for more information)
`Qore::ARGV` | Global | list | script command-line arguments (use the Qore::GetOpt class to parse command-line arguments)
`Qore::QORE_ARGV` | Global | list | complete qore command-line arguments
`Qore::ENV` | Global | hash | UNIX program environment

Note
  global variables are namespace members; if a namespace path is not declared for the global variable, then the global variable will reside in the root namespace

# Variable Declarations and Lexical Scope

Unless the %assume-local or %new-style parse directives are used, variables not in a parameter list automatically have global scope unless the first reference is prefixed with The "my" Keyword. Variable names in a parameter list are always local to their associated function, method, or catch block. Global variables can be explicitly declared with The "our" Keyword. The The "our" Keyword keyword is required if the parse option %require-our (`-O` or `–require-our` command-line option) is set for the parent program. See Parse Option Constants for more information.

When the %assume-local or %new-style parse directive is used, variables without an explicit scope declaration (i.e. The "my" Keyword or The "our" Keyword) are assumed to be local variables.

Variables may be assigned any value unless restricted with a type declaration. If no type declaration is given, then the variable is assumed to be type any. Note that type declarations are required for all variables (and for function and method parameters and class members) when the %require-types parse option is set.

Local variables are not shared between threads (local variables have a distinct value in each thread, with some very particular exceptions), however global variables are. See Threading (and in particular Threading and Variables) for more information.

Global variables are members of namespaces; if a global variable is declared anywhere outside a namespace declaration, and a namespace path is not given, then the global variable will be assumed to be in the root namespace.

For example (in the following script, the The "our" Keyword keyword is optional unless %require-our is set):

#!/usr/bin/qore
#
# variable scoping example
%new-style
our int a = 1; # this is a global variable
our (string b, any c, hash d); # list of global variables
if (a == 1) {
int a = 2;
my (string b, any c);
# a, b, and c are local variables,
# the use of which will not affect the
# global variables of the same name
printf("local a = %d\n", a);
}
printf("global a = %d\n", a);

The first printf() statement will output:

    local a = 2

The second printf() statement will output:

    global a = 1

Note
  If parse option %allow-bare-refs or %new-style is set, then variable references must be made without the "$" character. Because Qore is moving toward establishing %new-style as the default syntax; all examples given in the Qore documentation are given assuming %new-style unless otherwise indicated.

## Variable Implicit Construction

Variables with supported type declarations can be instantiated with a special syntax as follows: [my|our] var_type var_name`(`[arg_expression`, ...]);`

This allows a variable to be declared with a specific type and initialized at the same time.

The following types can be used for var_type:

- a class name or `object<`class_name`>` for object instantiation (the class name may have a namespace-prefixed path)
- `hash<`hashdecl_name`>` for type-safe hash instantiation (the type-safe hash name may have a namespace-prefixed path)
- `hash<string,` type`>` for complex hash instantiation with type-safe keys
- `list<`type`>` for complex list instantiation with type-safe elements

Examples
  # simple object declaration and instantiation
  Mutex m();
  # equivalent to the example above
  object<Mutex> m();
  # type-safe hashdecl hash declaration and instantiation
  hash<MyHash> h1(("a": 1));
  # complex hash with type-safe keys declaration and instantiation
  hash<string, int> h2(("a": 1));
  # complex list with type-safe elements declaration and instantiation
  list<int> l1(1);

This provides type information to the parser which allows more errors to be caught at parse time (instead of at run time), and furthermore allows Qore to improve performance by performing more work at parse time rather than for every time the object is accessed at run time (for example, method and variant resolution), and normally requires less typing. This is preferred to using the new operator with a variable declaration.

See also
  - New Value Operator (new)
  - Cast Operator (cast<>())

# Local Variables

Local variables are local to the block in which they are declared; they are also thread-local, meaning that each thread will have its own value of a local variable.

Local variables are generally accessed without any mutual-exclusion locking (with the exception of local variables bound in closures and local variables that have a reference taken of them).

Note
  Declaring a variable with my at the top-level of a program creates a local variable with global scope; in effect this is a global thread-local variable; see Threading and Variables for more information.

## The "my" Keyword

Variables declared with my are always local variables.

my Example

my int i = 1;

The my keyword is not required if the %assume-local or %new-style parse directive is set. In this case, all variables are assumed to be local unless explicitly declared with our.

# Global Variables

## The "our" Keyword

Variables declared with our have global scope and are subject to mutual exclusion locks with each access. Therefore even in single-threaded programs, it's more efficient to use local variables (even local variables with global scope - where a local variable is declared in the top-level block) if the value of the variable does not need to be shared among other threads.

our Example

our int i = 1;

Note that the our keyword is required when declaring a global variable if the parse option %require-our (`-O` or `–require-our` command-line option) is set for the parent program. See Parse Option Constants for more information.

Unlike local variables, global variables are members of namespaces; if a namespace path is not given, then the global variable will be assumed to be in the root namespace. Global variables declared in namespaces cannot be initialized at the same time as the declaration, but instead have to be initialized elsewhere.

When defining a user module, the our keyword can be preceded by public, which means that the global variable will be available (imported) in the Program object importing the module. See public for more information.

# Thread-Local Global Variables

## The "thread_local" Keyword

Variables declared with thread_local have global scope and are additionally thread local; they are never subject to mutual exclusion locks. Each Qore thread will have a different value for the variable, for example.

thread_local Example

thread_local int i = 1;

Note that the `thread_local` keyword is always required when declaring a global thread-local variable.

Like standard global variables but unlike local variables, thread-local variables are members of namespaces; if a namespace path is not given, then the thread-local variable will be assumed to be in the unnamed root namespace. Thread-local variables declared in namespaces cannot be initialized at the same time as the declaration, but instead have to be initialized elsewhere.

When defining a user module, the `thread_local` keyword can be preceded by public, which means that the `thread_local` variable will be available (imported) in Program objects importing the module. See public for more information.

Note
  - `thread_local` global variables are always thread local, even if referenced in a closure or if an lvalue reference is taken of a `thread_local` variable
  - Qore::set_thread_init() and Program::setThreadInit() can be used to automatically assign values to The "thread_local" Keyword variables when threads are started