/** @page qore_namespaces Namespaces

    @tableofcontents

    @par Description
    Namespaces allow @ref constants "constants", @ref qore_classes "classes", @ref qore_functions "functions", @ref our "global variables", and even other namespaces to co-exist in the same program by defining them in separate namespaces. Constants, classes, functions, 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, function, or namespace declaration separated by two colons \c "::".  Global variables can only be declared out of line so they can be initialized when they are declared.\n\n
    If the user does not specify the parent namespace with a namespace path in constant, class, function, global variable, or namespace declarations, the declaration will be by default in the unnamed default root namespace.

    @anchor namespace_declarations
    @par In-Line Namespace Declaration
    <tt>[@ref mod_public "public"] <b>namespace</b></tt> <em>[namespace_path::]namespace_identifier</em> <tt>{</tt>\n
    &nbsp;&nbsp;&nbsp;&nbsp;<em>[@ref constants "constant_declarations"]</em>\n
    &nbsp;&nbsp;&nbsp;&nbsp;<em>[@ref qore_classes "class_declarations"]</em>\n    
    &nbsp;&nbsp;&nbsp;&nbsp;<em>[@ref qore_functions "function_declarations"]</em>\n
    &nbsp;&nbsp;&nbsp;&nbsp;<em>[@ref global_variables "global_variable_declarations"]</em>\n
    &nbsp;&nbsp;&nbsp;&nbsp;<em>[namespace_declarations]</em>\n
    <tt>}</tt>

    @par Out of Line Namespace Declaration
    <tt>[@ref mod_public "public"] <b>namespace</b></tt> <em>namespace_identifier</em><tt>;</tt>

	@note No namespace path may be given with out of line namespace declarations.

    When defining a @ref user_modules "user module", namespace declarations can be preceded by @ref mod_public "public", which means that the namespace's public contents will be exported into the @ref Qore::Program "Program" object importing the module.  When a namespace is declared @ref mod_public "public" outside of a @ref user_modules "user module", it means that the namespace can be inherited in any child @ref Qore::Program "Program" objects created in the same scope. See @ref mod_public "public" for more information.

    @anchor namespace_resolution
    @par Namespace Resolution
    Namespaces can either be resolved by giving a path to the constant, class, function, global variable, or namespace desired, or by leaving out the namespace path and allowing the system to search for the constant, class, function, global variable, or namespace. In either case, a depth-first search of the namespace tree is made for a match.\n\n
    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.

    @anchor namespace_paths
    @par Namespace Paths
    Namespace paths look like the following:\n
    - <em>starting_namespace::[sub_namespace(s)s::]constant|class|namespace</em>

    @par Example
    @code{.py}
namespace MyNamespace {
    # global variable declarations in a namespace declaration cannot be initialized at the point they are declared
    our bool my_bool;

    const MyConst = 1;
    class MyClass {
    }
    namespace MySubNamespace;
}

# out of line initialization for MyNamespace::my_bool
MyNamespace::my_bool = False;
# out of line declaration and initialization for MyNamespace::my_int
our int MyNamespace::my_int = 200;
    @endcode

    @note No semicolon (\c ";") should follow the closing bracket in a namespace declaration (in fact using a semicolon in this case would raise a parse exception).
*/
