reorganize module

_archive/rhai_engine/rhaibook/rust/modules/self-contained.md

@@ -0,0 +1,70 @@
+Compile to a Self-Contained `AST`
+=================================
+
+{{#include ../../links.md}}
+
+```admonish tip.side "Tip"
+
+It does not matter where the [`import`] statement occurs — e.g. deep within statements blocks
+or within [function] bodies.
+```
+
+When a script [imports][`import`] external [modules] that may not be available later on, it is
+possible to eagerly [_pre-resolve_][module resolver] these imports and embed them directly into a
+self-contained [`AST`].
+
+For instance, a system may periodically connect to a central source (e.g. a database) to load
+scripts and compile them to [`AST`] form. Afterwards, in order to conserve bandwidth (or due to
+other physical limitations), it is disconnected from the central source for self-contained
+operation.
+
+Compile a script into a _self-contained_ [`AST`] via `Engine::compile_into_self_contained`.
+
+```rust
+let mut engine = Engine::new();
+
+// Compile script into self-contained AST using the current
+// module resolver (default to `FileModuleResolver`) to pre-resolve
+// 'import' statements.
+let ast = engine.compile_into_self_contained(&mut scope, script)?;
+
+// Make sure we can no longer resolve any module!
+engine.set_module_resolver(DummyModuleResolver::new());
+
+// The AST still evaluates fine, even with 'import' statements!
+engine.run(&ast)?;
+```
+
+When such an [`AST`] is evaluated, [`import`] statements within are provided the _pre-resolved_
+[modules] without going through the normal [module resolution][module resolver] process.
+
+
+Only Static Paths
+-----------------
+
+`Engine::compile_into_self_contained` only pre-resolves [`import`] statements in the script
+that are _static_, i.e. with a path that is a [string] literal.
+
+```rust
+// The following import is pre-resolved.
+import "hello" as h;
+
+if some_event() {
+    // The following import is pre-resolved.
+    import "hello" as h;
+}
+
+fn foo() {
+    // The following import is pre-resolved.
+    import "hello" as h;
+}
+
+// The following import is also pre-resolved because the expression
+// is usually optimized into a single string during compilation.
+import "he" + "llo" as h;
+
+let module_name = "hello";
+
+// The following import is NOT pre-resolved.
+import module_name as h;
+```