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

Refine docs.

Browse Source
This commit is contained in:
Stephen Chung 2020-09-20 10:50:58 +08:00
parent 39546b7053
commit 3341f40fd2
7 changed files with 79 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
RELEASES.md
View File

@ -9,6 +9,8 @@ Bug fixes
* `if` statement with an empty `true` block would not evaluate the `false` block. This is now fixed.
* Fixes a bug in `Module::set_fn_4_mut`.
* Module API's now properly handle `&str` and `String` parameters.
* Indexers are available under `no_object`.
New features
------------

15
doc/src/language/arrays.md
View File

@ -45,6 +45,15 @@ The following methods (mostly defined in the [`BasicArrayPackage`][packages] but
| `truncate` | target length | cuts off the array at exactly a specified length (discarding all subsequent elements) |
Use Custom Types With Arrays
---------------------------
To use a [custom type] with arrays, a number of array functions need to be manually implemented,
in particular `push`, `pad` and the `==` operator (in order to support the `in` operator).
See the section on [custom types] for more details.
Examples
--------
@ -123,9 +132,3 @@ y.clear(); // empty the array
y.len == 0;
```
`push` and `pad` are only defined for standard built-in types. For custom types, type-specific versions must be registered:
```rust
engine.register_fn("push", |list: &mut Array, item: MyType| list.push(Box::new(item)) );
```

40
doc/src/rust/custom.md
View File

@ -38,12 +38,14 @@ let result = engine.eval::<TestStruct>("let x = new_ts(); x.update(); x")?;
println!("result: {}", result.field); // prints 42
```
Register a Custom Type
---------------------
A custom type must implement `Clone` as this allows the [`Engine`] to pass by value.
Notice that the custom type needs to be _registered_ using `Engine::register_type`.
Notice that the custom type needs to be _registered_ using `Engine::register_type`
or `Engine::register_type_with_name`.
```rust
#[derive(Clone)]
@ -66,7 +68,8 @@ let mut engine = Engine::new();
engine.register_type::<TestStruct>();
```
Methods on The Custom Type
Methods on the Custom Type
-------------------------
To use native custom types, methods and functions in Rhai scripts, simply register them
@ -85,6 +88,7 @@ so that invoking methods can update the types. All other parameters in Rhai are
**IMPORTANT: Rhai does NOT support normal references (i.e. `&T`) as parameters.**
Use the Custom Type in Scripts
-----------------------------
@ -97,6 +101,7 @@ let result = engine.eval::<TestStruct>("let x = new_ts(); x.update(); x")?;
println!("result: {}", result.field); // prints 42
```
Method-Call Style vs. Function-Call Style
----------------------------------------
@ -127,6 +132,7 @@ Under [`no_object`], however, the _method_ style of function calls
let result = engine.eval::<()>("let x = [1, 2, 3]; x.clear()")?;
```
`type_of()` a Custom Type
-------------------------
@ -150,3 +156,33 @@ engine
let x = new_ts();
x.type_of() == "Hello";
```
Use the Custom Type With Arrays
------------------------------
The `push` and `pad` functions for [arrays] are only defined for standard built-in types.
For custom types, type-specific versions must be registered:
```rust
engine
.register_fn("push", |list: &mut Array, item: TestStruct| {
list.push(Dynamic::from(item));
}).register_fn("pad", |list: &mut Array, len: i64, item: TestStruct| {
if len as usize > list.len() {
list.resize(len as usize, item);
}
});
```
In particular, in order to use the `in` operator with a custom type for an [array],
the `==` operator must be registered for that custom type:
```rust
// Assume 'TestStruct' implements `PartialEq`
engine.register_fn("==", |item1: &mut TestStruct, item2: TestStruct| item1 == item2);
// Then this works in Rhai:
let item = new_ts(); // construct a new 'TestStruct'
item in array; // 'in' operator uses '=='
```

8
doc/src/rust/disable-custom.md
View File

@ -3,8 +3,8 @@ Disable Custom Types
{{#include ../links.md}}
The custom types API `register_type`, `register_type_with_name`, `register_get`, `register_set`, `register_get_set`,
`register_indexer_get`, `register_indexer_set` and `register_indexer_get_set` are not available under [`no_object`].
The custom types API `register_type`, `register_type_with_name`, `register_get`, `register_get_result`,
`register_set`, `register_set_result` and `register_get_set` are not available under [`no_object`].
The indexers API `register_indexer_get`, `register_indexer_set` and `register_indexer_get_set` are also
not available under [`no_index`].
The indexers API `register_indexer_get`, `register_indexer_get_result`, `register_indexer_set`,
`register_indexer_set_result`, and `register_indexer_get_set` are also not available under [`no_index`].

14
doc/src/rust/getters-setters.md
View File

@ -7,6 +7,20 @@ A custom type can also expose members by registering `get` and/or `set` function
Getters and setters each take a `&mut` reference to the first parameter.
Getters and setters are disabled when the [`no_object`] feature is used.
| `Engine` API | Description | Return Value of Function |
| --------------------- | ------------------------------------------------- | :-----------------------------------: |
| `register_get` | Register a getter | _Any_ |
| `register_set` | Register a setter | _Any_ |
| `register_get_set` | Short-hand to register both a getter and a setter | _None_ |
| `register_get_result` | Register a getter | `Result<Dynamic, Box<EvalAltResult>>` |
| `register_set_result` | Register a setter | `Result<Dynamic, Box<EvalAltResult>>` |
Examples
--------
```rust
#[derive(Clone)]
struct TestStruct {

12
doc/src/rust/indexers.md
View File

@ -16,6 +16,18 @@ Indexers are disabled when the [`no_index`] feature is used.
For efficiency reasons, indexers **cannot** be used to overload (i.e. override) built-in indexing operations for
[arrays] and [object maps].
| `Engine` API | Description | Return Value of Function |
| ----------------------------- | -------------------------------------------------------- | :-----------------------------------: |
| `register_indexer_get` | Register an index getter | _Any_ |
| `register_indexer_set` | Register an index setter | _Any_ |
| `register_indexer_get_set` | Short-hand to register both an index getter and a setter | _None_ |
| `register_indexer_get_result` | Register an index getter | `Result<Dynamic, Box<EvalAltResult>>` |
| `register_indexer_set_result` | Register an index setter | `Result<Dynamic, Box<EvalAltResult>>` |
Examples
--------
```rust
#[derive(Clone)]
struct TestStruct {

5
src/api.rs
View File

@ -463,7 +463,6 @@ impl Engine {
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_object"))]
#[cfg(not(feature = "no_index"))]
pub fn register_indexer_get<T, X, U>(
&mut self,
@ -516,7 +515,6 @@ impl Engine {
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_object"))]
#[cfg(not(feature = "no_index"))]
pub fn register_indexer_get_result<T, X>(
&mut self,
@ -564,7 +562,6 @@ impl Engine {
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_object"))]
#[cfg(not(feature = "no_index"))]
pub fn register_indexer_set<T, X, U>(
&mut self,
@ -617,7 +614,6 @@ impl Engine {
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_object"))]
#[cfg(not(feature = "no_index"))]
pub fn register_indexer_set_result<T, X, U>(
&mut self,
@ -664,7 +660,6 @@ impl Engine {
/// # Ok(())
/// # }
/// ```
#[cfg(not(feature = "no_object"))]
#[cfg(not(feature = "no_index"))]
pub fn register_indexer_get_set<T, X, U>(
&mut self,