From ae953315fe0835616459c3cf107a0fc10807973b Mon Sep 17 00:00:00 2001 From: Stephen Chung Date: Fri, 4 Sep 2020 15:42:31 +0800 Subject: [PATCH] Refine plugins doc. --- RELEASES.md | 4 ---- doc/src/SUMMARY.md | 4 ++-- doc/src/plugins/function.md | 14 +++++------ doc/src/plugins/module.md | 46 ++++++++++++++++++++++++------------- tests/plugins.rs | 2 ++ 5 files changed, 41 insertions(+), 29 deletions(-) diff --git a/RELEASES.md b/RELEASES.md index da91ff68..69044fc5 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -20,10 +20,6 @@ Bug fixes * Imported modules now work inside closures. * Closures that capture now work under `no_object`. - -Version 0.18.2 -============== - New features ------------ diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md index c6457b52..db96844b 100644 --- a/doc/src/SUMMARY.md +++ b/doc/src/SUMMARY.md @@ -46,8 +46,8 @@ The Rhai Scripting Language 2. [Load a Plugin Module as a Package](rust/packages/plugin.md) 3. [Manually Create a Custom Package](rust/packages/create.md) 10. [Plugins](plugins/index.md) - 1. [Create a Plugin Module](plugins/module.md) - 2. [Create a Plugin Function](plugins/function.md) + 1. [Export a Rust Module](plugins/module.md) + 2. [Export a Rust Function](plugins/function.md) 5. [Rhai Language Reference](language/index.md) 1. [Comments](language/comments.md) 2. [Values and Types](language/values-and-types.md) diff --git a/doc/src/plugins/function.md b/doc/src/plugins/function.md index 888d7220..391d97fb 100644 --- a/doc/src/plugins/function.md +++ b/doc/src/plugins/function.md @@ -1,5 +1,5 @@ -Exporting a Rust Function to Rhai -================================= +Export a Rust Function to Rhai +============================= {{#include ../links.md}} @@ -11,11 +11,11 @@ individual functions instead of a full-blown [plugin module]. Macros ------ -| Macro | Apply to | Behavior | -| ------------------------ | ------------------------------------------------------------- | --------------------------------------------------------- | -| `#[export_fn]` | Rust function defined in a Rust module | Export the function | -| `register_exported_fn!` | [`Engine`] instance, register name string, use path to function | Register function into an [`Engine`] under specific name | -| `set_exported_fn!` | [`Module`] instance, register name string, use path to function | Register function into an [`Module`] under specific name | +| Macro | Apply to | Behavior | +| ----------------------- | --------------------------------------------------------------- | -------------------------------------------------------- | +| `#[export_fn]` | Rust function defined in a Rust module | Export the function | +| `register_exported_fn!` | [`Engine`] instance, register name string, use path to function | Register function into an [`Engine`] under specific name | +| `set_exported_fn!` | [`Module`] instance, register name string, use path to function | Register function into an [`Module`] under specific name | `#[export_fn]` and `register_exported_fn!` diff --git a/doc/src/plugins/module.md b/doc/src/plugins/module.md index b26eff3d..9f510998 100644 --- a/doc/src/plugins/module.md +++ b/doc/src/plugins/module.md @@ -1,10 +1,10 @@ -Exporting a Rust Module to Rhai -=============================== +Export a Rust Module to Rhai +============================ {{#include ../links.md}} -When applied to a Rust module, the `#[export_module]` attribute will generate the necessary +When applied to a Rust module, the `#[export_module]` attribute generates the necessary code and metadata to allow Rhai access to its public (i.e. marked `pub`) functions. This code is exactly what would need to be written by hand to achieve the same goal, and is custom fit to each exported item. @@ -14,7 +14,7 @@ registered as a [custom package]. This is done by using the `exported_module!` m Using`#[export_module]` and `exported_module!` ----------------------------------------- +--------------------------------------------- Apply `#[export_module]` onto a Rust module to convert all `pub` functions into Rhai plugin functions. @@ -183,19 +183,33 @@ mod my_module { ``` +`#[export_module]` Parameters +---------------------------- + +Parameters can be applied to the `#[export_module]` attribute to override its default behavior. + +| Parameter | Behavior | +| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| _None_ | Export only public (i.e. `pub`) functions | +| `export_all` | Export all functions (including private, non-`pub` functions); use `#[rhai_fn(skip)]` on individual functions to avoid export | +| `export_prefix = "..."` | Export functions (including private, non-`pub` functions) with names starting with a specific prefix | + + Inner Attributes ------- +---------------- -As shown above, inner attributes can be applied to inner items to tweak the export process. `#[rhai_fn]` is applied to functions, and `#[rhai_mod]` is applied to inner modules. +Inner attributes can be applied to the inner items of a module to tweak the export process. -Here is the complete list of parameters currently supported: +`#[rhai_fn]` is applied to functions, while `#[rhai_mod]` is applied to sub-modules. -| Attribute | Use with | Apply to | Behavior | -| ----------------------------- | ------------ | -------------------------------------------------------------------- | ----------------------------------------------- | -| `skip` | `#[rhai_fn]` `#[rhai_mod]` | Function or submodule| Do not export this item | -| `name = "..."` | `#[rhai_fn]` `#[rhai_mod]` | `pub` item | Register under the specified name | -| `get = "..."` | `#[rhai_fn]` | function with `&mut` first parameter | Register a getter for the named property | -| `set = "..."` | `#[rhai_fn]` | function with `&mut` first parameter | Register a setter for the named property | -| `index_get` | `#[rhai_fn]` | function with `&mut` first parameter | Register an index getter | -| `index_set` | `#[rhai_fn]` | function with `&mut` first parameter | Register an index setter | -| `return_raw` | `#[rhai_fn]` | function returning `Result>` | Mark this as a [fallible function] | +Parameters should be set on inner attributes to specify the desired behavior. + +| Attribute Parameter | Use with | Apply to | Behavior | +| ------------------- | --------------------------- | -------------------------------------------------------- | ----------------------------------------------------- | +| `skip` | `#[rhai_fn]`, `#[rhai_mod]` | Function or sub-module | Do not export this function/sub-module | +| `name = "..."` | `#[rhai_fn]`, `#[rhai_mod]` | Function or sub-module | Register function/sub-module under the specified name | +| `get = "..."` | `#[rhai_fn]` | Function with `&mut` first parameter | Register a getter for the named property | +| `set = "..."` | `#[rhai_fn]` | Function with `&mut` first parameter | Register a setter for the named property | +| `index_get` | `#[rhai_fn]` | Function with `&mut` first parameter | Register an index getter | +| `index_set` | `#[rhai_fn]` | Function with `&mut` first parameter | Register an index setter | +| `return_raw` | `#[rhai_fn]` | Function returning `Result>` | Mark this as a [fallible function] | diff --git a/tests/plugins.rs b/tests/plugins.rs index dd56ae61..5310c79e 100644 --- a/tests/plugins.rs +++ b/tests/plugins.rs @@ -12,6 +12,8 @@ mod test { #[cfg(not(feature = "no_object"))] pub mod feature { + use rhai::{Array, Dynamic, EvalAltResult}; + #[rhai_fn(get = "foo", return_raw)] #[inline(always)] pub fn foo(array: &mut Array) -> Result> {