Rhai

https://rhai.rs/book/
Admin
Rhai is an embedded scripting language and evaluation engine for Rust, providing a safe and easy way...
Tokens:312,398
Snippets:3,255
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Configuration Script Example

Source: https://rhai.rs/book/print.html

Example Rhai script for configuring the system.

```rhai
┌────────────────┐
│ my_config.rhai │
└────────────────┘

config_set_id("hello");

config_add("foo");          // add to list
config_add("bar", true);    // add to map

if config_contains("hey") || config_is_set("hey") {
    config_add("baz", false);   // add to map
}
```

--------------------------------

### Install Rhai Tools with All Features

Source: https://rhai.rs/book/start/bin.html

Installs all Rhai binary tools with all available features enabled. This is the most comprehensive installation option.

```bash
cargo install --path . --bins  --features bin-features
```

--------------------------------

### Install Specific Rhai App with Features

Source: https://rhai.rs/book/start/bin.html

Installs a specific Rhai binary application, 'sample_app_to_run', with the 'bin-features' enabled. Use this for targeted installations.

```bash
cargo install --path . --bin sample_app_to_run  --features bin-features
```

--------------------------------

### Create and Run a Basic Rhai Script

Source: https://rhai.rs/book/engine/hello-world.html

Instantiate the Rhai engine and execute a simple script that prints output to the console. This is the most basic way to get started with Rhai.

```rust
use rhai::{Engine, EvalAltResult};

pub fn main() -> Result<(), Box<EvalAltResult>> {
    // Create an 'Engine'
    let engine = Engine::new();

    // Your first Rhai Script
    let script = "print(40 + 2);";

    // Run the script - prints "42"
    engine.run(script)?;

    // Done!
    Ok(())
}
```

--------------------------------

### Build and Run no-std Example

Source: https://rhai.rs/book/print.html

Commands to build and execute a no-std Rhai example using the nightly compiler.

```bash
cd no_std/no_std_test

cargo +nightly build --release

./target/release/no_std_test
```

--------------------------------

### Run Rhai Example

Source: https://rhai.rs/book/print.html

Command to execute a specific Rhai example from the project directory.

```bash
cargo run --example {example_name}
```

--------------------------------

### Install rhai-doc

Source: https://rhai.rs/book/tools/rhai-doc.html

Install the `rhai-doc` tool using cargo.

```bash
cargo install rhai-doc
```

--------------------------------

### Run Rhai Examples

Source: https://rhai.rs/book/start/examples/rust.html

Command to run specific Rhai examples. Replace {example_name} with the desired example directory name.

```bash
cargo run --example {example_name}
```

--------------------------------

### Initial Script Example

Source: https://rhai.rs/book/print.html

A basic Rhai script demonstrating variable calculation and printing.

```rhai
let magic = get_magic() * BAR;

let x = calc_foo(magic);

print(x);
```

--------------------------------

### Example Script with Macros

Source: https://rhai.rs/book/print.html

A script example utilizing macro placeholders for entity manipulation.

