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

Rename packages to global modules.

Browse Source
This commit is contained in:
Stephen Chung
2020-12-22 23:45:14 +08:00
parent eb46ec8296
commit 15fb03218c
34 changed files with 192 additions and 218 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
doc/src/rust/modules/create.md
View File

@@ -19,14 +19,16 @@ Manually creating a [module] is possible via the `Module` API.
For the complete `Module` API, refer to the [documentation](https://docs.rs/rhai/{{version}}/rhai/struct.Module.html) online.
Make the `Module` Available to the `Engine`
------------------------------------------
Make the `Module` Globally Available
-----------------------------------
`Engine::load_package` supports loading a [module] as a [package].
`Engine::register_global_module` registers a shared [module] into the _global_ namespace.
Since it acts as a [package], all functions will be registered into the _global_ namespace
and can be accessed without _namespace qualifiers_. This is by far the easiest way to expose
a module's functionalities to Rhai.
All [functions] and [type iterators] can be accessed without _namespace qualifiers_.
Variables and sub-modules are **ignored**.
This is by far the easiest way to expose a module's functionalities to Rhai.
```rust
use rhai::{Engine, Module};
@@ -40,18 +42,18 @@ let hash = module.set_fn_1("inc", |x: i64| Ok(x+1));
// 'set_fn_XXX' by default does not set function metadata.
module.update_fn_metadata(hash, ["x: i64", "i64"]);
// Load the module into the Engine as a new package.
// Register the module into the global namespace of the Engine.
let mut engine = Engine::new();
engine.load_package(module);
engine.register_global_module(module);
engine.eval::<i64>("inc(41)")? == 42; // no need to import module
```
Make the `Module` a Global Module
------------------------------------
Make the `Module` a Static Module
--------------------------------
`Engine::register_module` loads a [module] and makes it available globally under a specific namespace.
`Engine::register_static_module` registers a [module] and under a specific module namespace.
```rust
use rhai::{Engine, Module};
@@ -65,9 +67,9 @@ let hash = module.set_fn_1("inc", |x: i64| Ok(x+1));
// 'set_fn_XXX' by default does not set function metadata.
module.update_fn_metadata(hash, ["x: i64", "i64"]);
// Load the module into the Engine as a sub-module named 'calc'
// Register the module into the Engine as a static module namespace 'calc'
let mut engine = Engine::new();
engine.register_module("calc", module);
engine.register_static_module("calc", module);
engine.eval::<i64>("calc::inc(41)")? == 42; // refer to the 'Calc' module
```
@@ -89,9 +91,9 @@ let hash = module.set_fn_1_mut("inc", FnNamespace::Global, |x: &mut i64| Ok(x+1)
// 'set_fn_XXX' by default does not set function metadata.
module.update_fn_metadata(hash, ["x: &mut i64", "i64"]);
// Load the module into the Engine as a sub-module named 'calc'
// Register the module into the Engine as a static module namespace 'calc'
let mut engine = Engine::new();
engine.register_module("calc", module);
engine.register_static_module("calc", module);
// The method 'inc' works as expected because it is exposed to the global namespace
engine.eval::<i64>("let x = 41; x.inc()")? == 42;

3
doc/src/rust/packages/builtin.md
View File

@@ -35,5 +35,6 @@ use rhai::packages::{Package, CorePackage};
let mut engine = Engine::new_raw();
let package = CorePackage::new();
engine.load_package(package.get());
// Register the package into the Engine by converting it into a shared module.
engine.register_global_module(package.as_shared_module());
```

12
doc/src/rust/packages/create.md
View File

@@ -1,17 +1,17 @@
Manually Create a Custom Package
===============================
Create a Custom Package
=======================
{{#include ../../links.md}}
Sometimes specific functionalities are needed, so custom packages can be created.
A custom package is a convenient means to gather up a number of functions for later use.
An [`Engine`] only needs to `Engine::load_package` the custom package once to gain access
An [`Engine`] only needs to `Engine::register_global_module` the custom package once to gain access
to the entire set of functions within.
Loading a package into an [`Engine`] is functionally equivalent to calling `Engine::register_fn` etc.
on _each_ of the functions inside the package. But because packages are _shared_, loading an existing
package is _much_ cheaper than registering all the functions one by one.
Registering a package into an [`Engine`] is functionally equivalent to calling `Engine::register_fn` etc.
on _each_ of the functions inside the package. But because packages are _shared_, using a package is
_much_ cheaper than registering all the functions one by one.
The macro `rhai::def_package!` can be used to create a new custom package.

53
doc/src/rust/packages/index.md
View File

@@ -3,16 +3,17 @@ Packages
{{#include ../../links.md}}
Standard built-in Rhai features are provided in various _packages_ that can be loaded via a call to `Engine::load_package`.
Standard built-in Rhai features are provided in various _packages_ that can be registered into the
_global namespace_ of an [`Engine`] via `Engine::register_global_module`.
Packages reside under `rhai::packages::*` and the trait `rhai::packages::Package` must be loaded in order for
packages to be used.
Packages typically contain Rust functions that are callable within a Rhai script.
All functions registered in a package is loaded under the _global namespace_
All _top-level_ functions in a package are available under the _global namespace_
(i.e. they're available without namespace qualifiers).
Once a package is created (e.g. via `Package::new`), it can be _shared_ (via `Package::get`)
Once a package is created (e.g. via `Package::new`), it can be _shared_ (via `Package::as_shared_module`)
among multiple instances of [`Engine`], even across threads (under [`sync`]).
Therefore, a package only has to be created _once_.
@@ -21,43 +22,21 @@ use rhai::Engine;
use rhai::packages::Package // load the 'Package' trait to use packages
use rhai::packages::CorePackage; // the 'core' package contains basic functionalities (e.g. arithmetic)
let mut engine = Engine::new_raw(); // create a 'raw' Engine
let package = CorePackage::new(); // create a package - can be shared among multiple `Engine` instances
// Create a 'raw' Engine
let mut engine = Engine::new_raw();
engine.load_package(package.get()); // load the package manually. 'get' returns a reference to the shared package
// Create a package - can be shared among multiple `Engine` instances
let package = CorePackage::new();
// Register the package into the global namespace.
// 'Package::as_shared_module' converts the package into a shared module.
engine.register_global_module(package.as_shared_module());
```
Difference Between a Package and a Module
----------------------------------------
Share a Package Among `Engine`s
------------------------------
Packages are internally implemented as [modules], so they share a lot of behavior and characteristics.
`Engine::register_global_module` consumes the input shared module.
The main difference is that a package loads under the _global_ namespace, while a module loads under its own
namespace alias specified in an [`import`] statement (see also [modules]).
A package is _static_ (i.e. pre-loaded into an [`Engine`]), while a module is _dynamic_ (i.e. loaded with
the `import` statement).
Sub-modules in a package are _flattened_, meaning that functions from them must be pulled up to the root level.
In other words, there can be no sub-modules in a package, and everything should reside in one, flat namespace.
Only functions matter for a package. Constant variables registered in a package are ignored.
Load a Module as a Package
--------------------------
Stand-alone [modules] can be loaded directly into an [`Engine`] as a package via the same `Engine::load_package` API.
```rust
let mut module = Module::new();
:
// add functions into module
:
engine.load_package(module);
```
[Modules], however, are not _shared_, so use a [custom package] if it must be shared among multiple
instances of [`Engine`].
However, `Package::as_shared_module` can be called multiple times for multiple instances of [`Engine`].

42
doc/src/rust/packages/plugin.md
View File

@@ -1,42 +0,0 @@
Load a Plugin Module as a Package
================================
{{#include ../../links.md}}
[Plugin modules] can be loaded as a package just like a normal [module]
via the `exported_module!` macro.
```rust
use rhai::Engine;
use rhai::plugin::*;
// Define plugin module.
#[export_module]
mod my_module {
pub fn greet(name: &str) -> String {
format!("hello, {}!", name)
}
pub fn get_num() -> i64 {
42
}
}
fn main() {
let mut engine = Engine::new();
// Create plugin module.
let module = exported_module!(my_module);
// Make the 'greet' and 'get_num' functions available to scripts.
engine.load_package(module);
}
```
Share a Package Among `Engine`s
------------------------------
Loading a [module] via `Engine::load_package` consumes the module and it cannot be used again.
If the functions are needed for multiple instances of [`Engine`], create a [custom package] from the
[plugin module], which can then be shared with `Package::get`.