kjuulh/rhai
1
0
Fork 0
Code Issues 1 Pull Requests 1 Packages Projects Releases Wiki Activity

Module:;eval_ast_as_new defaults to merging namespaces.

Browse Source
This commit is contained in:
Stephen Chung
2020-10-03 11:42:54 +08:00
parent a72f70846f
commit eec3f4e1bf
12 changed files with 22 additions and 412 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
doc/src/rust/modules/ast.md
View File

@@ -18,21 +18,8 @@ When given an [`AST`], it is first evaluated, then the following items are expos
* Global modules that remain in the [`Scope`] at the end of a script run.
`merge_namespaces` Parameter
---------------------------
The parameter `merge_namespaces` in `Module::eval_ast_as_new` determines the exact behavior of
functions exposed by the module and the namespace that they can access:
| `merge_namespaces` value | Description | Namespace | Performance | Call global functions | Call functions in same module |
| :----------------------: | ------------------------------------------------ | :-----------------: | :---------: | :-------------------: | :---------------------------: |
| `true` | encapsulate entire `AST` into each function call | module, then global | 2x slower | yes | yes |
| `false` | register each function independently | global only | fast | yes | no |
If the ultimate intention is to load the [module] directly into an [`Engine`] via `Engine::load_package`,
set `merge_namespaces` to `false` because there will not be any _module_ namespace as `Engine::load_package`
flattens everything into the _global_ namespace anyway.
`Module::eval_ast_as_new` encapsulates the entire `AST` into each function call, merging the module namespace
with the global namespace. Therefore, functions defined within the same module script can cross-call each other.
Examples
@@ -77,15 +64,9 @@ let ast = engine.compile(r#"
"#)?;
// Convert the 'AST' into a module, using the 'Engine' to evaluate it first
//
// The second parameter ('merge_namespaces'), when set to true, will encapsulate
// a copy of the entire 'AST' into each function, allowing functions in the module script
// to cross-call each other.
//
// This incurs additional overhead, avoidable by setting 'merge_namespaces' to false
// which makes function calls 2x faster but at the expense of not being able to cross-call
// functions in the same module script.
let module = Module::eval_ast_as_new(Scope::new(), &ast, true, &engine)?;
// 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: 'foobar' (renamed from 'extra')

47
doc/src/rust/modules/resolvers.md
View File

@@ -56,53 +56,6 @@ The base directory can be changed via the `FileModuleResolver::new_with_path` co
`FileModuleResolver::create_module` loads a script file and returns a module.
`GlobalFileModuleResolver`
-------------------------
A simpler but more efficient version of `FileModuleResolver`, intended for short utility modules.
Not available for [`no_std`] or [WASM] builds.
Loads a script file (based off the current directory) with `.rhai` extension.
All functions are assumed **independent** and _cannot_ cross-call each other.
Functions are searched _only_ in the _global_ namespace.
```rust
------------------
| my_module.rhai |
------------------
private fn inner_message() { "hello! from module!" }
fn greet_inner() {
print(inner_message()); // cross-calling a module function!
// there will be trouble because each function
// in the module is supposed to be independent
// of each other
}
fn greet() {
print(main_message()); // function is searched in global namespace
}
-------------
| main.rhai |
-------------
fn main_message() { "hi! from main!" }
import "my_module" as m;
m::greet_inner(); // <- function not found: 'inner_message'
m::greet(); // works because 'main_message' exists in
// the global namespace
```
The base directory can be changed via the `FileModuleResolver::new_with_path` constructor function.
`GlobalFileModuleResolver::create_module` loads a script file and returns a module.
`StaticModuleResolver`
---------------------