Refine plugins doc.
This commit is contained in:
Stephen Chung
parent
2737fe8aa3
commit
ae953315fe
@ -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
|
||||
------------
|
||||
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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!`
|
||||
|
||||
@ -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<Dynamic, Box<EvalAltResult>>` | 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<Dynamic, Box<EvalAltResult>>` | Mark this as a [fallible function] |
|
||||
|
||||
@ -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<Dynamic, Box<EvalAltResult>> {
|
||||
|
||||
Loading…
Reference in New Issue
Block a user