```rhai
print(`Found entity FOO at (${x},${y},${z})`);

let speed = #FOO.speed;

if speed < 42 {
    #FOO.speed *= 2;
} else {
    #FOO.teleport(#FOO.home());
}

print(`FOO is now at (${ #FOO.current_location() })`);
```

--------------------------------

### Install Rhai tools

Source: https://rhai.rs/book/print.html

Installs all Rhai tools with full features or a specific binary using cargo.

```bash
cargo install --path . --bins  --features bin-features
```

```bash
cargo install --path . --bin sample_app_to_run  --features bin-features
```

--------------------------------

### Recursive Import Examples

Source: https://rhai.rs/book/print.html

Examples of import cycles that lead to infinite recursion.

```rhai
import "hello" as foo;          // import itself - infinite recursion!

foo::do_something();
```

```rhai
import "world" as foo;
foo::do_something();


┌────────────┐
│ world.rhai │
└────────────┘

import "hello" as bar;
bar::do_something_else();
```

--------------------------------

### Array Manipulation and Access

Source: https://rhai.rs/book/print.html

Examples demonstrating array initialization, insertion, removal, indexing, and iteration.

```Rhai
let y = [2, 3];             // y == [2, 3]

let y = [2, 3,];            // y == [2, 3]

y.insert(0, 1);             // y == [1, 2, 3]

y.insert(999, 4);           // y == [1, 2, 3, 4]

y.len == 4;

y[0] == 1;
y[1] == 2;
y[2] == 3;
y[3] == 4;

(1 in y) == true;           // use 'in' to test if an element exists in the array

(42 in y) == false;         // 'in' uses the 'contains' function, which uses the
                            // '==' operator (that users can override)
                            // to check if the target element exists in the array

y.contains(1) == true;      // the above de-sugars to this

y[1] = 42;                  // y == [1, 42, 3, 4]

(42 in y) == true;

y.remove(2) == 3;           // y == [1, 42, 4]

y.len == 3;

y[2] == 4;                  // elements after the removed element are shifted

ts.list = y;                // arrays can be assigned completely (by value copy)

ts.list[1] == 42;

[1, 2, 3][0] == 1;          // indexing on array literal

[1, 2, 3][-1] == 3;         // negative position counts from the end

fn abc() {
    [42, 43, 44]            // a function returning an array
}

abc()[0] == 42;

y.push(4);                  // y == [1, 42, 4, 4]

y += 5;                     // y == [1, 42, 4, 4, 5]

y.len == 5;

y.shift() == 1;             // y == [42, 4, 4, 5]

y.chop(3);                  // y == [4, 4, 5]

y.len == 3;

y.pop() == 5;               // y == [4, 4]

y.len == 2;

for element in y {          // arrays can be iterated with a 'for' statement
    print(element);
}
```

--------------------------------

### Simulate Command-Style Syntax

Source: https://rhai.rs/book/print.html

Demonstrates how to define multiple command-style syntax patterns that share a common starting keyword.

```rhai
// The following simulates a command-style syntax, all starting with 'perform'.
perform hello world;        // A fixed sequence of symbols
perform action 42;          // Perform a system action with a parameter
perform update system;      // Update the system
perform check all;          // Check all system settings
perform cleanup;            // Clean up the system
perform add something;      // Add something to the system
perform remove something;   // Delete something from the system
```

--------------------------------

### Example Usage of Custom Syntax

Source: https://rhai.rs/book/engine/custom-syntax.html

Demonstrates how to use a custom syntax in Rhai code. This example shows a custom 'exec' statement and how variables declared within it persist.

```rhai
// Assuming the 'exec' custom syntax implementation declares the variable 'hello':
let x = exec [hello < 42] <- foo(1, 2) : {
            hello += bar(hello);
            baz(hello);
        };

print(x);       // variable 'x'  has a value returned by the custom syntax

print(hello);   // variable declared by a custom syntax persists!
```

--------------------------------

### Configure Domain-Specific Engine

Source: https://rhai.rs/book/patterns/domain-tools.html

Example of creating a custom Engine configuration function that registers domain-specific types and modules.

```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
}
```

--------------------------------

### Rhai Implementation Function with '$$' Return Symbol

Source: https://rhai.rs/book/engine/custom-syntax-parsers.html

An example implementation function that uses the '$$' prefix in return symbols to identify which custom syntax variant was parsed. This function expects symbols starting with '$$' to terminate parsing and add the symbol to the input stream.

```rust
__
fn implementation_fn(context: &mut EvalContext, inputs: &[Expression], state: &Dynamic) -> Result<Dynamic, Box<EvalAltResult>>
{
    // Get the last symbol
    let key = inputs.last().unwrap().get_string_value().unwrap();

    // Make sure it starts with '$$'
    assert!(key.starts_with("$$"));

    // Execute the custom syntax expression
    match key {
        "$$hello" => { ... }
        "$$world" => { ... }
        "$$foo" => { ... }
        "$$bar" => { ... }
        _ => Err(...)
    }
}
```

--------------------------------

### Run Rhai REPL with Initialization Scripts

Source: https://rhai.rs/book/start/bin.html

Starts the Rhai REPL tool, first executing 'init1.rhai', 'init2.rhai', and 'init3.rhai' to load functions into the global namespace before entering the interactive session.

```bash
rhai-repl init1.rhai init2.rhai init3.rhai
```

--------------------------------

### Importing and Using Modules

Source: https://rhai.rs/book/print.html

Demonstrates loading modules, accessing functions and sub-modules, and the constant nature of module variables.

```rhai
import mod_file as my_mod;      // load the script file "crypto_42.rhai" and import it as a module named 'my_mod'
                                // notice that module path names can be dynamically constructed!
                                // any expression that evaluates to a string is acceptable after the 'import' keyword

lock::encrypt(secret);          // use functions defined under the module via '::'

lock::hash::sha256(key);        // sub-modules are also supported

print(lock::status);            // module variables are constants

lock::status = "off";           // <- runtime error: cannot modify a constant
```

--------------------------------

### Basic Tag Manipulation in Rhai

Source: https://rhai.rs/book/language/dynamic-tag.html

Demonstrates how to set, get, and use tags with integer values. Shows default tag behavior, direct assignment, function calls, and bit-field operations. Includes an example of a runtime error for out-of-bounds tag values.

```rhai
let x = 42;

x.tag == 0;             // tag defaults to zero

x.tag = 123;            // set tag value

set_tag(x, 123);        // 'set_tag' function also works

x.tag == 123;           // get updated tag value

x.tag() == 123;         // method also works

tag(x) == 123;          // function call style also works

x.tag[3..5] = 2;        // tag can be used as a bit-field

x.tag[3..5] == 2;

let y = x;

y.tag == 123;           // the tag is copied across assignment

y.tag = 3000000000;     // runtime error: 3000000000 is too large for 'i32'
```

--------------------------------

### Dynamic Script Reloading Setup

Source: https://rhai.rs/book/print.html

Initializes a system structure that holds a Rhai engine and an AST with interior mutability for dynamic updates.

```rust
// Main system object
struct System {
    engine: Engine,
    script: Rc<RefCell<AST>>,
      :
}

// Embed Rhai 'Engine' and control script
let engine = Engine::new();
let ast = engine.compile_file("config.rhai")?;

let mut system = System { engine, script: Rc::new(RefCell::new(ast)) };
```

--------------------------------

### Rhai Engine Setup with `|>` Closure

Source: https://rhai.rs/book/rust/packages/create.html

Demonstrates the use of the `|>` syntax to provide a closure for setting up an Engine instance when a package is registered. This allows for direct manipulation of the Engine, such as registering custom types or operators.

```rust
def_package! {
    pub MyPackage(module) {
            :
            :
    } |> |engine| {
        // Call methods on 'engine'
    }
}

```

--------------------------------

### Example Rhai Configuration Script

Source: https://rhai.rs/book/patterns/config.html

A sample Rhai script demonstrating how to call the registered configuration functions to set values, add to lists, and populate maps.

```rhai
┌────────────────┐
│ my_config.rhai │
└────────────────┘

config_set_id("hello");

config_add("foo");          // add to list
config_add("bar", true);    // add to map

if config_contains("hey") || config_is_set("hey") {
    config_add("baz", false);   // add to map
}
```

--------------------------------

### Invalid Expression Syntax Examples

Source: https://rhai.rs/book/print.html

These examples demonstrate operations that will trigger syntax errors because they contain statements or non-expression constructs.

```rust
// The following are all syntax errors because the script
// is not a strict expression.

engine.eval_expression::<() ("x = 42")?;

let ast = engine.compile_expression("let x = 42")?;

let result = engine.eval_expression_with_scope::<i64>(&mut scope,
                    "{ let y = calc(x); x + y }"
             )?;

let fp: FnPtr = engine.eval_expression("|x| x + 1")?;
```

--------------------------------

### Using do-while and do-until loops

Source: https://rhai.rs/book/print.html

Demonstrates do-while and do-until loop syntax with continue and break statements.

```rhai
let x = 10;

do {
    x -= 1;
    if x < 6 { continue; }  // skip to the next iteration
    print(x);
    if x == 5 { break; }    // break out of do loop
} while x > 0;


do {
    x -= 1;
    if x < 6 { continue; }  // skip to the next iteration
    print(x);
    if x == 5 { break; }    // break out of do loop
} until x == 0;
```

--------------------------------

### Recursive function nesting example

Source: https://rhai.rs/book/print.html

A contrived example showing how recursive function calls combined with deep expression nesting can lead to stack overflow.

```rhai
fn deep_calc(a, n) {
    (a+(a+(a+(a+(a+(a+(a+(a+(a+ ... (a+deep_calc(a,n+1)) ... )))))))))
    //                                 ^^^^^^^^^^^^^^^^ recursive call!
}

let a = 42;

let result = (a+(a+(a+(a+(a+(a+(a+(a+(a+ ... (a+deep_calc(a,0)) ... )))))))));
```

--------------------------------

### EnergizerBunny API Example

Source: https://rhai.rs/book/patterns/control.html

This Rust code defines a simple EnergizerBunny struct with methods to control its state and speed. It serves as an example of a system that can be controlled by Rhai scripts.

```rust
struct EnergizerBunny;

impl EnergizerBunny {
    pub fn new () -> Self { ... }
    pub fn go (&mut self) { ... }
    pub fn stop (&mut self) { ... }
    pub fn is_going (&self) { ... }
    pub fn get_speed (&self) -> i64 { ... }
    pub fn set_speed (&mut self, speed: i64) { ... }
}

```

--------------------------------

### Creating and Invoking Function Pointers

Source: https://rhai.rs/book/print.html

Demonstrates how to create function pointers using the Fn constructor or shorthand, and how to invoke them using the call method.

```rhai
fn foo(x) { 41 + x }

let func = Fn("foo");       // use the 'Fn' function to create a function pointer

let func = foo;             // <- short-hand: equivalent to 'Fn("foo")'

print(func);                // prints 'Fn(foo)'

let func = fn_name.Fn();    // <- error: 'Fn' cannot be called in method-call style

func.type_of() == "Fn";     // type_of() as function pointer is 'Fn'

func.name == "foo";

func.call(1) == 42;         // call a function pointer with the 'call' method

foo(1) == 42;               // <- the above de-sugars to this

call(func, 1);              // normal function call style also works for 'call'

let len = Fn("len");        // 'Fn' also works with registered native Rust functions

len.call("hello") == 5;

let fn_name = "hello";      // the function name does not have to exist yet

let hello = Fn(fn_name + "_world");

hello.call(0);              // error: function not found - 'hello_world (i64)'
```

--------------------------------

### Map Rhai Bin Tools to Project Paths

Source: https://rhai.rs/book/patterns/domain-tools.html

Mapping of standard Rhai binary tool source files to project-specific example paths.

```text
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
```

--------------------------------

### Getting Dynamic Value Type Name

Source: https://rhai.rs/book/language/dynamic-rust.html

Use `type_name` to get the full Rust path name of the data within a Dynamic value, useful for pattern matching.

```rust
let list: Array = engine.eval("...")?;
let item = list[0];

match item.type_name() {
    "()" => ...
    "i64" => ...
    "f64" => ...
    "rust_decimal::Decimal" => ...
    "core::ops::range::Range<i64>" => ...
    "core::ops::range::RangeInclusive<i64>" => ...
    "alloc::string::String" => ...
    "bool" => ...
    "char" => ...
    "rhai::FnPtr" => ...
    "std::time::Instant" => ...
    "crate::path::to::module::TestStruct" => ...
        :
}
```

--------------------------------

### Example of Deeply Nested Expression

Source: https://rhai.rs/book/safety/max-stmt-depth.html

This example demonstrates a deeply nested expression that could potentially cause a stack overflow during parsing if the maximum expression depth limits are exceeded.

```rust
let a = (1+(1+(1+(1+(1+(1+(1+(1+(1+(1+(...)+1)))))))))));
```

--------------------------------

### Macro Expansion Example in Rust

Source: https://rhai.rs/book/patterns/macros.html

Demonstrates how to use Rust's string replace method to expand macro-like syntax in a script before execution. This is useful for simplifying complex property access chains.

```rust
let script = script.replace("#FOO", "foo[x][y].bar[z].baz");

