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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
RELEASES.md
View File

@ -4,6 +4,13 @@ Rhai Release Notes
Version 0.19.9
==============
Breaking changes
----------------
* `Engine::load_package` is renamed `Engine::register_global_module`.
* `Package::get` is renamed `Package::as_shared_module`.
* `Engine::register_module` is renamed `Engine::register_static_module`.
Version 0.19.8
==============
@ -103,7 +110,7 @@ New features
* New `switch` statement.
* New `do ... while` and `do ... until` statements.
* New `Engine::gen_fn_signatures`, `Module::gen_fn_signatures` and `PackagesCollection::gen_fn_signatures` to generate a list of signatures for functions registered.
* New `Engine::register_module` to register a module as a sub-module in the global namespace.
* New `Engine::register_static_module` to register a module as a sub-module in the global namespace.
* New `set_exported_global_fn!` macro to register a plugin function and expose it to the global namespace.
* `Module::set_fn_XXX_mut` can expose a module function to the global namespace. This is convenient when registering an API for a custom type.
* `Module::set_getter_fn`, `Module::set_setter_fn`, `Module::set_indexer_get_fn`, `Module::set_indexer_set_fn` all expose the function to the global namespace by default. This is convenient when registering an API for a custom type.
@ -370,7 +377,7 @@ Breaking changes
* `Engine::register_raw_fn_XXX` API shortcuts are removed.
* `PackagesCollection::get_fn`, `PackagesCollection::contains_fn`, `Module::get_fn` and `Module::contains_fn` now take an additional `public_only` parameter indicating whether only public functions are accepted.
* The iterator returned by `Scope::iter` now contains a clone of the `Dynamic` value (unshared).
* `Engine::load_package` takes any type that is `Into<PackageLibrary>`.
* `Engine::register_global_module` takes any type that is `Into<PackageLibrary>`.
* Error in `Engine::register_custom_syntax` is no longer `Box`-ed.
Housekeeping

2
benches/engine.rs
View File

@ -23,7 +23,7 @@ fn bench_engine_new_raw_core(bench: &mut Bencher) {
bench.iter(|| {
let mut engine = Engine::new_raw();
engine.load_package(package.get());
engine.register_global_module(package.as_shared_module());
});
}

2
benches/eval_module.rs
View File

