reorganize module

_archive/rhai_engine/rhaibook/rust/modules/resolvers/file.md

@@ -0,0 +1,183 @@
+`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!"
+```
+