let mut scope = Scope::new();

// Add global variables
scope.push("foo", ...);
scope.push_constant("x", ...);
scope.push_constant("y", ...);
scope.push_constant("z", ...);

// Run the script as normal
engine.run_with_scope(&mut scope, script)?;
```

--------------------------------

### Rhai Array Size Limit Example

Source: https://rhai.rs/book/safety/max-array-size.html

Demonstrates how Rhai detects and raises an error when an array tree exceeds the maximum size limit, even if individual arrays are small. This includes examples of recursive array growth and infinite loops creating nested arrays.

```rhai
// Small, innocent array...
let small_array = [42];             // 1-deep... 1 item, 1 array

// ... becomes huge when multiplied!
small_array.push(small_array);      // 2-deep... 2 items, 2 arrays
small_array.push(small_array);      // 3-deep... 4 items, 4 arrays
small_array.push(small_array);      // 4-deep... 8 items, 8 arrays
small_array.push(small_array);      // 5-deep... 16 items, 16 arrays
          :
          :
small_array.push(small_array);      // <- Rhai raises an error somewhere here
small_array.push(small_array);      //    when the TOTAL number of items in
small_array.push(small_array);      //    the entire array tree exceeds limit

// Or this abomination...
let a = [ 42 ];

loop {
    a[0] = a;       // <- only 1 item, but infinite number of arrays
```

--------------------------------

### Define a recursive function

Source: https://rhai.rs/book/print.html

An example of a function that triggers infinite recursion.

```rhai
// This is a function that, when called, recurses forever.
fn recurse_forever() {
    recurse_forever();
}
```

--------------------------------

### Constructing a 16-byte command buffer

Source: https://rhai.rs/book/print.html

Demonstrates initializing a BLOB, writing ASCII data to a specific range, calculating a CRC, and sending the buffer to a device.

```rhai
// Assume the following 16-byte command for an embedded device:
// ┌─────────┬───────────────┬──────────────────────────────────┬───────┐
// │    0    │       1       │              2-13                │ 14-15 │
// ├─────────┼───────────────┼──────────────────────────────────┼───────┤
// │ command │ string length │ ASCII string, max. 12 characters │  CRC  │
// └─────────┴───────────────┴──────────────────────────────────┴───────┘

let buf = blob(16, 0);      // initialize command buffer

let text = "foo & bar";     // text string to send to device

buf[0] = 0x42;              // command code
buf[1] = s.len();           // length of string

buf.write_ascii(2..14, text);   // write the string

let crc = buf.calc_crc();   // calculate CRC

buf.write_le(14, 2, crc);   // write CRC

print(buf);                 // prints "[4209666f6f202620 626172000000abcd]"
                            //          ^^ command code              ^^^^ CRC
                            //            ^^ string length
                            //              ^^^^^^^^^^^^^^^^^^^ foo & bar

device.send(buf);           // send command to device
```

--------------------------------

### Configure `no-std` Build with Allocator and Panic Handlers

Source: https://rhai.rs/book/start/builds/no-std.html

This example demonstrates the necessary Rust compiler flags, external crate inclusions, and handler implementations for a `no-std` environment. It includes setting up `wee_alloc` as the global allocator and defining custom panic and error handlers that abort the program.

```rust
#![no_std]

#![feature(alloc_error_handler, start, core_intrinsics, lang_items, link_cfg)]

extern crate alloc;
extern crate wee_alloc;

#[global_allocator]
static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT;

#[cfg(all(windows, target_env = "msvc"))]
#[link(name = "msvcrt")]
#[link(name = "libcmt")]
extern "C" {}

#[alloc_error_handler]
fn err_handler(_: core::alloc::Layout) -> !
{
    core::intrinsics::abort();
}

#[panic_handler]
#[lang = "panic_impl"]
extern "C" fn rust_begin_panic(_: &core::panic::PanicInfo) -> !
{
    core::intrinsics::abort();
}

#[lang = "eh_personality"]
extern "C" fn eh_personality() {}

#[no_mangle]
extern "C" fn rust_eh_register_frames() {}

#[no_mangle]
extern "C" fn rust_eh_unregister_frames() {}

#[no_mangle]
extern "C" fn _Unwind_Resume() {}

#[start]
fn main(_argc: isize, _argv: *const *const u8) -> isize {
    // ... main program ...
}
```

--------------------------------

### Define a script function

Source: https://rhai.rs/book/print.html

Example of a simple script-defined function signature.

```rhai
fn foo(x, y, z) {}
```

--------------------------------

### Array Initialization and Basic Operations

Source: https://rhai.rs/book/language/arrays.html

Demonstrates array creation, insertion at specific indices, checking length, and accessing elements. Supports trailing commas in initialization.

```rhai
let y = [2, 3];             // y == [2, 3]

let y = [2, 3,];            // y == [2, 3]

y.insert(0, 1);             // y == [1, 2, 3]

y.insert(999, 4);           // y == [1, 2, 3, 4]

y.len == 4;

y[0] == 1;
y[1] == 2;
y[2] == 3;
y[3] == 4;
```

--------------------------------

### Get Character at Position

Source: https://rhai.rs/book/ref/string-fn.html

Retrieve a character from a string at a specific position.

```APIDOC
## get

### Description
Gets the character at a certain position (returns `()` if the position is not valid). Position counts from the end if negative.

### Parameters
#### Path Parameters
- **position** (integer) - Description: Position to get the character from. Counting from the end if negative.

### Method
Function
```

--------------------------------

### AST Structure Representation

Source: https://rhai.rs/book/print.html

A conceptual representation of the AST generated by the example script.

```text
FnDef {
    Name: "sum",
    ThisType: None,
    Parameters: [
        "x",
        "y"
    ],
    Body: Block [
        Return {
            Expression {
                FnCall {
                    Name: "+",
                    Arguments: [
                        Variable "x",
                        Variable "y"
                    ]
                }
            }
        }
    ]
}
Block [
    FnCall {
        Name: "print",
        Arguments: [
            Expression {
                FnCall {
                    Name: "sum",
                    Arguments: [
                        Constant 42,
                        Constant 1
                    ]
                }
            }
        ]
    }
]
```

--------------------------------

### Configure Engine with the |> operator

Source: https://rhai.rs/book/print.html

Shows the syntax for the optional closure block that runs during package registration to perform Engine-level setup.

```rust
def_package! {
    pub MyPackage(module) {
            :
            :
    } |> |engine| {
        // Call methods on 'engine'
    }
}
```

--------------------------------

### String Length and Byte Count

Source: https://rhai.rs/book/ref/string-fn.html

Get the number of characters or bytes in a string.

```APIDOC
## len

### Description
Returns the number of characters (not number of bytes) in the string.

### Method
Property

## bytes

### Description
Returns the number of bytes making up the UTF-8 string. For strings containing only ASCII characters, this is much faster than `len`.

### Method
Property
```

--------------------------------

### Example Rhai Script

Source: https://rhai.rs/book/print.html

A simple Rhai script demonstrating function definition and printing.

```rhai
fn sum(x, y) { x + y }
print(sum(42, 1));
```

--------------------------------

### Constructing and Sending a Binary Command Buffer

Source: https://rhai.rs/book/print.html

Demonstrates initializing a 16-byte buffer, writing ASCII data, calculating a CRC, and printing the resulting byte stream.

```rhai
let buf = blob(16, 0);      // initialize command buffer

let text = "foo & bar";     // text string to send to device

buf[0] = 0x42;              // command code
buf[1] = s.len();           // length of string

buf.write_ascii(2..14, text);   // write the string

let crc = buf.calc_crc();   // calculate CRC

buf.write_le(14, 2, crc);   // write CRC

print(buf);                 // prints "[4209666f6f202620 626172000000abcd]"
                            //          ^^ command code              ^^^^ CRC
                            //            ^^ string length
                            //              ^^^^^^^^^^^^^^^^^^^ foo & bar

device.send(buf);           // send command to device
```

--------------------------------

### Create Function Pointer (Short-hand vs Fn)

Source: https://rhai.rs/book/language/fn-ptr.html

Demonstrates the short-hand notation for creating function pointers to script-defined functions, which is equivalent to using the `Fn` function.

```rhai
fn foo() { ... }        // function definition

let f = foo;            // function pointer to 'foo'

let f = Fn("foo");      // <- the above is equivalent to this

let g = bar;            // error: variable 'bar' not found
```

--------------------------------

### Event Handler Functions

Source: https://rhai.rs/book/print.html

Example implementations of 'end' and 'update' event handlers in Rhai.

```rhai
/// 'end' event handler
fn end(data) {
    if !bool_state {
        throw "Not yet started!";
    }
    if !obj_state.func1() && !obj_state.func2() {
        throw "Conditions not yet ready to end!";
    }
    bool_state = false;
    obj_state.value = data;
}

/// 'update' event handler
fn update(data) {
    obj_state.value += process(data);

    // Without OOP support, can only call function
    log(obj_state.value, data);
}
```

--------------------------------

### Define an object with anonymous functions

Source: https://rhai.rs/book/print.html

Example of an object structure containing anonymous functions.

```rhai
let obj = #{
    data: 42,
    increment: anon_fn_0003,
    decrement: anon_fn_0004,
    print: anon_fn_0005
};
```

--------------------------------

### rhai-doc Configuration File Example

Source: https://rhai.rs/book/tools/rhai-doc.html

A sample `rhai.toml` configuration file for `rhai-doc`. This file customizes project name, theme color, root URL, index file, icon, stylesheet, code highlighting, script extension, and external links.

```toml
name = "My Rhai Project"                # project name
color = [246, 119, 2]                   # theme color
root = "/docs/"                         # root URL for generated site
index = "home.md"                       # this file becomes 'index.html'
icon = "logo.svg"                       # project icon
stylesheet = "my_stylesheet.css"        # custom stylesheet
code_theme = "atom-one-light"           # 'highlight.js' theme
code_lang = "ts"                        # default language for code blocks
extension = "rhai"                      # script extension
google_analytics = "G-ABCDEF1234"       # Google Analytics ID

