184 lines
5.0 KiB
Markdown
184 lines
5.0 KiB
Markdown
`FileModuleResolver`
|
|
====================
|
|
|
|
{{#include ../../../links.md}}
|
|
|
|
|
|
```admonish abstract.small "Default"
|
|
|
|
`FileModuleResolver` is the default for [`Engine::new`][`Engine`].
|
|
```
|
|
|
|
The _default_ [module] resolution service, not available for [`no_std`] or [WASM] builds.
|
|
Loads a script file (based off the current directory or a specified one) with `.rhai` extension.
|
|
|
|
|
|
Function Namespace
|
|
-------------------
|
|
|
|
All functions in the [_global_ namespace][function namespace], plus all those defined in the same
|
|
[module], are _merged_ into a _unified_ [namespace][function namespace].
|
|
|
|
All [modules] imported at _global_ level via [`import`] statements become sub-[modules],
|
|
which are also available to [functions] defined within the same script file.
|
|
|
|
|
|
Base Directory
|
|
--------------
|
|
|
|
```admonish tip.side.wide "Tip: Default"
|
|
|
|
If the base directory is not set, then relative paths are based off the directory of the loading script.
|
|
|
|
This allows scripts to simply cross-load each other.
|
|
```
|
|
|
|
_Relative_ paths are resolved relative to a _root_ directory, which is usually the base directory.
|
|
|
|
The base directory can be set via `FileModuleResolver::new_with_path` or
|
|
`FileModuleResolver::set_base_path`.
|
|
|
|
|
|
Custom [`Scope`]
|
|
----------------
|
|
|
|
```admonish tip.side.wide "Tip"
|
|
|
|
This [`Scope`] can conveniently hold global [constants] etc.
|
|
```
|
|
|
|
The `set_scope` method adds an optional [`Scope`] which will be used to [optimize][script optimization] [module] scripts.
|
|
|
|
|
|
Caching
|
|
-------
|
|
|
|
```admonish tip.side.wide "Tip: Enable/disable caching"
|
|
|
|
Use `enable_cache` to enable/disable the cache.
|
|
```
|
|
|
|
By default, [modules] are also _cached_ so a script file is only evaluated _once_, even when
|
|
repeatedly imported.
|
|
|
|
|
|
Unix Shebangs
|
|
-------------
|
|
|
|
On Unix-like systems, the _shebang_ (`#!`) is used at the very beginning of a script file to mark a
|
|
script with an interpreter (for Rhai this would be [`rhai-run`]({{rootUrl}}/start/bin.md)).
|
|
|
|
If a script file starts with `#!`, the entire first line is skipped.
|
|
Because of this, Rhai scripts with shebangs at the beginning need no special processing.
|
|
|
|
```js
|
|
#!/home/to/me/bin/rhai-run
|
|
|
|
// This is a Rhai script
|
|
|
|
let answer = 42;
|
|
print(`The answer is: ${answer}`);
|
|
```
|
|
|
|
|
|
Example
|
|
-------
|
|
|
|
|
|
```rust
|
|
┌────────────────┐
|
|
│ my_module.rhai │
|
|
└────────────────┘
|
|
|
|
// This function overrides any in the main script.
|
|
private fn inner_message() { "hello! from module!" }
|
|
|
|
fn greet() {
|
|
print(inner_message()); // call function in module script
|
|
}
|
|
|
|
fn greet_main() {
|
|
print(main_message()); // call function not in module script
|
|
}
|
|
|
|
|
|
┌───────────┐
|
|
│ main.rhai │
|
|
└───────────┘
|
|
|
|
// This function is overridden by the module script.
|
|
fn inner_message() { "hi! from main!" }
|
|
|
|
// This function is found by the module script.
|
|
fn main_message() { "main here!" }
|
|
|
|
import "my_module" as m;
|
|
|
|
m::greet(); // prints "hello! from module!"
|
|
|
|
m::greet_main(); // prints "main here!"
|
|
```
|
|
|
|
|
|
Simulate Virtual Functions
|
|
--------------------------
|
|
|
|
When calling a namespace-qualified [function] defined within a [module], other [functions] defined
|
|
within the same module override any similar-named [functions] (with the same number of parameters)
|
|
defined in the [global namespace][function namespace].
|
|
|
|
This is to ensure that a [module] acts as a self-contained unit and [functions] defined in the
|
|
calling script do not override [module] code.
|
|
|
|
In some situations, however, it is actually beneficial to do it in reverse: have [module] [functions] call
|
|
[functions] defined in the calling script (i.e. in the [global namespace][function namespace]) if
|
|
they exist, and only call those defined in the [module] if none are found.
|
|
|
|
One such situation is the need to provide a _default implementation_ to a simulated _virtual_ function:
|
|
|
|
```rust
|
|
┌────────────────┐
|
|
│ my_module.rhai │
|
|
└────────────────┘
|
|
|
|
// Do not do this (it will override the main script):
|
|
// fn message() { "hello! from module!" }
|
|
|
|
// This function acts as the default implementation.
|
|
private fn default_message() { "hello! from module!" }
|
|
|
|
// This function depends on a 'virtual' function 'message'
|
|
// which is not defined in the module script.
|
|
fn greet() {
|
|
if is_def_fn("message", 0) { // 'is_def_fn' detects if 'message' is defined.
|
|
print(message());
|
|
} else {
|
|
print(default_message());
|
|
}
|
|
}
|
|
|
|
|
|
┌───────────┐
|
|
│ main.rhai │
|
|
└───────────┘
|
|
|
|
// The main script defines 'message' which is needed by the module script.
|
|
fn message() { "hi! from main!" }
|
|
|
|
import "my_module" as m;
|
|
|
|
m::greet(); // prints "hi! from main!"
|
|
|
|
|
|
┌────────────┐
|
|
│ main2.rhai │
|
|
└────────────┘
|
|
|
|
// The main script does not define 'message' which is needed by the module script.
|
|
|
|
import "my_module" as m;
|
|
|
|
m::greet(); // prints "hello! from module!"
|
|
```
|
|
|