@ -20,7 +20,7 @@ fn bench_eval_module(bench: &mut Bencher) {
let module = Module::eval_ast_as_new(Default::default(), &ast, &engine).unwrap();
engine.register_module("testing", module);
engine.register_static_module("testing", module);
let ast = engine
.compile(

10
codegen/src/lib.rs
View File

@ -160,7 +160,7 @@ pub fn export_fn(
///
/// let module = exported_module!(my_plugin_module);
///
/// engine.load_package(module);
/// engine.register_global_module(module);
///
/// assert_eq!(engine.eval::<i64>("foo(bar())")?, 42);
/// # Ok(())
@ -203,7 +203,7 @@ pub fn export_module(
///
/// let module = exported_module!(my_plugin_module);
///
/// engine.load_package(module);
/// engine.register_global_module(module);
///
/// assert_eq!(engine.eval::<i64>("foo(bar())")?, 42);
/// # Ok(())
@ -250,7 +250,7 @@ pub fn exported_module(module_path: proc_macro::TokenStream) -> proc_macro::Toke
/// let mut module = Module::new();
/// combine_with_exported_module!(&mut module, "my_plugin_module_ID", my_plugin_module);
///
/// engine.load_package(module);
/// engine.register_global_module(module);
///
/// assert_eq!(engine.eval::<i64>("foo(bar())")?, 42);
/// # Ok(())
@ -324,7 +324,7 @@ pub fn register_exported_fn(args: proc_macro::TokenStream) -> proc_macro::TokenS
/// let mut module = Module::new();
/// set_exported_fn!(module, "func", my_plugin_function);
///
/// engine.load_package(module);
/// engine.register_global_module(module);
///
/// assert_eq!(engine.eval::<i64>("func(21)")?, 42);
/// # Ok(())
@ -366,7 +366,7 @@ pub fn set_exported_fn(args: proc_macro::TokenStream) -> proc_macro::TokenStream
/// let mut module = Module::new();
/// set_exported_global_fn!(module, "func", my_plugin_function);
///
/// engine.register_module("test", module);
/// engine.register_static_module("test", module);
///
/// assert_eq!(engine.eval::<i64>("func(21)")?, 42);
/// # Ok(())

2
codegen/tests/test_modules.rs
View File

@ -257,7 +257,7 @@ mod multiple_fn_rename {
fn multiple_fn_rename_test() -> Result<(), Box<EvalAltResult>> {
let mut engine = Engine::new();
let m = rhai::exported_module!(crate::multiple_fn_rename::my_adds);
engine.load_package(m);
engine.register_global_module(m);
let output_array = engine.eval::<Array>(
r#"

3
doc/src/SUMMARY.md
View File

@ -43,8 +43,7 @@ The Rhai Scripting Language
4. [Printing Custom Types](rust/print-custom.md)
9. [Packages](rust/packages/index.md)
1. [Built-in Packages](rust/packages/builtin.md)
2. [Load a Plugin Module as a Package](rust/packages/plugin.md)
3. [Manually Create a Custom Package](rust/packages/create.md)
2. [Custom Packages](rust/packages/create.md)
10. [Modules](rust/modules/index.md)
1. [Create from Rust](rust/modules/create.md)
2. [Create from AST](rust/modules/ast.md)

6
doc/src/engine/metadata/export_to_json.md
View File

@ -20,9 +20,9 @@ Functions from the following sources are included:
1) Script-defined functions in an [`AST`] (for `Engine::gen_fn_metadata_with_ast_to_json`)
2) Native Rust functions registered into the global namespace via the `Engine::register_XXX` API
3) _Public_ (i.e. non-[`private`]) functions (native Rust or Rhai scripted) in global sub-modules registered via
[`Engine::register_module`]({{rootUrl}}/rust/modules/create.md)
4) Native Rust functions in registered [packages] (optional)
3) _Public_ (i.e. non-[`private`]) functions (native Rust or Rhai scripted) in static modules
registered via `Engine::register_static_module`
4) Native Rust functions in global modules registered via `Engine::register_global_module` (optional)
Notice that if a function has been [overloaded][function overloading], only the overriding function's
metadata is included.

6
doc/src/engine/metadata/gen_fn_sig.md
View File

@ -17,9 +17,9 @@ As part of a _reflections_ API, `Engine::gen_fn_signatures` returns a list of fu
Functions from the following sources are included, in order:
1) Native Rust functions registered into the global namespace via the `Engine::register_XXX` API
2) _Public_ (i.e. non-[`private`]) functions (native Rust or Rhai scripted) in global sub-modules registered via
[`Engine::register_module`]({{rootUrl}}/rust/modules/create.md)
3) Native Rust functions in registered [packages] (optional)
2) _Public_ (i.e. non-[`private`]) functions (native Rust or Rhai scripted) in global sub-modules
registered via `Engine::register_static_module`.
3) Native Rust functions in global modules registered via `Engine::register_global_module` (optional)
Functions Metadata

13
doc/src/language/fn-namespaces.md
View File