[[links]]                               # external link for 'Blog'
name = "Blog"
link = "https://example.com/blog"

[[links]]                               # external link for 'Tools'
name = "Tools"
link = "https://example.com/tools"
```

--------------------------------

### Accessing nested properties

Source: https://rhai.rs/book/print.html

Example of accessing a nested property using bracket notation.

```Rhai
print(root.prop1.sub["hello"].list[0].value);
```

--------------------------------

### Register UrlPackage into Engine

Source: https://rhai.rs/book/lib/rhai-url.html

Initialize the UrlPackage and register it into the Rhai Engine to enable URL support.

```rust
use rhai::Engine;
use rhai::packages::Package;    // needed for 'Package' trait
use rhai_url::UrlPackage;

let mut engine = Engine::new();

// Create new 'UrlPackage' instance
let url = UrlPackage::new();

// Load the package into the `Engine`
url.register_into_engine(&mut engine);
```

--------------------------------

### Using infinite loop

Source: https://rhai.rs/book/print.html

Demonstrates the infinite loop construct with break and continue control flow.

```rhai
let x = 10;

loop {
    x -= 1;

    if x > 5 { continue; }  // skip to the next iteration

    print(x);

    if x == 0 { break; }    // break out of loop
}
```

--------------------------------

### BLOB Accessor Functions

Source: https://rhai.rs/book/language/blobs.html

Functions to get or set individual bytes within a BLOB.

```APIDOC
## get

