Import a Module
===============

{{#include ../../links.md}}

`import` Statement
-----------------

A module can be _imported_ via the `import` statement, and its members are accessed via '`::`' similar to C++.

```rust
import "crypto" as lock;        // import the script file 'crypto.rhai' as a module named 'lock'

lock::encrypt(secret);          // use functions defined under the module via '::'

lock::hash::sha256(key);        // sub-modules are also supported

print(lock::status);            // module variables are constants

lock::status = "off";           // <- runtime error - cannot modify a constant
```


Scoped Imports
--------------

`import` statements are _scoped_, meaning that they are only accessible inside the scope that they're imported.

They can appear anywhere a normal statement can be, but in the vast majority of cases `import` statements are
group at the beginning of a script. It is not advised to deviate from this common practice unless
there is a _Very Good Reason™_.

Especially, do not place an `import` statement within a loop; doing so will repeatedly re-load the same module
during every iteration of the loop!

```rust
let mod = "crypto";

if secured {                    // new block scope
    import mod as c;            // import module (the path needs not be a constant string)

    c::encrypt(key);            // use a function in the module
}                               // the module disappears at the end of the block scope

c::encrypt(others);             // <- this causes a run-time error because the 'crypto' module
                                //    is no longer available!

for x in range(0, 1000) {
    import "crypto" as c;       // <- importing a module inside a loop is a Very Bad Idea™

    c.encrypt(something);
}
```


Recursive Imports
----------------

Beware of _import cycles_ - i.e. recursively loading the same module. This is a sure-fire way to
cause a stack overflow in the [`Engine`], unless stopped by setting a limit for [maximum number of modules].

For instance, importing itself always causes an infinite recursion:

```rust
// This file is 'hello.rhai'

import "hello" as foo;          // import itself - infinite recursion!

foo::do_something();
```

Modules cross-referencing also cause infinite recursion:

```rust
// This file is 'hello.rhai' - references 'world.rhai'
import "world" as foo;
foo::do_something();

// This file is 'world.rhai' - references 'hello.rhai'
import "hello" as bar;
bar::do_something_else();
```