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

Revise docs for 0.19.0.

Browse Source
This commit is contained in:
Stephen Chung
2020-09-30 23:02:01 +08:00
parent a04ed02b54
commit cbc3d8764a
30 changed files with 291 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -3,8 +3,16 @@ Disable Custom Types
{{#include ../links.md}}
`no_object` Feature
-------------------
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`].
`no_index` Feature
------------------
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`].

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

@@ -11,7 +11,7 @@ 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_get` | register a getter | _any_ `T: Clone` |
| `register_set` | register a setter | _none_ |
| `register_get_set` | short-hand to register both a getter and a setter | _none_ |
| `register_get_result` | register a getter | `Result<Dynamic, Box<EvalAltResult>>` |

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

@@ -15,7 +15,7 @@ Indexers are disabled when the [`no_index`] feature is used.
| `Engine` API | Description | Return Value of Function |
| ----------------------------- | -------------------------------------------------------- | :-----------------------------------: |
| `register_indexer_get` | register an index getter | _any_ |
| `register_indexer_get` | register an index getter | _any_ `T: Clone` |
| `register_indexer_set` | register an index setter | _none_ |
| `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>>` |

13
doc/src/rust/operators.md
View File

@@ -6,16 +6,23 @@ Operator Overloading
In Rhai, a lot of functionalities are actually implemented as functions, including basic operations
such as arithmetic calculations.
For example, in the expression "`a + b`", the `+` operator is _not_ built in, but calls a function named "`+`" instead!
For example, in the expression "`a + b`", the `+` operator calls a function named "`+`"!
```rust
let x = a + b;
let x = +(a, b); // <- the above is equivalent to this function call
```
Similarly, comparison operators including `==`, `!=` etc. are all implemented as functions,
with the stark exception of `&&` and `||`. Because they [_short-circuit_]({{rootUrl}}/language/logic.md#boolean-operators),
`&&` and `||` are handled specially and _not_ via a function; as a result, overriding them has no effect at all.
with the stark exception of `&&` and `||`.
`&&` and `||` Cannot Be Overloaded
---------------------------------
Because they [_short-circuit_]({{rootUrl}}/language/logic.md#boolean-operators), `&&` and `||` are
handled specially and _not_ via a function; as a result, overriding them has no effect at all.
Overload Operator via Rust Function

6
doc/src/rust/packages/create.md
View File

@@ -60,7 +60,7 @@ def_package!(rhai:MyPackage:"My own personal super package", module, {
Create a Custom Package from a Plugin Module
-------------------------------------------
By far the easiest way to create a custom module is to call `rhai::plugins::combine_with_exported_module!`
By far the easiest way to create a custom module is to call `rhai::plugin::combine_with_exported_module!`
from within `rhai::def_package!` which simply merges in all the functions defined within a [plugin module].
In fact, this exactly is how Rhai's built-in packages, such as `BasicMathPackage`, are implemented.
@@ -113,8 +113,8 @@ def_package!(rhai:MyPackage:"My own personal super package", module, {
//
// The sub-module 'my_sub_module' is flattened and its functions registered at the top level.
//
// The text string name in the middle parameter can be anything and is reserved for future use;
// it is recommended to be an ID string that uniquely identifies the module.
// The text string name in the second parameter can be anything and is reserved for future use;
// it is recommended to be an ID string that uniquely identifies the plugin module.
//
// The constant variable, 'MY_NUMBER', is ignored.
//

3
doc/src/rust/packages/plugin.md
View File

@@ -3,7 +3,8 @@ Load a Plugin Module as a Package
{{#include ../../links.md}}
[Plugin modules] can be loaded as a package just like a normal [module].
[Plugin modules] can be loaded as a package just like a normal [module]
via the `exported_module!` macro.
```rust
use rhai::Engine;

18
doc/src/rust/register-raw.md
View File

@@ -35,13 +35,12 @@ engine.register_raw_fn(
// Therefore, get a '&mut' reference to the first argument _last_.
// Alternatively, use `args.split_first_mut()` etc. to split the slice first.
let y: i64 = *args[1].read_lock::<i64>() // get a reference to the second argument
.unwrap(); // then copying it because it is a primary type
let y = *args[1].read_lock::<i64>().unwrap(); // get a reference to the second argument
// then copy it because it is a primary type
let y: i64 = std::mem::take(args[1]).cast::<i64>(); // alternatively, directly 'consume' it
let y = std::mem::take(args[1]).cast::<i64>(); // alternatively, directly 'consume' it
let x: &mut i64 = args[0].write_lock::<i64>() // get a '&mut' reference to the
.unwrap(); // first argument
let x = args[0].write_lock::<i64>().unwrap(); // get a '&mut' reference to the first argument
*x += y; // perform the action
@@ -51,7 +50,7 @@ engine.register_raw_fn(
// The above is the same as (in fact, internally they are equivalent):
engine.register_fn("increment_by", |x: &mut i64, y: i64| x += y);
engine.register_fn("increment_by", |x: &mut i64, y: i64| *x += y);
```
@@ -153,7 +152,8 @@ is a _shared value_ created by [capturing][automatic currying] variables from [c
Shared values are implemented as `Rc<RefCell<Dynamic>>` (`Arc<RwLock<Dynamic>>` under [`sync`]).
If the value is _not_ a shared value, or if running under [`no_closure`] where there is
no [capturing][automatic currying], this API de-sugars to a simple `downcast_ref` and `downcast_mut`.
no [capturing][automatic currying], this API de-sugars to a simple `Dynamic::downcast_ref` and
`Dynamic::downcast_mut`.
If the value is a shared value, then it is first locked and the returned lock guard
then allows access to the underlying value in the specified type.
@@ -171,9 +171,9 @@ to partition the slice:
let (first, rest) = args.split_first_mut().unwrap();
// Mutable reference to the first parameter
let this_ptr: &mut A = &mut *first.write_lock::<A>().unwrap();
let this_ptr = &mut *first.write_lock::<A>().unwrap();
// Immutable reference to the second value parameter
// This can be mutable but there is no point because the parameter is passed by value
let value_ref: &B = &*rest[0].read_lock::<B>().unwrap();
let value_ref = &*rest[0].read_lock::<B>().unwrap();
```

13
doc/src/rust/traits.md
View File

@@ -5,9 +5,10 @@ Traits
A number of traits, under the `rhai::` module namespace, provide additional functionalities.
| Trait | Description | Methods |
| ------------------ | ---------------------------------------------------------------------------------------- | --------------------------------------- |
| `RegisterFn` | trait for registering functions | `register_fn` |
| `RegisterResultFn` | trait for registering fallible functions returning `Result<Dynamic, Box<EvalAltResult>>` | `register_result_fn` |
| `Func` | trait for creating Rust closures from script | `create_from_ast`, `create_from_script` |
| `ModuleResolver` | trait implemented by module resolution services | `resolve` |
| Trait | Description | Methods |
| ------------------------ | ------------------------------------------------------------------ | --------------------------------------------------------------------- |
| `RegisterFn` | trait for registering functions | `register_fn` |
| `RegisterResultFn` | trait for registering [fallible functions] | `register_result_fn` |
| `Func` | trait for creating Rust closures from script | `create_from_ast`, `create_from_script` |
| `ModuleResolver` | trait implemented by [module resolution][module resolver] services | `resolve` |
| `plugin::PluginFunction` | trait implemented by [plugin] functions | `call`, `is_method_call`, `is_variadic`, `clone_boxed`, `input_types` |