### Description
Gets a copy of the byte at a certain position (0 if the position is not valid). Position can be counted from the end if negative.

### Parameters
- position (integer) - The index of the byte to retrieve. Negative values count from the end.
```

```APIDOC
## set

### Description
Sets a certain position to a new value (no effect if the position is not valid). Position can be counted from the end if negative.

### Parameters
1. position (integer) - The index of the byte to set. Negative values count from the end.
2. new_byte (integer) - The new byte value to set.
```

--------------------------------

### Crop String

Source: https://rhai.rs/book/ref/string-fn.html

Retain only a portion of a string based on start position and length, or a range.

```APIDOC
## crop

### Description
Retains only a portion of the string. Can be used with a start position and a count, or with a range.

### Parameters
#### Path Parameters
- **start_position** (integer) - Description: The starting position for the portion to retain. Counting from the end if negative.
- **count** (integer) - Optional. The number of characters to retain. None if ≤ 0, to the end if omitted.

### Method
Function

## crop (range)

### Description
Retains only a portion of the string using a range.

### Parameters
#### Path Parameters
- **range** (range) - Description: The range of characters to retain, from beginning if ≤ 0, to end if ≥ length.

### Method
Function
```

--------------------------------

### Example Script Using Custom SQL Syntax

Source: https://rhai.rs/book/engine/custom-syntax-arbitrary-text.html

This script demonstrates how to use the custom 'SELECT' syntax registered previously. It shows variable substitution for 'nobody', 'min_amount', and 'max_total', and block substitution for SQL clauses.

```rhai
__
let nobody = "John Doe";
let min_amount = 100.0;
let max_total = 1000.0;

