herocode/rhaj
Archived
13
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

reorganize module

Browse Source
This commit is contained in:
Timur Gordon
2025-04-04 08:28:07 +02:00
parent 1ea37e2e7f
commit 939b6b4e57
375 changed files with 7580 additions and 191 deletions
Download Patch File Download Diff File Expand all files Collapse all files

256
_archive/rhai_engine/rhaibook/rust/packages/create.md Normal file
View File

@@ -0,0 +1,256 @@
Create a Custom Package
=======================
{{#include ../../links.md}}
```admonish info.side "See also"
See also the [_One Engine Instance Per Call_]({{rootUrl}}/patterns/parallel.md) pattern.
```
The macro `def_package!` can be used to create a custom [package].
A custom [package] can aggregate many other [packages] into a single self-contained unit.
More functions can be added on top of others.
Custom [packages] are extremely useful when multiple [raw `Engine`] instances must be created such
that they all share the same set of functions.
`def_package!`
--------------
> ```rust
> def_package! {
> /// Package description doc-comment
> pub name(variable) {
> :
> // package init code block
> :
> }
>
> // Multiple packages can be defined at the same time,
> // possibly with base packages and/or code to setup an Engine.
>
> /// Package description doc-comment
> pub(crate) name(variable) : base_package_1, base_package_2, ... {
> :
> // package init code block
> :
> } |> |engine| {
> :
> // engine setup code block
> :
> }
>
> /// A private package description doc-comment
> name(variable) {
> :
> // private package init code block
> :
> }
>
> :
> }
> ```
where:
| Element | Description |
| :---------------------: | ---------------------------------------------------------------------------------------------------- |
| description | doc-comment for the [package] |
| `pub` etc. | visibility of the [package] |
| name | name of the [package], usually ending in ...`Package` |
| variable | a variable name holding a reference to the [module] forming the [package], usually `module` or `lib` |
| base_package | an external [package] type that is merged into this [package] as a dependency |
| package init code block | a code block that initializes the [package] |
| engine | a variable name holding a mutable reference to an [`Engine`] |
| engine setup code block | a code block that performs setup tasks on an [`Engine`] during registration |
Examples
--------
```rust
// Import necessary types and traits.
use rhai::def_package; // 'def_package!' macro
use rhai::packages::{ArithmeticPackage, BasicArrayPackage, BasicMapPackage, LogicPackage};
use rhai::{FuncRegistration, CustomType, TypeBuilder};
/// This is a custom type.
#[derive(Clone, CustomType)]
struct TestStruct {
foo: String,
bar: i64,
baz: bool
}
def_package! {
/// My own personal super package
// Aggregate other base packages (if any) simply by listing them after a colon.
pub MyPackage(module) : ArithmeticPackage, LogicPackage, BasicArrayPackage, BasicMapPackage
{
// Register additional Rust function.
FuncRegistration::new("get_bar_value")
.with_params_info(&["s: &mut TestStruct", "i64"])
.set_into_module(module, |s: &mut TestStruct| s.bar);
// Register a function for use as a custom operator.
FuncRegistration::new("@")
.with_namespace(FnNamespace::Global) // <- make it available globally.
.set_into_module(module, |x: i64, y: i64| x * x + y * y);
} |> |engine| {
// This optional block performs tasks on an 'Engine' instance,
// e.g. register custom types and/or custom operators/syntax.
// Register custom type.
engine.build_type::<TestStruct>();
// Define a custom operator '@' with precedence of 160
// (i.e. between +|- and *|/).
engine.register_custom_operator("@", 160).unwrap();
}
}
```
~~~admonish tip.small "Tip: Feature gates on base packages"
Base packages in the list after the colon (`:`) can also have attributes (such as feature gates)!
```rust
def_package! {
// 'BasicArrayPackage' is used only under 'arrays' feature.
pub MyPackage(module) :
ArithmeticPackage,
LogicPackage,
#[cfg(feature = "arrays")]
BasicArrayPackage
{
...
}
}
```
~~~
~~~admonish danger.small "Advanced: `Engine` setup with `|>`"
A second code block (in the syntax of a [closure]) following a right-triangle symbol (`|>`)
is run whenever the [package] is being registered.
It allows performing setup tasks directly on that [`Engine`], e.g. registering [custom types],
[custom operators] and/or [custom syntax].
```rust
def_package! {
pub MyPackage(module) {
:
:
} |> |engine| {
// Call methods on 'engine'
}
}
```
~~~
Create a Custom Package from a Plugin Module
--------------------------------------------
```admonish question.side "Trivia"
This is exactly how Rhai's built-in [packages], such as `BasicMathPackage`, are actually implemented.
```
By far the easiest way to create a custom [package] is to call `plugin::combine_with_exported_module!`
from within `def_package!` which simply merges in all the functions defined within a [plugin module].
Due to specific requirements of a [package], `plugin::combine_with_exported_module!`
_flattens_ all sub-modules (i.e. all functions and [type iterators] defined within sub-modules
are pulled up to the top level instead) and so there will not be any sub-modules added to the [package].
Variables in the [plugin module] are ignored.
```rust
// Import necessary types and traits.
use rhai::def_package;
use rhai::packages::{ArithmeticPackage, BasicArrayPackage, BasicMapPackage, LogicPackage};
use rhai::plugin::*;
// Define plugin module.
#[export_module]
mod my_plugin_module {
// Custom type.
pub type ABC = TestStruct;
// Public constant.
pub const MY_NUMBER: i64 = 42;
// Public function.
pub fn greet(name: &str) -> String {
format!("hello, {}!", name)
}
// Non-public functions are by default not exported.
fn get_private_num() -> i64 {
42
}
// Public function.
pub fn get_num() -> i64 {
get_private_num()
}
// Custom operator.
#[rhai_fn(name = "@")]
pub fn square_add(x: i64, y: i64) -> i64 {
x * x + y * y
}
// A sub-module. If using 'combine_with_exported_module!', however,
// it will be flattened and all functions registered at the top level.
//
// Because of this flattening, sub-modules are very convenient for
// putting feature gates onto large groups of functions.
#[cfg(feature = "sub-num-feature")]
pub mod my_sub_module {
// Only available under 'sub-num-feature'.
pub fn get_sub_num() -> i64 {
0
}
}
}
def_package! {
/// My own personal super package
// Aggregate other base packages (if any) simply by listing them after a colon.
pub MyPackage(module) : ArithmeticPackage, LogicPackage, BasicArrayPackage, BasicMapPackage
{
// Merge all registered functions and constants from the plugin module
// into the custom package.
//
// The sub-module 'my_sub_module' is flattened and its functions
// registered at the top level.
//
// The text string name in the second parameter can be anything
// and is reserved for future use; it is recommended to be an
// ID string that uniquely identifies the plugin module.
//
// The constant variable, 'MY_NUMBER', is ignored.
//
// This call ends up registering three functions at the top level of
// the package:
// 1) 'greet'
// 2) 'get_num'
// 3) 'get_sub_num' (flattened from 'my_sub_module')
//
combine_with_exported_module!(module, "my-mod", my_plugin_module));
} |> |engine| {
// This optional block is used to set up an 'Engine' during registration.
// Define a custom operator '@' with precedence of 160
// (i.e. between +|- and *|/).
engine.register_custom_operator("@", 160).unwrap();
}
}
```