89 lines
2.8 KiB
Markdown
89 lines
2.8 KiB
Markdown
Create a Module from an AST
|
|
===========================
|
|
|
|
{{#include ../../links.md}}
|
|
|
|
|
|
`Module::eval_ast_as_new`
|
|
-------------------------
|
|
|
|
```admonish info.side.wide "Encapsulated environment"
|
|
|
|
`Module::eval_ast_as_new` encapsulates the entire [`AST`] into each function call, merging the
|
|
[module namespace][function namespace] with the [global namespace][function namespace].
|
|
|
|
Therefore, [functions] defined within the same [module] script can cross-call each other.
|
|
```
|
|
|
|
```admonish info.side.wide "See also"
|
|
|
|
See [_Export Variables, Functions and Sub-Modules from Script_][`export`] for details on how to prepare
|
|
a Rhai script for this purpose as well as to control which [functions]/[variables] to export.
|
|
```
|
|
|
|
A [module] can be created from a single script (or pre-compiled [`AST`]) containing global
|
|
[variables], [functions] and [sub-modules][module] via `Module::eval_ast_as_new`.
|
|
|
|
When given an [`AST`], it is first evaluated (usually to [import][`import`] [modules] and set up global
|
|
[constants] used by [functions]), then the following items are exposed as members of the new [module]:
|
|
|
|
* global [variables] and [constants] – all [variables] and [constants] exported via the
|
|
[`export`] statement (those not exported remain hidden),
|
|
|
|
* [functions] not specifically marked [`private`],
|
|
|
|
* imported [modules] that remain in the [`Scope`] at the end of a script run become sub-modules.
|
|
|
|
|
|
Examples
|
|
--------
|
|
|
|
Don't forget the [`export`] statement, otherwise there will be no [variables] exposed by the
|
|
[module] other than non-[`private`] [functions] (unless that's intentional).
|
|
|
|
```rust
|
|
use rhai::{Engine, Module};
|
|
|
|
let engine = Engine::new();
|
|
|
|
// Compile a script into an 'AST'
|
|
let ast = engine.compile(
|
|
r#"
|
|
// Functions become module functions
|
|
fn calc(x) {
|
|
x + add_len(x, 1) // functions within the same module
|
|
// can always cross-call each other!
|
|
}
|
|
fn add_len(x, y) {
|
|
x + y.len
|
|
}
|
|
|
|
// Imported modules become sub-modules
|
|
import "another module" as extra;
|
|
|
|
// Variables defined at global level can become module variables
|
|
const x = 123;
|
|
let foo = 41;
|
|
let hello;
|
|
|
|
// Variable values become constant module variable values
|
|
foo = calc(foo);
|
|
hello = `hello, ${foo} worlds!`;
|
|
|
|
// Finally, export the variables and modules
|
|
export x as abc; // aliased variable name
|
|
export foo;
|
|
export hello;
|
|
"#)?;
|
|
|
|
// Convert the 'AST' into a module, using the 'Engine' to evaluate it first
|
|
// A copy of the entire 'AST' is encapsulated into each function,
|
|
// allowing functions in the module script to cross-call each other.
|
|
let module = Module::eval_ast_as_new(Scope::new(), &ast, &engine)?;
|
|
|
|
// 'module' now contains:
|
|
// - sub-module: 'extra'
|
|
// - functions: 'calc', 'add_len'
|
|
// - constants: 'abc' (renamed from 'x'), 'foo', 'hello'
|
|
```
|