let records = SELECT
                id,
                SUM(amount) AS `total`,
                FIRST('http://hitme.com/') + id AS `link`
              FROM db.public.users
              WHERE name <> {nobody} AND amount >= {min_amount}
              GROUP BY id
              HAVING SUM(amount) <= @max_total;


```

--------------------------------

### Extract Sub-string

Source: https://rhai.rs/book/ref/string-fn.html

Extract a portion of a string based on start position and length, or a range.

```APIDOC
## sub_string

### Description
Extracts a sub-string. Can be used with a start position and a count, or with a range.

### Parameters
#### Path Parameters
- **start_position** (integer) - Description: The starting position for the sub-string. Counting from the end if negative.
- **count** (integer) - Optional. The number of characters to extract. None if ≤ 0, to the end if omitted.

### Method
Function

## sub_string (range)

### Description
Extracts a sub-string using a range.

### Parameters
#### Path Parameters
- **range** (range) - Description: The range of characters to extract, from beginning if ≤ 0, to end if ≥ length.

### Method
Function
```

--------------------------------

### Using 'take' to Return Large Values from Functions

Source: https://rhai.rs/book/language/assignment.html

Demonstrates how to use 'take' to efficiently return large data structures from functions without cloning, contrasting it with a naive cloning approach.

```rhai
fn get_large_value_naive() {
    let large_result = do_complex_calculation();

    large_result.done = true;

    // Return a cloned copy of the result, then the
    // local variable 'large_result' is thrown away!
    large_result
}

