diff --git a/RELEASES.md b/RELEASES.md index cd9974cb..79824a05 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -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`. +* `Engine::register_global_module` takes any type that is `Into`. * Error in `Engine::register_custom_syntax` is no longer `Box`-ed. Housekeeping diff --git a/benches/engine.rs b/benches/engine.rs index f1ac588b..0cfc2972 100644 --- a/benches/engine.rs +++ b/benches/engine.rs @@ -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()); }); } diff --git a/benches/eval_module.rs b/benches/eval_module.rs index ac6f56d4..a3a3920a 100644 --- a/benches/eval_module.rs +++ b/benches/eval_module.rs @@ -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( diff --git a/codegen/src/lib.rs b/codegen/src/lib.rs index 38ee893a..ff96271b 100644 --- a/codegen/src/lib.rs +++ b/codegen/src/lib.rs @@ -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::("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::("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::("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::("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::("func(21)")?, 42); /// # Ok(()) diff --git a/codegen/tests/test_modules.rs b/codegen/tests/test_modules.rs index 2217b384..7f4fb462 100644 --- a/codegen/tests/test_modules.rs +++ b/codegen/tests/test_modules.rs @@ -257,7 +257,7 @@ mod multiple_fn_rename { fn multiple_fn_rename_test() -> Result<(), Box> { 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::( r#" diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md index a0a76d3c..4adec297 100644 --- a/doc/src/SUMMARY.md +++ b/doc/src/SUMMARY.md @@ -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) diff --git a/doc/src/engine/metadata/export_to_json.md b/doc/src/engine/metadata/export_to_json.md index add09c16..13d2da72 100644 --- a/doc/src/engine/metadata/export_to_json.md +++ b/doc/src/engine/metadata/export_to_json.md @@ -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. diff --git a/doc/src/engine/metadata/gen_fn_sig.md b/doc/src/engine/metadata/gen_fn_sig.md index ee8390fc..30067c60 100644 --- a/doc/src/engine/metadata/gen_fn_sig.md +++ b/doc/src/engine/metadata/gen_fn_sig.md @@ -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 diff --git a/doc/src/language/fn-namespaces.md b/doc/src/language/fn-namespaces.md index 61111f65..ef4cbd77 100644 --- a/doc/src/language/fn-namespaces.md +++ b/doc/src/language/fn-namespaces.md @@ -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
2) `Engine::register_XXX` API
3) [packages] loaded
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
2) `Engine::register_XXX` API
3) global [modules] loaded via `Engine::register_global_module`
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 diff --git a/doc/src/language/functions.md b/doc/src/language/functions.md index 677deebc..1a896346 100644 --- a/doc/src/language/functions.md +++ b/doc/src/language/functions.md @@ -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: diff --git a/doc/src/language/modules/export.md b/doc/src/language/modules/export.md index 6ff7ea3b..362ca111 100644 --- a/doc/src/language/modules/export.md +++ b/doc/src/language/modules/export.md @@ -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. diff --git a/doc/src/patterns/enums.md b/doc/src/patterns/enums.md index c061bab9..6adeb6d4 100644 --- a/doc/src/patterns/enums.md +++ b/doc/src/patterns/enums.md @@ -116,7 +116,7 @@ let mut engine = Engine::new(); // Load the module as the module namespace "MyEnum" engine .register_type_with_name::("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: diff --git a/doc/src/patterns/events.md b/doc/src/patterns/events.md index e7c5d946..24574612 100644 --- a/doc/src/patterns/events.md +++ b/doc/src/patterns/events.md @@ -100,7 +100,7 @@ impl Handler { // Register custom types and API's engine .register_type_with_name::("SomeType") - .load_package(exported_module!(SomeTypeAPI)); + .register_global_module(exported_module!(SomeTypeAPI)); // Create a custom 'Scope' to hold state let mut scope = Scope::new(); diff --git a/doc/src/patterns/parallel.md b/doc/src/patterns/parallel.md index e070b78d..3db89b3f 100644 --- a/doc/src/patterns/parallel.md +++ b/doc/src/patterns/parallel.md @@ -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`. + + However, because packages are shared, using existing package is _much cheaper_ than + registering all the functions one by one. -* Load the required packages into the [raw `Engine`] via `Engine::load_package`, using `Package::get` to obtain a shared copy. +* 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> { - // 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. diff --git a/doc/src/patterns/singleton.md b/doc/src/patterns/singleton.md index 6f59f70a..316ab302 100644 --- a/doc/src/patterns/singleton.md +++ b/doc/src/patterns/singleton.md @@ -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 diff --git a/doc/src/plugins/module.md b/doc/src/plugins/module.md index a8343220..a6b3b8af 100644 --- a/doc/src/plugins/module.md +++ b/doc/src/plugins/module.md @@ -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!`: diff --git a/doc/src/rust/modules/create.md b/doc/src/rust/modules/create.md index 4c279800..d0af3a55 100644 --- a/doc/src/rust/modules/create.md +++ b/doc/src/rust/modules/create.md @@ -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::("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::("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::("let x = 41; x.inc()")? == 42; diff --git a/doc/src/rust/packages/builtin.md b/doc/src/rust/packages/builtin.md index a430e17e..5d49ca0a 100644 --- a/doc/src/rust/packages/builtin.md +++ b/doc/src/rust/packages/builtin.md @@ -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()); ``` diff --git a/doc/src/rust/packages/create.md b/doc/src/rust/packages/create.md index ec573804..9b3f654a 100644 --- a/doc/src/rust/packages/create.md +++ b/doc/src/rust/packages/create.md @@ -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. diff --git a/doc/src/rust/packages/index.md b/doc/src/rust/packages/index.md index fe6fc36f..541e6f49 100644 --- a/doc/src/rust/packages/index.md +++ b/doc/src/rust/packages/index.md @@ -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`]. diff --git a/doc/src/rust/packages/plugin.md b/doc/src/rust/packages/plugin.md deleted file mode 100644 index 509aff32..00000000 --- a/doc/src/rust/packages/plugin.md +++ /dev/null @@ -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`. diff --git a/doc/src/start/builds/minimal.md b/doc/src/start/builds/minimal.md index 71ed7bd9..45882382 100644 --- a/doc/src/start/builds/minimal.md +++ b/doc/src/start/builds/minimal.md @@ -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. diff --git a/src/engine.rs b/src/engine.rs index 90f81283..bb6cb872 100644 --- a/src/engine.rs +++ b/src/engine.rs @@ -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>, + /// A collection of all modules loaded into the global namespace of the Engine. + pub(crate) global_modules: StaticVec>, /// 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 { diff --git a/src/engine_api.rs b/src/engine_api.rs index 78b96e6c..4506601b 100644 --- a/src/engine_api.rs +++ b/src/engine_api.rs @@ -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>) -> &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::("CalcService::calc(41)")?, 42); /// # Ok(()) /// # } /// ``` #[cfg(not(feature = "no_module"))] - pub fn register_module( + pub fn register_static_module( &mut self, name: impl Into, - module: impl Into>, + module: impl Into>, ) -> &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 diff --git a/src/engine_settings.rs b/src/engine_settings.rs index e61dc08f..7d5d17f4 100644 --- a/src/engine_settings.rs +++ b/src/engine_settings.rs @@ -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>) -> &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. diff --git a/src/fn_call.rs b/src/fn_call.rs index 68701342..6d19919d 100644 --- a/src/fn_call.rs +++ b/src/fn_call.rs @@ -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)) diff --git a/src/packages/mod.rs b/src/packages/mod.rs index e5bffc58..89bb7fbb 100644 --- a/src/packages/mod.rs +++ b/src/packages/mod.rs @@ -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; + fn as_shared_module(&self) -> Shared; } /// 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() } diff --git a/src/serde_impl/metadata.rs b/src/serde_impl/metadata.rs index da0e6ab1..b8bb010b 100644 --- a/src/serde_impl/metadata.rs +++ b/src/serde_impl/metadata.rs @@ -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 { 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 { - 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 { + self.gen_fn_metadata_with_ast_to_json(&Default::default(), include_global) } } diff --git a/tests/for.rs b/tests/for.rs index 56899fd1..fea8e56e 100644 --- a/tests/for.rs +++ b/tests/for.rs @@ -101,7 +101,7 @@ fn test_for_module_iterator() -> Result<(), Box> { 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(); diff --git a/tests/functions.rs b/tests/functions.rs index 2034095f..e8e10cec 100644 --- a/tests/functions.rs +++ b/tests/functions.rs @@ -62,7 +62,7 @@ fn test_functions_namespaces() -> Result<(), Box> { 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::("test()")?, 999); assert_eq!(engine.eval::("fn test() { 123 } test()")?, 123); diff --git a/tests/modules.rs b/tests/modules.rs index 656dc728..fb799343 100644 --- a/tests/modules.rs +++ b/tests/modules.rs @@ -44,7 +44,7 @@ fn test_module_sub_module() -> Result<(), Box> { assert_eq!(m2.get_var_value::("answer").unwrap(), 41); let mut engine = Engine::new(); - engine.register_module("question", module); + engine.register_static_module("question", module); assert_eq!(engine.eval::("question::MYSTIC_NUMBER")?, 42); assert!(engine.eval::("MYSTIC_NUMBER").is_err()); diff --git a/tests/packages.rs b/tests/packages.rs index ae31e719..8729c373 100644 --- a/tests/packages.rs +++ b/tests/packages.rs @@ -11,8 +11,8 @@ fn test_packages() -> Result<(), Box> { // 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> { 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::("foo(41)")?, 42); assert_eq!(engine.eval::("bar(40)")?, 42); diff --git a/tests/plugins.rs b/tests/plugins.rs index e3e8d1a1..ed9d5d07 100644 --- a/tests/plugins.rs +++ b/tests/plugins.rs @@ -77,7 +77,7 @@ fn test_plugins_package() -> Result<(), Box> { 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> { "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::("test::MYSTIC_NUMBER")?, 42); diff --git a/tests/plugins_unroll.rs b/tests/plugins_unroll.rs index c872381a..533f2de8 100644 --- a/tests/plugins_unroll.rs +++ b/tests/plugins_unroll.rs @@ -52,7 +52,7 @@ fn test_generated_ops() -> Result<(), Box> { 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::("let a = 0; add_i32(a, 1)")?, 1);