From b91a07359614bfc327349bd508a9f37240f2ccda Mon Sep 17 00:00:00 2001 From: Stephen Chung Date: Sun, 4 Oct 2020 23:05:33 +0800 Subject: [PATCH] Add events handler pattern. --- doc/src/SUMMARY.md | 41 +++++---- doc/src/patterns/events.md | 182 +++++++++++++++++++++++++++++++++++++ doc/src/patterns/index.md | 6 +- 3 files changed, 206 insertions(+), 23 deletions(-) create mode 100644 doc/src/patterns/events.md diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md index 5193b7bb..f8e279cc 100644 --- a/doc/src/SUMMARY.md +++ b/doc/src/SUMMARY.md @@ -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) diff --git a/doc/src/patterns/events.md b/doc/src/patterns/events.md new file mode 100644 index 00000000..9334e726 --- /dev/null +++ b/doc/src/patterns/events.md @@ -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) -> 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") + .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); +} +``` diff --git a/doc/src/patterns/index.md b/doc/src/patterns/index.md index b0e5d633..fb651ae8 100644 --- a/doc/src/patterns/index.md +++ b/doc/src/patterns/index.md @@ -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.