rhai_trace 0.3.1

A small library providing better error and span support for Rhai, the embeddable programming language.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

# Propagating Better Errors

`rhai_trace` enables **structured, insightful error reporting** by transforming raw Rhai errors into enriched diagnostics. Instead of handling opaque error messages, developers can seamlessly integrate contextualized error reports into tooling like IDEs or debuggers.

## Core Concept: `BetterError`

At its heart is the `BetterError` struct, designed to aggregate error metadata:

```rust, ignore
pub struct BetterError {
    pub message: String,
    pub help: Option<String>,
    pub hint: Option<String>,
    pub note: Option<String>,
    pub span: Span,
}
```

- **Message**: what went wrong (original error)
- **Help**: actionable suggestions
- **Hint**: contextual nudges
- **Note**: additional insights
- **Span**: location in source code

`BetterError` makes it possible to enhance diagnostics with code context or execution.

## Improving Errors

`rhai_trace` offers two functions for enhancing diagnostics:

### `BetterError::improve_eval_error`

Used for runtime errors where the script was successfully parsed and spans can be extracted.

```rust, ignore
if let Ok(better) = BetterError::improve_eval_error(
    &e,
    &code,
    &engine,
    None // <-- can replace with spans from `SpanTracker`
) {
    // Use `better` to enrich error reporting in tooling
} else {
    eprintln!("Original Error: {:?}", e);
}
```

If you want `improve_eval_error` to not extract spans every time, then you can pass the result from `SpanTracer` as the fourth argument.

This may be useful if you want to improve performance by caching the spans and reusing it when needed.

### `BetterError::improve_parse_error`

Used for syntax errors where the script failed to compile and spans cannot be extracted.

```rust, ignore
let ast = engine.compile(code)
    .map_err(|e| BetterError::improve_parse_error(&e, &code, &engine));
```

`improve_parse_error` does **not** require spans because parsing failed before code locations could be reliably extracted.

## Practical Example

```rust, ignore
use rhai_trace::*;

fn main() {
    let code = r#"
        fn multiply(x, y) { x * y }
        print(multiply("a", 7)); // triggers runtime error
    "#;

    let engine = Engine::new();

    match engine.eval::<rhai::Dynamic>(code) {
        Ok(_) => println!("Executed successfully"),
        Err(e) => {
            if let Ok(better) = BetterError::improve_eval_error(
                &e,
                code,
                &engine,
                None
            ) {
                // `better` == `BetterError`
                //
                // Each value can be extracted and
                // piped to diagnostic tools.
                plug_into_codespan(better);
            } else {
                eprintln!("Original Error: {:?}", e);
            }
        }
    }
}
```