140 lines
3.9 KiB
Markdown
140 lines
3.9 KiB
Markdown
Domain-Specific Tools
|
|
=====================
|
|
|
|
{{#include ../links.md}}
|
|
|
|
[bin tool]: {{rootUrl}}/start/bin.md
|
|
[bin tools]: {{rootUrl}}/start/bin.md
|
|
|
|
```admonish info "Usage scenario"
|
|
|
|
* A system has a _domain-specific_ API, requiring [custom types] and/or
|
|
Rust [functions]({{rootUrl}}/rust/functions.md) to be registered and exposed to scripting.
|
|
|
|
* The system's behavior is controlled by Rhai script [functions], such as in the
|
|
[_Scriptable Event Handler with State_](events.md), [_Control Layer_](control.md) or
|
|
[_Singleton Command Object_](singleton.md) patterns.
|
|
|
|
* It is desirable to be able to _interactively_ test the system with different scripts,
|
|
and/or [debug][debugger] them.
|
|
```
|
|
|
|
```admonish abstract "Key concepts"
|
|
|
|
* Leverage the pre-packaged [bin tools] – it is easy because each of them is
|
|
one single source file.
|
|
|
|
* Modify the [`Engine`] creation code to include domain-specific registrations.
|
|
```
|
|
|
|
|
|
Implementation
|
|
--------------
|
|
|
|
### Copy necessary tool source files
|
|
|
|
Each [bin tool] is a single source file.
|
|
|
|
Download the necessary one(s) into the project's `bin` or `example` subdirectory.
|
|
|
|
| Select this source file | To make |
|
|
| --------------------------------------------------- | ------------------------------------- |
|
|
| [`rhai-run.rs`]({{repoHome}}/src/bin/rhai-run.rs) | a simple script runner for the system |
|
|
| [`rhai-repl.rs`]({{repoHome}}/src/bin/rhai-repl.rs) | an interactive REPL for the system |
|
|
| [`rhai-dbg.rs`]({{repoHome}}/src/bin/rhai-dbg.rs) | a script debugger for the system |
|
|
|
|
#### Example
|
|
|
|
```sh
|
|
rhai-run.rs -> /path/to/my_project/examples/test.rs
|
|
rhai-repl.rs -> /path/to/my_project/examples/repl.rs
|
|
rhai-dbg.rs -> /path/to/my_project/examples/db.rs
|
|
```
|
|
|
|
### Leverage `Engine` configuration code in the project
|
|
|
|
Assume the project already contains configuration code for a customized [`Engine`].
|
|
|
|
```rust
|
|
use rhai::Engine;
|
|
use rhai::plugin::*;
|
|
|
|
// Domain-specific data types
|
|
use my_project::*;
|
|
|
|
#[export_module]
|
|
mod my_domain_api {
|
|
:
|
|
:
|
|
// plugin module
|
|
:
|
|
:
|
|
}
|
|
|
|
// This function creates a new Rhai scripting engine and
|
|
// configures it properly
|
|
fn create_scripting_engine(config: MySystemConfig) -> Engine {
|
|
let mut engine = Engine::new();
|
|
|
|
// Register domain-specific API into the Engine
|
|
engine.register_type_with_name::<MyObject>("MyObject")
|
|
.register_type_with_name::<MyOtherObject>("MyOtherObject")
|
|
.register_fn(...)
|
|
.register_fn(...)
|
|
.register_fn(...)
|
|
:
|
|
:
|
|
// register API functions
|
|
:
|
|
:
|
|
.register_get_set(...)
|
|
.register_index_get_set(...)
|
|
.register_fn(...);
|
|
|
|
// Plugin modules can be used to easily and quickly
|
|
// register an entire API
|
|
engine.register_global_module(exported_module!(my_domain_api).into());
|
|
|
|
// Configuration options in 'MySystemConfig' may be used
|
|
// to control the Engine's behavior
|
|
if config.strict_mode {
|
|
engine.set_strict_variables(true);
|
|
}
|
|
|
|
// Return the scripting engine
|
|
engine
|
|
}
|
|
```
|
|
|
|
### Modify `Engine` creation
|
|
|
|
Each [bin tool] contains a line that creates the main script [`Engine`].
|
|
|
|
Modify it to call the project's creation function.
|
|
|
|
```rust
|
|
// Initialize scripting engine
|
|
let mut engine = Engine::new();
|
|
|
|
// Modify to this:
|
|
let mut engine = create_scripting_engine(my_config);
|
|
```
|
|
|
|
### Make sure that Rhai has the appropriate feature(s)
|
|
|
|
In the project's `Cargo.toml`, specify the Rhai dependency with `bin-features`.
|
|
|
|
```toml
|
|
[dependencies]
|
|
rhai = { version = "{{version}}", features = ["bin-features"] }
|
|
```
|
|
|
|
### Rebuild
|
|
|
|
Rebuild the project, which should automatically build all the customized tools.
|
|
|
|
### Run tools
|
|
|
|
Each customized tool now has access to the entire domain-specific API.
|
|
Functions and [custom types] can be used in REPL, [debugging][debugger] etc.
|