fn get_large_value_smart() {
    let large_result = do_complex_calculation();

    large_result.done = true;

    // Return the result without cloning!
    // Method style call is also OK.
    large_result.take()
}
```

--------------------------------

### Run Rhai App with Features

Source: https://rhai.rs/book/start/bin.html

Executes a Rhai binary application, 'sample_app_to_run', using Cargo, ensuring that 'bin-features' are enabled. This is an alternative to direct installation.

```bash
cargo run --features bin-features --bin sample_app_to_run
```

--------------------------------

### Conditional if statements

Source: https://rhai.rs/book/print.html

Examples of standard if-else structures, mandatory brace requirements, and using if as an expression.

```Rhai
if foo(x) {
    print("It's true!");
} else if bar == baz {
    print("It's true again!");
} else if baz.is_foo() {
    print("Yet again true.");
} else if foo(bar - baz) {
    print("True again... this is getting boring.");
} else {
    print("It's finally false!");
}
```

```Rhai
// Rhai is not C!
if (decision) print(42);
//            ^ syntax error, expecting '{'
```

```Rhai
// The following is equivalent to C: int x = 1 + (decision ? 42 : 123) / 2;
let x = 1 + if decision { 42 } else { 123 } / 2;
x == 22;

let x = if decision { 42 }; // no else branch defaults to '()'
x == ();
```

```Rhai
fn index_of(x) {
    // 'if' is parsed primarily as a statement
    if this.contains(x) {
        return this.find_index(x)
    }
```

--------------------------------

### Variable Declaration Examples

Source: https://rhai.rs/book/print.html

Shows valid and invalid variable declarations and the case sensitivity of names.

```Rhai
let x;              // ok - value is '()'
let x = 3;          // ok
let _x = 42;        // ok
let x_ = 42;        // also ok
let _x_ = 42;       // still ok

let _ = 123;        // <- syntax error: illegal variable name
let _9 = 9;         // <- syntax error: illegal variable name

let x = 42;         // variable is 'x', lower case
let X = 123;        // variable is 'X', upper case
```
Tokens:
Raw