@ -15,10 +15,10 @@ allow combining all functions in one [`AST`] into another, forming a new, unifie
In general, there are two types of _namespaces_ where functions are looked up:
| Namespace | How Many | Source | Lookup method | Sub-modules? | Variables? |
| --------- | :------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | :----------: | :--------: |
| Global | One | 1) [`AST`] being evaluated<br/>2) `Engine::register_XXX` API<br/>3) [packages] loaded<br/>4) functions in [modules] loaded via `Engine::register_module` and marked _global_ | simple function name | ignored | ignored |
| Module | Many | [`Module`] | namespace-qualified function name | yes | yes |
| Namespace | How Many | Source | Lookup method | Sub-modules? | Variables? |
| --------- | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | :----------: | :--------: |
| Global | One | 1) [`AST`] being evaluated<br/>2) `Engine::register_XXX` API<br/>3) global [modules] loaded via `Engine::register_global_module`<br/>4) functions in static [modules] loaded via `Engine::register_static_module` and marked _global_ | simple function name | ignored | ignored |
| Module | Many | [`Module`] | namespace-qualified function name | yes | yes |
Module Namespace
@ -52,9 +52,10 @@ There is one _global_ namespace for every [`Engine`], which includes (in the fol
* All native Rust functions and iterators registered via the `Engine::register_XXX` API.
* All functions and iterators defined in [packages] that are loaded into the [`Engine`].
* All functions and iterators defined in global [modules] that are registered into the [`Engine`] via
`Engine::register_global_module`.
* Functions defined in [modules] loaded via `Engine::register_module` that are specifically marked
* Functions defined in [modules] loaded via `Engine::register_static_module` that are specifically marked
for exposure to the global namespace (e.g. via the `#[rhai(global)]` attribute in a [plugin module]).
Anywhere in a Rhai script, when a function call is made, the function is searched within the

2
doc/src/language/functions.md
View File

@ -172,7 +172,7 @@ Functions from the following sources are returned, in order:
1) Encapsulated script environment (e.g. when loading a [module] from a script file),
2) Current script,
3) [Modules] imported via the [`import`] statement (latest imports first),
4) [Modules] added via [`Engine::register_module`]({{rootUrl}}/rust/modules/create.md) (latest registrations first)
4) [Modules] added via [`Engine::register_static_module`]({{rootUrl}}/rust/modules/create.md) (latest registrations first)
The return value is an [array] of [object maps] (so `get_fn_metadata_list` is not available under
[`no_index`] or [`no_object`]), containing the following fields:

2
doc/src/language/modules/export.md
View File

