164 lines
4.7 KiB
Markdown
164 lines
4.7 KiB
Markdown
Scriptable Event Handler with State<br/>Map Style
|
|
=================================================
|
|
|
|
{{#include ../links.md}}
|
|
|
|
|
|
```admonish example
|
|
|
|
A runnable example of this implementation is included.
|
|
|
|
See the [_Examples_]({{rootUrl}}/start/examples/rust.md) section for details.
|
|
```
|
|
|
|
|
|
I Hate `this`! How Can I Get Rid of It?
|
|
----------------------------------------
|
|
|
|
You're using Rust and you don't want people to think you're writing lowly JavaScript?
|
|
|
|
Taking inspiration from the [_JS Style_](events-2.md), a slight modification of the
|
|
[_Main Style_](events-1.md) is to store all states inside an [object map] inside a custom [`Scope`].
|
|
|
|
Nevertheless, instead of writing `this.variable_name` everywhere to access a state variable
|
|
(in the [_JS Style_](events-2.md)), you'd write `state.variable_name` instead.
|
|
|
|
It is up to you to decide whether this is an improvement!
|
|
|
|
|
|
Handler Initialization
|
|
----------------------
|
|
|
|
```admonish note.side "No shadowing 'state'"
|
|
|
|
Notice that a [variable definition filter] is used to prevent [shadowing] of the states [object map].
|
|
```
|
|
|
|
Implementation wise, this style follows closely the [_Main Style_](events-1.md), but a single
|
|
[object map] is added to the custom [`Scope`] which holds all state values.
|
|
|
|
Global [constants] can still be added to the custom [`Scope`] as normal and used through the script.
|
|
|
|
Calls to the `init` [function] no longer need to avoid rewinding the [`Scope`] because state
|
|
[variables] are added as properties under the states [object map].
|
|
|
|
```rust
|
|
impl Handler {
|
|
// Create a new 'Handler'.
|
|
pub fn new(path: impl Into<PathBuf>) -> Self {
|
|
let mut engine = Engine::new();
|
|
|
|
// Forbid shadowing of 'state' variable
|
|
engine.on_def_var(|_, info, _| Ok(info.name != "state"));
|
|
|
|
:
|
|
// Code omitted
|
|
:
|
|
|
|
// Use an object map to hold state
|
|
let mut states = Map::new();
|
|
|
|
// Default states can be added
|
|
states.insert("bool_state".into(), Dynamic::FALSE);
|
|
|
|
// Add the main states-holding object map and call it 'state'
|
|
scope.push("state", states);
|
|
|
|
// Just a simple 'call_fn' can do here because we're rewinding the 'Scope'
|
|
// In a real application you'd again be handling errors...
|
|
engine.call_fn(&mut scope, &ast, "init", ()).unwrap();
|
|
|
|
:
|
|
// Code omitted
|
|
:
|
|
|
|
Self { engine, scope, ast }
|
|
}
|
|
}
|
|
```
|
|
|
|
|
|
Handler Scripting Style
|
|
-----------------------
|
|
|
|
The stored state is kept in an [object map] in the custom [`Scope`].
|
|
|
|
In this example, that [object map] is named `state`, but it can be any name.
|
|
|
|
### User-defined functions in state
|
|
|
|
Because an [object map] is used to hold state values, it is even possible to add user-defined
|
|
[functions], leveraging the [OOP] support for [object maps].
|
|
|
|
However, within these user-defined [functions], the `this` pointer binds to the [object map].
|
|
Therefore, the variable-accessing syntax is different from the main body of the script.
|
|
|
|
```js
|
|
fn do_action() {
|
|
// Access state: `state.xxx`
|
|
state.number = 42;
|
|
|
|
// Add OOP functions - you still need to use `this`...
|
|
state.log = |x| print(`State = ${this.value}, data = ${x}`);
|
|
}
|
|
```
|
|
|
|
### Sample script
|
|
|
|
```js
|
|
/// Initialize user-provided state.
|
|
/// State is stored inside an object map bound to 'state'.
|
|
fn init() {
|
|
// Add 'bool_state' as new state variable if one does not exist
|
|
if "bool_state" !in state {
|
|
state.bool_state = false;
|
|
}
|
|
// Add 'obj_state' as new state variable (overwrites any existing)
|
|
state.obj_state = new_state(0);
|
|
|
|
// Can also add OOP-style functions!
|
|
state.log = |x| print(`State = ${this.obj_state.value}, data = ${x}`);
|
|
}
|
|
|
|
/// 'start' event handler
|
|
fn start(data) {
|
|
// Can detect system-provided default states!
|
|
// Access state variables in 'state'
|
|
if state.bool_state {
|
|
throw "Already started!";
|
|
}
|
|
|
|
// New values can be added to the state
|
|
state.start_mode = data;
|
|
|
|
if state.obj_state.func1() || state.obj_state.func2() {
|
|
throw "Conditions not yet ready to start!";
|
|
}
|
|
state.bool_state = true;
|
|
state.obj_state.value = data;
|
|
|
|
// Constant 'MY_CONSTANT' in custom scope is also visible!
|
|
print(`MY_CONSTANT = ${MY_CONSTANT}`);
|
|
}
|
|
|
|
/// 'end' event handler
|
|
fn end(data) {
|
|
if !state.bool_state || "start_mode" !in state {
|
|
throw "Not yet started!";
|
|
}
|
|
if !state.obj_state.func1() && !state.obj_state.func2() {
|
|
throw "Conditions not yet ready to end!";
|
|
}
|
|
state.bool_state = false;
|
|
state.obj_state.value = data;
|
|
}
|
|
|
|
/// 'update' event handler
|
|
fn update(data) {
|
|
state.obj_state.value += process(data);
|
|
|
|
// Call user-defined function OOP-style!
|
|
state.log(data);
|
|
}
|
|
```
|