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

Refine plugins doc.

Browse Source
This commit is contained in:
Stephen Chung 2020-09-04 15:42:31 +08:00
parent 2737fe8aa3
commit ae953315fe
5 changed files with 41 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
RELEASES.md
View File

@ -20,10 +20,6 @@ Bug fixes
* Imported modules now work inside closures. * Imported modules now work inside closures.
* Closures that capture now work under `no_object`. * Closures that capture now work under `no_object`.
Version 0.18.2
==============
New features New features
------------ ------------

4
doc/src/SUMMARY.md
View File

@ -46,8 +46,8 @@ The Rhai Scripting Language
2. [Load a Plugin Module as a Package](rust/packages/plugin.md) 2. [Load a Plugin Module as a Package](rust/packages/plugin.md)
3. [Manually Create a Custom Package](rust/packages/create.md) 3. [Manually Create a Custom Package](rust/packages/create.md)
10. [Plugins](plugins/index.md) 10. [Plugins](plugins/index.md)
1. [Create a Plugin Module](plugins/module.md) 1. [Export a Rust Module](plugins/module.md)
2. [Create a Plugin Function](plugins/function.md) 2. [Export a Rust Function](plugins/function.md)
5. [Rhai Language Reference](language/index.md) 5. [Rhai Language Reference](language/index.md)
1. [Comments](language/comments.md) 1. [Comments](language/comments.md)
2. [Values and Types](language/values-and-types.md) 2. [Values and Types](language/values-and-types.md)

14
doc/src/plugins/function.md
View File

@ -1,5 +1,5 @@
Exporting a Rust Function to Rhai Export a Rust Function to Rhai
================================= =============================
{{#include ../links.md}} {{#include ../links.md}}
@ -11,11 +11,11 @@ individual functions instead of a full-blown [plugin module].
Macros Macros
------ ------
| Macro | Apply to | Behavior | | Macro | Apply to | Behavior |
| ------------------------ | ------------------------------------------------------------- | --------------------------------------------------------- | | ----------------------- | --------------------------------------------------------------- | -------------------------------------------------------- |
| `#[export_fn]` | Rust function defined in a Rust module | Export the function | | `#[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 | | `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 | | `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!` `#[export_fn]` and `register_exported_fn!`

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

@ -1,10 +1,10 @@
Exporting a Rust Module to Rhai Export a Rust Module to Rhai
=============================== ============================
{{#include ../links.md}} {{#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 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 is exactly what would need to be written by hand to achieve the same goal, and is custom fit
to each exported item. 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!` Using`#[export_module]` and `exported_module!`
---------------------------------------- ---------------------------------------------
Apply `#[export_module]` onto a Rust module to convert all `pub` functions into Rhai plugin Apply `#[export_module]` onto a Rust module to convert all `pub` functions into Rhai plugin
functions. 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 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 | Parameters should be set on inner attributes to specify the desired behavior.
| ----------------------------- | ------------ | -------------------------------------------------------------------- | ----------------------------------------------- |
| `skip` | `#[rhai_fn]` `#[rhai_mod]` | Function or submodule| Do not export this item | | Attribute Parameter | Use with | Apply to | Behavior |
| `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 | | `skip` | `#[rhai_fn]`, `#[rhai_mod]` | Function or sub-module | Do not export this function/sub-module |
| `set = "..."` | `#[rhai_fn]` | function with `&mut` first parameter | Register a setter for the named property | | `name = "..."` | `#[rhai_fn]`, `#[rhai_mod]` | Function or sub-module | Register function/sub-module under the specified name |
| `index_get` | `#[rhai_fn]` | function with `&mut` first parameter | Register an index getter | | `get = "..."` | `#[rhai_fn]` | Function with `&mut` first parameter | Register a getter for the named property |
| `index_set` | `#[rhai_fn]` | function with `&mut` first parameter | Register an index setter | | `set = "..."` | `#[rhai_fn]` | Function with `&mut` first parameter | Register a setter for the named property |
| `return_raw` | `#[rhai_fn]` | function returning `Result<Dynamic, Box<EvalAltResult>>` | Mark this as a [fallible function] | | `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<Dynamic, Box<EvalAltResult>>` | Mark this as a [fallible function] |

2
tests/plugins.rs
View File

@ -12,6 +12,8 @@ mod test {
#[cfg(not(feature = "no_object"))] #[cfg(not(feature = "no_object"))]
pub mod feature { pub mod feature {
use rhai::{Array, Dynamic, EvalAltResult};
#[rhai_fn(get = "foo", return_raw)] #[rhai_fn(get = "foo", return_raw)]
#[inline(always)] #[inline(always)]
pub fn foo(array: &mut Array) -> Result<Dynamic, Box<EvalAltResult>> { pub fn foo(array: &mut Array) -> Result<Dynamic, Box<EvalAltResult>> {