reorganize module

_archive/rhai_engine/rhaibook/rust/modules/ast.md

@@ -0,0 +1,88 @@
+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'
+```