@ -4,7 +4,7 @@ Export Variables, Functions and Sub-Modules in Module
{{#include ../../links.md}}
The easiest way to expose a package of functions as a self-contained [module] is to do it via a Rhai script itself.
The easiest way to expose a collection of functions as a self-contained [module] is to do it via a Rhai script itself.
See the section on [_Creating a Module from AST_]({{rootUrl}}/rust/modules/ast.md) for more details.

2
doc/src/patterns/enums.md
View File

@ -116,7 +116,7 @@ let mut engine = Engine::new();
// Load the module as the module namespace "MyEnum"
engine
.register_type_with_name::<MyEnum>("MyEnum")
.register_module("MyEnum", exported_module!(MyEnumModule));
.register_static_module("MyEnum", exported_module!(MyEnumModule));
```
With this API in place, working with enums feels almost the same as in Rust:

2
doc/src/patterns/events.md
View File

@ -100,7 +100,7 @@ impl Handler {
// Register custom types and API's
engine
.register_type_with_name::<SomeType>("SomeType")
.load_package(exported_module!(SomeTypeAPI));
.register_global_module(exported_module!(SomeTypeAPI));
// Create a custom 'Scope' to hold state
let mut scope = Scope::new();

25
doc/src/patterns/parallel.md
View File

@ -20,7 +20,8 @@ Usage Scenario
Key Concepts
------------
* Create a single instance of each standard [package] required. To duplicate `Engine::new`, create a [`StandardPackage`]({{rootUrl}}/rust/packages/builtin.md).
* Create a single instance of each standard [package] required.
To duplicate `Engine::new`, create a [`StandardPackage`]({{rootUrl}}/rust/packages/builtin.md).
* Gather up all common custom functions into a [custom package].
@ -29,10 +30,14 @@ Key Concepts
* Always use `Engine::new_raw` to create a [raw `Engine`], instead of `Engine::new` which is _much_ more expensive.
A [raw `Engine`] is _extremely_ cheap to create.
Loading the [`StandardPackage`]({{rootUrl}}/rust/packages/builtin.md) into a [raw `Engine`] via `Engine::load_package` is essentially the same as `Engine::new`.
But because packages are shared, loading an existing package is _much cheaper_ than registering all the functions one by one.
Registering the [`StandardPackage`]({{rootUrl}}/rust/packages/builtin.md) into a [raw `Engine`] via
`Engine::register_global_module` is essentially the same as `Engine::new`.
* Load the required packages into the [raw `Engine`] via `Engine::load_package`, using `Package::get` to obtain a shared copy.
However, because packages are shared, using existing package is _much cheaper_ than
registering all the functions one by one.
* Register the required packages with the [raw `Engine`] via `Engine::register_global_module`,
using `Package::as_shared_module` to obtain a shared [module].
Examples
@ -46,17 +51,17 @@ let std_pkg = StandardPackage::new();
let custom_pkg = MyCustomPackage::new();
let make_call = |x: i64| -> Result<(), Box<EvalAltResult>> {
// Create a raw Engine - extremely cheap.
// Create a raw Engine - extremely cheap
let mut engine = Engine::new_raw();
// Load packages - cheap.
engine.load_package(std_pkg.get());
engine.load_package(custom_pkg.get());
// Register packages as global modules - cheap
engine.register_global_module(std_pkg.as_shared_module());
engine.register_global_module(custom_pkg.as_shared_module());
// Create custom scope - cheap.
// Create custom scope - cheap
let mut scope = Scope::new();
// Push variable into scope - relatively cheap.
// Push variable into scope - relatively cheap
scope.push("x", x);
// Evaluate script.

2
doc/src/patterns/singleton.md
View File

@ -146,7 +146,7 @@ pub mod bunny_api {
}
}
engine.load_package(exported_module!(bunny_api));
engine.register_global_module(exported_module!(bunny_api));
```
### Push Constant Command Object into Custom Scope

48
doc/src/plugins/module.md
View File

@ -28,11 +28,11 @@ and is custom fit to each exported item.
All `pub` functions become registered functions, all `pub` constants become [module] constant variables,
and all sub-modules become Rhai sub-modules.
This Rust module can then either be loaded into an [`Engine`] as a normal [module] or
registered as a [package]. This is done by using the `exported_module!` macro.
This Rust module can then be registered into an [`Engine`] as a normal [module].
This is done via the `exported_module!` macro.
The macro `combine_with_exported_module!` can also be used to _combine_ all the functions
and variables into an existing module, _flattening_ the namespace - i.e. all sub-modules
The macro `combine_with_exported_module!` can be used to _combine_ all the functions
and variables into an existing [module], _flattening_ the namespace - i.e. all sub-modules
are eliminated and their contents promoted to the top level. This is typical for
developing [custom packages].
@ -42,7 +42,7 @@ use rhai::plugin::*; // a "prelude" import for macros
#[export_module]
mod my_module {
// This constant will be registered as the constant variable 'MY_NUMBER'.
// Ignored when loaded as a package.
// Ignored when registered as a global module.
pub const MY_NUMBER: i64 = 42;
// This function will be registered as 'greet'.
@ -64,9 +64,9 @@ mod my_module {
42
}
// Sub-modules are ignored when the Module is loaded as a package.
// Sub-modules are ignored when the module is registered globally.
pub mod my_sub_module {
// This function is ignored when loaded as a package.
// This function is ignored when registered globally.
// Otherwise it is a valid registered function under a sub-module.
pub fn get_info() -> String {
"hello".to_string()
@ -78,7 +78,7 @@ mod my_module {
// This is currently a limitation of the plugin procedural macros.
#[cfg(feature = "advanced_functions")]
pub mod advanced {
// This function is ignored when loaded as a package.
// This function is ignored when registered globally.
// Otherwise it is a valid registered function under a sub-module
// which only exists when the 'advanced_functions' feature is used.
pub fn advanced_calc(input: i64) -> i64 {
@ -88,10 +88,10 @@ mod my_module {
}
```
### Use `Engine::load_package`
### Use `Engine::register_global_module`
The simplest way to load this into an [`Engine`] is to first use the `exported_module!` macro
to turn it into a normal Rhai [module], then use the `Engine::load_package` method on it:
The simplest way to register this into an [`Engine`] is to first use the `exported_module!` macro
to turn it into a normal Rhai [module], then use the `Engine::register_global_module` method on it:
```rust
fn main() {
@ -100,13 +100,13 @@ fn main() {
// The macro call creates a Rhai module from the plugin module.
let module = exported_module!(my_module);
// A module can simply be loaded, registering all public functions.
engine.load_package(module);
// A module can simply be registered into the global namespace.
engine.register_global_module(module);
}
```
The functions contained within the module definition (i.e. `greet`, `get_num` and `increment`)
are automatically registered into the [`Engine`] when `Engine::load_package` is called.
are automatically registered into the [`Engine`] when `Engine::register_global_module` is called.
```rust
let x = greet("world");
@ -123,12 +123,14 @@ x == 43;
```
Notice that, when using a [module] as a [package], only functions registered at the _top level_
can be accessed. Variables as well as sub-modules are ignored.
can be accessed.
### Use `Engine::register_module`
Variables as well as sub-modules are **ignored**.
Another simple way to load this into an [`Engine`] is, again, to use the `exported_module!` macro
to turn it into a normal Rhai [module], then use the `Engine::register_module` method on it:
### Use `Engine::register_static_module`
Another simple way to register this into an [`Engine`] is, again, to use the `exported_module!` macro
to turn it into a normal Rhai [module], then use the `Engine::register_static_module` method on it:
```rust
fn main() {
@ -137,13 +139,13 @@ fn main() {
// The macro call creates a Rhai module from the plugin module.
let module = exported_module!(my_module);
// A module can simply be loaded as a globally-available module.
engine.register_module("service", module);
// A module can simply be registered as a static module namespace.
engine.register_static_module("service", module);
}
```
The functions contained within the module definition (i.e. `greet`, `get_num` and `increment`),
plus the constant `MY_NUMBER`, are automatically loaded under the module namespace `service`:
plus the constant `MY_NUMBER`, are automatically registered under the module namespace `service`:
```rust
let x = service::greet("world");
@ -178,14 +180,14 @@ x.increment();
x == 43;
```
### Use as loadable `Module`
### Use Dynamically
Using this directly as a dynamically-loadable Rhai [module] is almost the same, except that a
[module resolver] must be used to serve the module, and the module is loaded via `import` statements.
See the [module] section for more information.
### Use as custom package
### Combine into Custom Package
Finally the plugin module can also be used to develop a [custom package],
using `combine_with_exported_module!`:

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`.

4
doc/src/start/builds/minimal.md
View File

@ -49,6 +49,6 @@ Use a Raw [`Engine`]
A _raw_ engine supports, out of the box, only a very [restricted set]({{rootUrl}}/engine/raw.md#built-in-operators)
of basic arithmetic and logical operators.
Selectively include other necessary functionalities by loading specific [packages] to minimize the footprint.
Selectively include other necessary functionalities by picking specific [packages] to minimize the footprint.
Packages are sharable (even across threads via the [`sync`] feature), so they only have to be created once.
Packages are shared (even across threads via the [`sync`] feature), so they only have to be created once.

24
src/engine.rs
View File

@ -613,8 +613,8 @@ pub struct Engine {
/// A module containing all functions directly loaded into the Engine.
pub(crate) global_namespace: Module,
/// A collection of all library packages loaded into the Engine.
pub(crate) packages: StaticVec<Shared<Module>>,
/// A collection of all modules loaded into the global namespace of the Engine.
pub(crate) global_modules: StaticVec<Shared<Module>>,
/// A collection of all sub-modules directly loaded into the Engine.
pub(crate) global_sub_modules: Imports,
@ -745,8 +745,8 @@ impl Engine {
let mut engine = Self {
id: Default::default(),
packages: Default::default(),
global_namespace: Default::default(),
global_modules: Default::default(),
global_sub_modules: Default::default(),
#[cfg(not(feature = "no_module"))]
@ -798,20 +798,20 @@ impl Engine {
disable_doc_comments: false,
};
engine.load_package(StandardPackage::new().get());
engine.register_global_module(StandardPackage::new().as_shared_module());
engine
}
/// Create a new [`Engine`] with minimal built-in functions.
/// Use the [`load_package`][Engine::load_package] method to load additional packages of functions.
/// Use the [`register_global_module`][Engine::register_global_module] method to load additional packages of functions.
#[inline]
pub fn new_raw() -> Self {
Self {
id: Default::default(),
packages: Default::default(),
global_namespace: Default::default(),
global_modules: Default::default(),
global_sub_modules: Default::default(),
#[cfg(not(feature = "no_module"))]
@ -1971,7 +1971,11 @@ impl Engine {
match self
.global_namespace
.get_fn(hash_fn, false)
.or_else(|| self.packages.iter().find_map(|m| m.get_fn(hash_fn, false)))
.or_else(|| {
self.global_modules
.iter()
.find_map(|m| m.get_fn(hash_fn, false))
})
.or_else(|| mods.get_fn(hash_fn))
{
// op= function registered as method
@ -2180,7 +2184,11 @@ impl Engine {
let func = self
.global_namespace
.get_iter(iter_type)
.or_else(|| self.packages.iter().find_map(|m| m.get_iter(iter_type)))
.or_else(|| {
self.global_modules
.iter()
.find_map(|m| m.get_iter(iter_type))
})
.or_else(|| mods.get_iter(iter_type));
if let Some(func) = func {

34
src/engine_api.rs
View File

@ -14,8 +14,8 @@ use crate::stdlib::{
};
use crate::utils::get_hasher;
use crate::{
scope::Scope, Dynamic, Engine, EvalAltResult, FnAccess, FnNamespace, NativeCallContext,
ParseError, Position, AST,
scope::Scope, Dynamic, Engine, EvalAltResult, FnAccess, FnNamespace, Module, NativeCallContext,
ParseError, Position, Shared, AST,
};
#[cfg(not(feature = "no_index"))]
@ -723,7 +723,23 @@ impl Engine {
self.register_indexer_get(getter)
.register_indexer_set(setter)
}
/// Register a [`Module`][crate::Module] as a fixed module namespace with the [`Engine`].
/// Register a shared [`Module`][crate::Module] into the global namespace of [`Engine`].
///
/// All functions and type iterators are automatically available to scripts without namespace qualifications.
///
/// Sub-modules and variables are **ignored**.
///
/// When searching for functions, modules loaded later are preferred.
/// In other words, loaded modules are searched in reverse order.
#[inline(always)]
pub fn register_global_module(&mut self, package: impl Into<Shared<Module>>) -> &mut Self {
// Insert the module into the front
self.global_modules.insert(0, package.into());
self
}
/// Register a shared [`Module`][crate::Module] as a static module namespace with the [`Engine`].
///
/// Functions marked `FnNamespace::Global` and type iterators are exposed to scripts without namespace qualifications.
///
/// # Example
///
@ -738,17 +754,17 @@ impl Engine {
/// module.set_fn_1("calc", |x: i64| Ok(x + 1));
///
/// // Register the module as a fixed sub-module
/// engine.register_module("CalcService", module);
/// engine.register_static_module("CalcService", module);
///
/// assert_eq!(engine.eval::<i64>("CalcService::calc(41)")?, 42);
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_module"))]
pub fn register_module(
pub fn register_static_module(
&mut self,
name: impl Into<crate::ImmutableString>,
module: impl Into<crate::Shared<crate::Module>>,
module: impl Into<Shared<Module>>,
) -> &mut Self {
let module = module.into();
@ -1681,7 +1697,11 @@ impl Engine {
});
if include_packages {
signatures.extend(self.packages.iter().flat_map(|m| m.gen_fn_signatures()));
signatures.extend(
self.global_modules
.iter()
.flat_map(|m| m.gen_fn_signatures()),
);
}
signatures

12
src/engine_settings.rs
View File

@ -2,22 +2,12 @@
use crate::stdlib::{format, string::String};
use crate::token::{is_valid_identifier, Token};
use crate::{Engine, Module, Shared};
use crate::Engine;
#[cfg(not(feature = "no_module"))]
use crate::stdlib::boxed::Box;
impl Engine {
/// Load a new package into the [`Engine`].
/// A simple [`Module`][crate::Module] is automatically converted into a package.
///
/// When searching for functions, packages loaded later are preferred.
/// In other words, loaded packages are searched in reverse order.
#[inline(always)]
pub fn load_package(&mut self, package: impl Into<Shared<Module>>) -> &mut Self {
self.packages.insert(0, package.into());
self
}
/// Control whether and how the [`Engine`] will optimize an [`AST`][crate::AST] after compilation.
///
/// Not available under the `no_optimize` feature.

12
src/fn_call.rs
View File

@ -184,7 +184,11 @@ impl Engine {
let f = self
.global_namespace
.get_fn(hash_fn, pub_only)
.or_else(|| self.packages.iter().find_map(|m| m.get_fn(hash_fn, false)))
.or_else(|| {
self.global_modules
.iter()
.find_map(|m| m.get_fn(hash_fn, false))
})
.or_else(|| mods.get_fn(hash_fn));
state.functions_cache.insert(hash_fn, f.cloned());
@ -460,8 +464,8 @@ impl Engine {
//|| (hash_script != 0 && self.global_namespace.contains_fn(hash_script, pub_only))
|| self.global_namespace.contains_fn(hash_fn, false)
// Then check packages
|| (hash_script != 0 && self.packages.iter().any(|m| m.contains_fn(hash_script, false)))
|| self.packages.iter().any(|m| m.contains_fn(hash_fn, false))
|| (hash_script != 0 && self.global_modules.iter().any(|m| m.contains_fn(hash_script, false)))
|| self.global_modules.iter().any(|m| m.contains_fn(hash_fn, false))
// Then check imported modules
|| (hash_script != 0 && mods.map(|m| m.contains_fn(hash_script)).unwrap_or(false))
|| mods.map(|m| m.contains_fn(hash_fn)).unwrap_or(false)
@ -542,7 +546,7 @@ impl Engine {
})
//.or_else(|| self.global_namespace.get_fn(hash_script, pub_only))
.or_else(|| {
self.packages
self.global_modules
.iter()
.find_map(|m| m.get_fn(hash_script, false))
.map(|f| (f, None))

8
src/packages/mod.rs
View File

@ -1,8 +1,6 @@
//! Module containing all built-in _packages_ available to Rhai, plus facilities to define custom packages.
use crate::fn_native::{CallableFunction, IteratorFn};
use crate::stdlib::{any::TypeId, string::String};
use crate::{Module, Shared, StaticVec};
use crate::{Module, Shared};
pub(crate) mod arithmetic;
mod array_basic;
@ -39,7 +37,7 @@ pub trait Package {
fn init(lib: &mut Module);
/// Retrieve the generic package library from this package.
fn get(&self) -> Shared<Module>;
fn as_shared_module(&self) -> Shared<Module>;
}
/// Macro that makes it easy to define a _package_ (which is basically a shared module)
@ -71,7 +69,7 @@ macro_rules! def_package {
pub struct $package($root::Shared<$root::Module>);
impl $root::packages::Package for $package {
fn get(&self) -> $root::Shared<$root::Module> {
fn as_shared_module(&self) -> $root::Shared<$root::Module> {
self.0.clone()
}

18
src/serde_impl/metadata.rs
View File

@ -219,17 +219,17 @@ impl Engine {
/// Functions from the following sources are included:
/// 1) Functions defined in an [`AST`][crate::AST]
/// 2) Functions registered into the global namespace
/// 3) Functions in registered sub-modules
/// 4) Functions in packages (optional)
/// 3) Functions in static modules
/// 4) Functions in global modules (optional)
pub fn gen_fn_metadata_with_ast_to_json(
&self,
ast: &AST,
include_packages: bool,
include_global: bool,
) -> serde_json::Result<String> {
let mut global: ModuleMetadata = Default::default();
if include_packages {
self.packages
if include_global {
self.global_modules
.iter()
.flat_map(|m| m.iter_fn().map(|f| f.into()))
.for_each(|info| global.functions.push(info));
@ -260,9 +260,9 @@ impl Engine {
///
/// Functions from the following sources are included:
/// 1) Functions registered into the global namespace
/// 2) Functions in registered sub-modules
/// 3) Functions in packages (optional)
pub fn gen_fn_metadata_to_json(&self, include_packages: bool) -> serde_json::Result<String> {
self.gen_fn_metadata_with_ast_to_json(&Default::default(), include_packages)
/// 2) Functions in static modules
/// 3) Functions in global modules (optional)
pub fn gen_fn_metadata_to_json(&self, include_global: bool) -> serde_json::Result<String> {
self.gen_fn_metadata_with_ast_to_json(&Default::default(), include_global)
}
}

2
tests/for.rs
View File

@ -101,7 +101,7 @@ fn test_for_module_iterator() -> Result<(), Box<EvalAltResult>> {
let mut module = Module::new();
module.set_sub_module("inner", sub_module);
engine.register_module("testing", module);
engine.register_static_module("testing", module);
let script = r#"
let item = testing::inner::new_ts();

2
tests/functions.rs
View File

@ -62,7 +62,7 @@ fn test_functions_namespaces() -> Result<(), Box<EvalAltResult>> {
let hash = m.set_fn_0("test", || Ok(999 as INT));
m.update_fn_namespace(hash, FnNamespace::Global);
engine.register_module("hello", m);
engine.register_static_module("hello", m);
assert_eq!(engine.eval::<INT>("test()")?, 999);
assert_eq!(engine.eval::<INT>("fn test() { 123 } test()")?, 123);

2
tests/modules.rs
View File

@ -44,7 +44,7 @@ fn test_module_sub_module() -> Result<(), Box<EvalAltResult>> {
assert_eq!(m2.get_var_value::<INT>("answer").unwrap(), 41);
let mut engine = Engine::new();
engine.register_module("question", module);
engine.register_static_module("question", module);
assert_eq!(engine.eval::<INT>("question::MYSTIC_NUMBER")?, 42);
assert!(engine.eval::<INT>("MYSTIC_NUMBER").is_err());

6
tests/packages.rs
View File

@ -11,8 +11,8 @@ fn test_packages() -> Result<(), Box<EvalAltResult>> {
// Create a raw Engine - extremely cheap.
let mut engine = Engine::new_raw();
// Load packages - cheap.
engine.load_package(std_pkg.get());
// Register packages - cheap.
engine.register_global_module(std_pkg.as_shared_module());
// Create custom scope - cheap.
let mut scope = Scope::new();
@ -37,7 +37,7 @@ fn test_packages_with_script() -> Result<(), Box<EvalAltResult>> {
let ast = engine.compile("fn foo(x) { x + 1 } fn bar(x) { foo(x) + 1 }")?;
let module = Module::eval_ast_as_new(Scope::new(), &ast, &engine)?;
engine.load_package(module);
engine.register_global_module(module);
assert_eq!(engine.eval::<INT>("foo(41)")?, 42);
assert_eq!(engine.eval::<INT>("bar(40)")?, 42);

4
tests/plugins.rs
View File

@ -77,7 +77,7 @@ fn test_plugins_package() -> Result<(), Box<EvalAltResult>> {
let mut m = Module::new();
combine_with_exported_module!(&mut m, "test", test::special_array_package);
engine.load_package(m);
engine.register_global_module(m);
reg_functions!(engine += greet::single(INT, bool, char));
@ -95,7 +95,7 @@ fn test_plugins_package() -> Result<(), Box<EvalAltResult>> {
"6 kitties"
);
engine.register_module("test", exported_module!(test::special_array_package));
engine.register_static_module("test", exported_module!(test::special_array_package));
assert_eq!(engine.eval::<INT>("test::MYSTIC_NUMBER")?, 42);

2
tests/plugins_unroll.rs
View File

@ -52,7 +52,7 @@ fn test_generated_ops() -> Result<(), Box<EvalAltResult>> {
register_in_bulk!(m, add, i8, i16, i32, i64);
register_in_bulk!(m, mul, i8, i16, i32, i64);
engine.load_package(m);
engine.register_global_module(m);
#[cfg(feature = "only_i32")]
assert_eq!(engine.eval::<INT>("let a = 0; add_i32(a, 1)")?, 1);