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

Add events handler pattern.

Browse Source
This commit is contained in:
Stephen Chung 2020-10-04 23:05:33 +08:00
parent a962debf0d
commit b91a073596
3 changed files with 206 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
doc/src/SUMMARY.md
View File

@ -52,18 +52,19 @@ The Rhai Scripting Language
1. [Comments](language/comments.md)
2. [Values and Types](language/values-and-types.md)
1. [Dynamic Values](language/dynamic.md)
2. [type_of()](language/type-of.md)
3. [Numbers](language/numbers.md)
2. [Serialization/Deserialization with `serde`](rust/serde.md)
3. [type_of()](language/type-of.md)
4. [Numbers](language/numbers.md)
1. [Operators](language/num-op.md)
2. [Functions](language/num-fn.md)
3. [Value Conversions](language/convert.md)
4. [Strings and Characters](language/strings-chars.md)
5. [Strings and Characters](language/strings-chars.md)
1. [Built-in Functions](language/string-fn.md)
5. [Arrays](language/arrays.md)
6. [Object Maps](language/object-maps.md)
6. [Arrays](language/arrays.md)
7. [Object Maps](language/object-maps.md)
1. [Parse from JSON](language/json.md)
2. [Special Support for OOP](language/object-maps-oop.md)
7. [Time-Stamps](language/timestamps.md)
8. [Time-Stamps](language/timestamps.md)
3. [Keywords](language/keywords.md)
4. [Statements](language/statements.md)
5. [Variables](language/variables.md)
@ -104,29 +105,29 @@ The Rhai Scripting Language
7. [Maximum Number of Modules](safety/max-modules.md)
8. [Maximum Call Stack Depth](safety/max-call-stack.md)
9. [Maximum Statement Depth](safety/max-stmt-depth.md)
7. [Advanced Topics](advanced.md)
1. [Advanced Patterns](patterns/index.md)
1. [Object-Oriented Programming (OOP)](patterns/oop.md)
2. [Loadable Configuration](patterns/config.md)
3. [Control Layer](patterns/control.md)
4. [Singleton Command](patterns/singleton.md)
5. [One Engine Instance Per Call](patterns/parallel.md)
2. [Capture Scope for Function Call](language/fn-capture.md)
3. [Serialization/Deserialization of `Dynamic` with `serde`](rust/serde.md)
4. [Script Optimization](engine/optimize/index.md)
7. [Usage Patterns](patterns/index.md)
1. [Object-Oriented Programming (OOP)](patterns/oop.md)
2. [Loadable Configuration](patterns/config.md)
3. [Control Layer](patterns/control.md)
4. [Singleton Command](patterns/singleton.md)
5. [One Engine Instance Per Call](patterns/parallel.md)
6. [Scriptable Event Handler with State](patterns/events.md)
8. [Advanced Topics](advanced.md)
1. [Capture Scope for Function Call](language/fn-capture.md)
2. [Script Optimization](engine/optimize/index.md)
1. [Optimization Levels](engine/optimize/optimize-levels.md)
2. [Re-Optimize an AST](engine/optimize/reoptimize.md)
3. [Eager Function Evaluation](engine/optimize/eager.md)
4. [Side-Effect Considerations](engine/optimize/side-effects.md)
5. [Volatility Considerations](engine/optimize/volatility.md)
6. [Subtle Semantic Changes](engine/optimize/semantics.md)
5. [Low-Level API](rust/register-raw.md)
6. [Use as DSL](engine/dsl.md)
3. [Low-Level API](rust/register-raw.md)
4. [Use as DSL](engine/dsl.md)
1. [Disable Keywords and/or Operators](engine/disable.md)
2. [Custom Operators](engine/custom-op.md)
3. [Extending with Custom Syntax](engine/custom-syntax.md)
7. [Multiple Instantiation](patterns/multiple.md)
8. [Appendix](appendix/index.md)
5. [Multiple Instantiation](patterns/multiple.md)
9. [Appendix](appendix/index.md)
1. [Keywords](appendix/keywords.md)
2. [Operators and Symbols](appendix/operators.md)
3. [Literals](appendix/literals.md)

182
doc/src/patterns/events.md Normal file
View File

