Module:;eval_ast_as_new defaults to merging namespaces.
This commit is contained in:
Stephen Chung
@@ -88,84 +88,3 @@ fn say_hello() {
|
||||
}
|
||||
say_hello();
|
||||
```
|
||||
|
||||
|
||||
Namespace Consideration When Not Using `FileModuleResolver`
|
||||
---------------------------------------------------------
|
||||
|
||||
[Modules] can be dynamically loaded into a Rhai script using the [`import`] keyword.
|
||||
When that happens, functions defined within the [module] can be called with a _qualified_ name.
|
||||
|
||||
The [`FileModuleResolver`][module resolver] encapsulates the namespace inside the module itself,
|
||||
so everything works as expected. A function defined in the module script cannot access functions
|
||||
defined in the calling script, but it can freely call functions defined within the same module script.
|
||||
|
||||
There is a catch, though. When using anything other than the [`FileModuleResolver`][module resolver],
|
||||
functions in a module script refer to functions defined in the _global namespace_.
|
||||
When called later, those functions may not be found.
|
||||
|
||||
When using the [`GlobalFileModuleResolver`][module resolver], for example:
|
||||
|
||||
```rust
|
||||
Using GlobalFileModuleResolver
|
||||
==============================
|
||||
|
||||
-----------------
|
||||
| greeting.rhai |
|
||||
-----------------
|
||||
|
||||
fn get_message() { "Hello!" };
|
||||
|
||||
fn say_hello() {
|
||||
print(get_message()); // 'get_message' is looked up in the global namespace
|
||||
// when exported
|
||||
}
|
||||
|
||||
say_hello(); // Here, 'get_message' is found in the module namespace
|
||||
|
||||
---------------
|
||||
| script.rhai |
|
||||
---------------
|
||||
|
||||
import "greeting" as g;
|
||||
g::say_hello(); // <- error: function not found - 'get_message'
|
||||
// because it does not exist in the global namespace
|
||||
```
|
||||
|
||||
In the example above, although the module `greeting.rhai` loads fine (`"Hello!"` is printed),
|
||||
the subsequent call using the _namespace-qualified_ function name fails to find the same function
|
||||
'`message`' which now essentially becomes `g::message`. The call fails as there is no more
|
||||
function named '`message`' in the global namespace.
|
||||
|
||||
Therefore, when writing functions for a [module] intended for the [`GlobalFileModuleResolver`][module resolver],
|
||||
make sure that those functions are as independent as possible and avoid cross-calling them from each other.
|
||||
|
||||
A [function pointer] is a valid technique to call another function in an environment-independent manner:
|
||||
|
||||
```rust
|
||||
-----------------
|
||||
| greeting.rhai |
|
||||
-----------------
|
||||
|
||||
fn get_message() { "Hello!" };
|
||||
|
||||
fn say_hello(msg_func) { // 'msg_func' is a function pointer
|
||||
print(msg_func.call()); // call via the function pointer
|
||||
}
|
||||
|
||||
say_hello(Fn("get_message"));
|
||||
|
||||
|
||||
---------------
|
||||
| script.rhai |
|
||||
---------------
|
||||
|
||||
import "greeting" as g;
|
||||
|
||||
fn my_msg() {
|
||||
import "greeting" as g; // <- must import again here...
|
||||
g::get_message() // <- ... otherwise will not find module 'g'
|
||||
}
|
||||
|
||||
g::say_hello(Fn("my_msg")); // prints 'Hello!'
|
||||
```
|
||||
|
||||
@@ -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')
|
||||
|
||||
@@ -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`
|
||||
---------------------
|
||||
|
||||
|
||||
Reference in New Issue
Block a user