boa-cat 0.2.0

Tree-walking ECMAScript interpreter built on ecma-syntax-cat. Evaluates Script programs to Values with a persistent heap and lexical environment, plus native (Rust-implemented) callables for embedder-supplied built-ins. No mut, no Rc/Arc, no interior mutability, no panics, exhaustive matches. Comp-cat-rs reformulation of the Boa engine core, targeting Tauri integration.
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

//! Expression-evaluation outcomes.
//!
//! Every expression evaluation either returns a [`Value`] (`Normal`) or
//! propagates a JavaScript-level exception value (`Throw`).  Both forms
//! are paired with the updated [`Heap`] and [`Fuel`] state.
//!
//! Engine-fatal errors (out-of-fuel, unsupported AST) are returned via
//! [`Error`] (`Result::Err`), not via this enum.
//!
//! [`Heap`]: crate::heap::Heap
//! [`Fuel`]: crate::fuel::Fuel
//! [`Error`]: crate::error::Error

use crate::fuel::Fuel;
use crate::heap::Heap;
use crate::value::Value;

/// The outcome of evaluating an expression.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Outcome {
    /// Normal completion carrying a value.
    Normal(Value),
    /// `throw value`.
    Throw(Value),
}

impl Outcome {
    /// Map the value under `Normal`, leaving `Throw` untouched.
    #[must_use]
    pub fn map_normal(self, f: impl FnOnce(Value) -> Value) -> Self {
        match self {
            Self::Normal(v) => Self::Normal(f(v)),
            Self::Throw(v) => Self::Throw(v),
        }
    }
}

/// Result of an expression evaluation step.
pub type EvalResult = Result<(Outcome, Heap, Fuel), crate::error::Error>;

/// Continue from a normal outcome; propagate a throw.
///
/// Performs the common monadic-bind on `EvalResult`: when `result` is a
/// fatal error, propagate it; when it's a throw, propagate the throw with
/// updated `Heap`/`Fuel`; when it's a normal value, hand it to `k`.
///
/// # Errors
///
/// Propagates any [`Error`] from `result` or from `k`.
///
/// [`Error`]: crate::error::Error
pub fn step<F>(result: EvalResult, k: F) -> EvalResult
where
    F: FnOnce(Value, Heap, Fuel) -> EvalResult,
{
    result.and_then(|(outcome, heap, fuel)| match outcome {
        Outcome::Throw(v) => Ok((Outcome::Throw(v), heap, fuel)),
        Outcome::Normal(v) => k(v, heap, fuel),
    })
}