@ -0,0 +1,182 @@
Scriptable Event Handler with State
==================================
{{#include ../links.md}}
Usage Scenario
--------------
* A system sends _events_ that must be handled.
* Flexibility in event handling must be provided, through user-side scripting.
* State must be kept between invocations of event handlers.
* Default implementations of event handlers can be provided.
Key Concepts
------------
* An _event handler_ object is declared that holds the following items:
* [`Engine`] with registered functions serving as an API,
* [`AST`] of the user script,
* a [`Scope`] containing state.
* Upon an event, the appropriate event handler function in the script is called via [`Engine::call_fn`][`call_fn`].
* Optionally, trap the `EvalAltResult::ErrorFunctionNotFound` error to provide a default implementation.
Implementation
--------------
### Declare Handler Object
In most cases, it would be simpler to store an [`Engine`] instance together with the handler object
because it only requires registering all API functions only once.
In rare cases where handlers are created and destroyed in a tight loop, a new [`Engine`] instance
can be created for each event. See [_One Engine Instance Per Call_](parallel.md) for more details.
```rust
use rhai::{Engine, Scope, AST, EvalAltResult};
// Event handler
struct Handler {
// Scripting engine
pub engine: Engine,
// Use a custom 'Scope' to keep stored state
pub scope: Scope<'static>,
// Program script
pub ast: AST
}
```
### Initialize Handler Object
Steps to initialize the event handler:
1. Register an API with the [`Engine`],
2. Create a custom [`Scope`] to serve as the stored state,
3. Add default state variables into the custom [`Scope`],
4. Get the handler script and [compile][`AST`] it,
5. Store the compiled [`AST`] for future evaluations,
6. Run the [`AST`] to initialize event handler state variables.
```rust
impl Handler {
pub new(path: impl Into<PathBuf>) -> Self {
let mut engine = Engine::new();
// Register API functions here
engine
.register_fn("func1", func1)
.register_fn("func2", func2)
.register_fn("func3", func3)
.register_type_with_name::<SomeType>("SomeType")
.register_get_set("value",
|obj: &mut SomeType| obj.data,
|obj: &mut SomeType, value: i64| obj.data = value
);
// Create a custom 'Scope' to hold state
let mut scope = Scope::new();
// Add initialized state into the custom 'Scope'
scope.push("state1", false);
scope.push("state2", SomeType::new(42));
// Compile the handler script.
// In a real application you'd be handling errors...
let ast = engine.compile_file(path).unwrap();
// Evaluate the script to initialize it and other state variables.
// In a real application you'd again be handling errors...
engine.consume_ast_with_scope(&mut scope, &ast).unwrap();
// The event handler is essentially these three items:
Handler { engine, scope, ast }
}
}
```
### Hook up events
There is usually an interface or trait that gets called when an event comes from the system.
Mapping an event from the system into a scripted handler is straight-forward:
```rust
impl Handler {
// Say there are three events: 'start', 'end', 'update'.
// In a real application you'd be handling errors...
pub fn on_event(&mut self, event_name: &str, event_data: i64) {
match event_name {
// The 'start' event maps to function 'start'.
// In a real application you'd be handling errors...
"start" =>
self.engine
.call_fn(&mut self.scope, &self.ast, "start", (event_data,)).unwrap(),
// The 'end' event maps to function 'end'.
// In a real application you'd be handling errors...
"end" =>
self.engine
.call_fn(&mut self.scope, &self.ast, "end", (event_data,)).unwrap(),
// The 'update' event maps to function 'update'.
// This event provides a default implementation when the scripted function
// is not found.
"update" =>
self.engine
.call_fn(&mut self.scope, &self.ast, "update", (event_data,))
.or_else(|err| match *err {
EvalAltResult::ErrorFunctionNotFound(fn_name, _) if fn_name == "update" => {
// Default implementation of 'update' event handler
self.scope.set_value("state2", SomeType::new(42));
// Turn function-not-found into a success
Ok(().into())
}
_ => Err(err.into())
})
.unwrap()
}
}
}
```
### Sample Handler Script
Because the stored state is kept in a custom [`Scope`], it is possible for all functions defined
in the handler script to access and modify these state variables.
The API registered with the [`Engine`] can be also used throughout the script.
```rust
fn start(data) {
if state1 {
throw "Already started!";
}
if func1(state2) || func2() {
throw "Conditions not yet ready to start!";
}
state1 = true;
state2.value = 0;
}
fn end(data) {
if !state1 {
throw "Not yet started!";
}
if func1(state2) || func2() {
throw "Conditions not yet ready to start!";
}
state1 = false;
}
fn update(data) {
state2.value += func3(data);
}
```

6
doc/src/patterns/index.md
View File

@ -1,7 +1,7 @@
Advanced Patterns
=================
Usage Patterns
==============
{{#include ../links.md}}
Leverage the full power and flexibility of Rhai in advanced scenarios.
Leverage the full power and flexibility of Rhai in different scenarios.