From 3341f40fd2f2ed23cbc1efb677ecd87004534154 Mon Sep 17 00:00:00 2001 From: Stephen Chung Date: Sun, 20 Sep 2020 10:50:58 +0800 Subject: [PATCH] Refine docs. --- RELEASES.md | 2 ++ doc/src/language/arrays.md | 15 ++++++++----- doc/src/rust/custom.md | 40 +++++++++++++++++++++++++++++++-- doc/src/rust/disable-custom.md | 8 +++---- doc/src/rust/getters-setters.md | 14 ++++++++++++ doc/src/rust/indexers.md | 12 ++++++++++ src/api.rs | 5 ----- 7 files changed, 79 insertions(+), 17 deletions(-) diff --git a/RELEASES.md b/RELEASES.md index cb155381..9d8476fb 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -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 ------------ diff --git a/doc/src/language/arrays.md b/doc/src/language/arrays.md index 69f24103..5c0ce9e9 100644 --- a/doc/src/language/arrays.md +++ b/doc/src/language/arrays.md @@ -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)) ); -``` diff --git a/doc/src/rust/custom.md b/doc/src/rust/custom.md index b2325204..22bea701 100644 --- a/doc/src/rust/custom.md +++ b/doc/src/rust/custom.md @@ -38,12 +38,14 @@ let result = engine.eval::("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::(); ``` -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::("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 '==' +``` diff --git a/doc/src/rust/disable-custom.md b/doc/src/rust/disable-custom.md index a2c69c95..e5ad8a82 100644 --- a/doc/src/rust/disable-custom.md +++ b/doc/src/rust/disable-custom.md @@ -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`]. diff --git a/doc/src/rust/getters-setters.md b/doc/src/rust/getters-setters.md index 7597e8d5..6f6184ce 100644 --- a/doc/src/rust/getters-setters.md +++ b/doc/src/rust/getters-setters.md @@ -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>` | +| `register_set_result` | Register a setter | `Result>` | + + +Examples +-------- + ```rust #[derive(Clone)] struct TestStruct { diff --git a/doc/src/rust/indexers.md b/doc/src/rust/indexers.md index 94a6b5f1..69f73965 100644 --- a/doc/src/rust/indexers.md +++ b/doc/src/rust/indexers.md @@ -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>` | +| `register_indexer_set_result` | Register an index setter | `Result>` | + + +Examples +-------- + ```rust #[derive(Clone)] struct TestStruct { diff --git a/src/api.rs b/src/api.rs index 899b1ab6..85e0aab3 100644 --- a/src/api.rs +++ b/src/api.rs @@ -463,7 +463,6 @@ impl Engine { /// # Ok(()) /// # } /// ``` - #[cfg(not(feature = "no_object"))] #[cfg(not(feature = "no_index"))] pub fn register_indexer_get( &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( &mut self, @@ -564,7 +562,6 @@ impl Engine { /// # Ok(()) /// # } /// ``` - #[cfg(not(feature = "no_object"))] #[cfg(not(feature = "no_index"))] pub fn register_indexer_set( &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( &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( &mut self,