/** @page variables Variables

    @tableofcontents

    Unless parse option @ref allow-bare-refs "%allow-bare-refs" or @ref new-style "%new-style" are set, variables are %Qore identifiers prefixed by a \c "$" sign, similar to <a href="http://www.perl.org">Perl</a>. If a variable is declared without any type restriction, then it is assumed to have type @ref any_type "any". In this case, variables so declared can hold any data type.

    @section special_variables 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.

    <b>Special %Qore Variables</b>
    |!Variable|!Scope|!Data Type|!Explanation
    |\c argv|Local|@ref list_or_nothing_type "*list"|automatically assigned local variable containing the list of function or method arguments that were not assigned to parameter variables (see @ref implicit_arguments for more information)
    |\c Qore::ARGV|Global|@ref list_type "list"|script command-line arguments (use the @ref Qore::GetOpt class to parse command-line arguments)
    |\c Qore::QORE_ARGV|Global|@ref list_type "list"|complete qore command-line arguments
    |\c Qore::ENV|Global|@ref hash_type "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

    @section variable_declarations Variable Declarations and Lexical Scope

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

    When the @ref assume-local "%assume-local" or @ref new-style "%new-style" parse directive is used, variables without an explicit scope declaration (i.e. @ref my or @ref our) are assumed to be @ref local_variables "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 @ref any_type "any". Note that type declarations are required for all variables (and for function and method parameters and class members) when the @ref require-types "%require-types" parse option is set.

    @ref local_variables "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 @ref threading (and in particular @ref threading_and_variables) for more information.

    Global variables are members of @ref qore_namespaces "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 @ref our keyword is optional unless @ref require-our "%require-our" is set):

    @code{.py}
#!/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);
    @endcode

    The first printf() statement will output:
    @verbatim
local a = 2@endverbatim

    The second printf() statement will output:
    @verbatim
global a = 1@endverbatim

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

    @subsection variable_implicit_construction Variable Implicit Construction
    Variables with supported type declarations can be instantiated with a special syntax as follows:
    [@ref my "my"|@ref our "our"] <em>@ref data_type_declarations "var_type" var_name</em><tt>(</tt>[<em>@ref expressions "arg_expression"</em><tt>, ...]);</tt>

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

    The following types can be used for <em>@ref data_type_declarations "var_type"</em>:
    - a @ref qore_classes "class name" or <tt>@ref object_type "object"&lt;</tt><em>@ref qore_classes "class_name"</em><tt>&gt;</tt> for object instantiation (the class name may have a namespace-prefixed path)
    - <tt>@ref hash_type "hash"&lt;</tt><em>@ref hashdecl "hashdecl_name"</em><tt>&gt;</tt> for @ref hashdecl "type-safe hash" instantiation (the type-safe hash name may have a namespace-prefixed path)
    - <tt>@ref hash_type "hash"&lt;string, </tt><em>@ref data_type_declarations "type"</em><tt>&gt;</tt> for @ref hash_complex_type "complex hash" instantiation with type-safe keys
    - <tt>@ref list_type "list"&lt;</tt><em>@ref data_type_declarations "type"</em><tt>&gt;</tt> for @ref list_complex_type "complex list" instantiation with type-safe elements

    @par Examples
    @code{.py}
# 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);
    @endcode

    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 @ref new "new operator" with a variable declaration.

    @see
    - @ref new
    - @ref cast

    @section local_variables 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 @ref closure "closures" and local variables that have a @ref lvalue_references "reference" taken of them).

    @note Declaring a variable with \b 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 @ref threading_and_variables for more information.

    @subsection my The "my" Keyword
    Variables declared with \b my are always local variables.

    <b>my Example</b>\n
    @code{.py}my int i = 1;@endcode

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

    @section global_variables Global Variables

    @subsection our The "our" Keyword
    Variables declared with \b 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.

    <b>our Example</b>\n
    @code{.py} our int i = 1;@endcode

    Note that the \b our keyword is required when declaring a global variable if the parse option @ref require-our "%require-our" (\c -O or \c --require-our command-line option) is set for the parent program. See @ref parse_options for more information.

    Unlike local variables, global variables are members of @ref qore_namespaces "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 @ref qore_namespaces "namespaces" cannot be initialized at the same time as the declaration, but instead have to be initialized elsewhere.

    When defining a @ref user_modules "user module", the \b our keyword can be preceded by @ref mod_public "public", which means that the global variable will be available (imported) in the @ref Qore::Program "Program" object importing the module.  See @ref mod_public "public" for more information.

    @section thread_local_variables Thread-Local Global Variables

    @subsection thread_local The "thread_local" Keyword
    Variables declared with \b 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.

    <b>thread_local Example</b>\n
    @code{.py} thread_local int i = 1;@endcode

    Note that the <tt><b>thread_local</b></tt> keyword is always required when declaring a global thread-local variable.

    Like standard @ref global_variables "global variables" but unlike local variables, thread-local variables are
    members of @ref qore_namespaces "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
    @ref qore_namespaces "namespaces" cannot be initialized at the same time as the declaration, but instead have to be
    initialized elsewhere.

    When defining a @ref user_modules "user module", the <tt><b>thread_local</b></tt> keyword can be preceded by
    @ref mod_public "public", which means that the <tt><b>thread_local</b></tt> variable will be available (imported) in
    @ref Qore::Program "Program" objects importing the module.  See @ref mod_public "public" for more information.

    @note
    - <tt><b>thread_local</b></tt> global variables are always thread local, even if referenced in a
      @ref closure "closure" or if an @ref references_overview "lvalue reference" is taken of a
      <tt><b>thread_local</b></tt> variable
    - @ref Qore::set_thread_init() and @ref Qore::Program::setThreadInit() "Program::setThreadInit()" can be used to
      automatically assign values to @ref thread_local variables when threads are started
*/
