Struct EvalCtx 

pub struct EvalCtx {
    pub fuel: usize,
    pub ops: HashMap<String, Arc<CustomOp>>,
}

Per-evaluation context: fuel budget + custom operator map.

EvalCtx is Send + Sync. Build once, share via Arc<EvalCtx> across threads. Each evaluate() call receives &EvalCtx and maintains its own stack-local fuel counter — no shared mutable state.

Fields

fuel: usize

Maximum AST nodes the evaluator may visit. Default: 200.

ops: HashMap<String, Arc<CustomOp>>

Custom operator map: operator name → handler.

Implementations

impl EvalCtx

pub fn new() -> Self

Create a context with 200 fuel and no custom operators.

Example

use fsm_guards::EvalCtx;
let ctx = EvalCtx::new();
assert_eq!(ctx.fuel, 200);

Examples found in repository

examples/basic_guard.rs (line 9)

fn main() {
    let ctx = EvalCtx::new();

    // Simple equality check
    let approved = evaluate(
        &json!({"==": [{"var": "status"}, "approved"]}),
        &json!({"status": "approved"}),
        &ctx,
    )
    .unwrap();
    println!("approved: {approved}"); // true

    // Compound rule
    let ready = evaluate(
        &json!({"and": [
            {"==": [{"var": "status"}, "active"]},
            {">=": [{"var": "score"}, 80]},
            {"in": [{"var": "role"}, ["admin", "operator"]]}
        ]}),
        &json!({"status": "active", "score": 95, "role": "admin"}),
        &ctx,
    )
    .unwrap();
    println!("ready: {ready}"); // true

    // Missing variable — detected before evaluation
    match evaluate(
        &json!({"var": "nonexistent"}),
        &json!({"status": "active"}),
        &ctx,
    ) {
        Err(GuardError::MissingVar(path)) => println!("missing var: {path}"),
        other => println!("unexpected: {other:?}"),
    }
}

examples/fuel_limits.rs (line 17)

fn main() {
    // ── short-circuit: or stops on first true ──────────────────────────────
    // Build a 200-node branch that would blow a pre-walk budget.
    let mut deep = json!({"==": [1, 2]});
    for _ in 0..50 {
        deep = json!({"and": [deep, {"==": [1, 2]}]});
    }
    let rule = json!({"or": [true, deep]});

    let ctx = EvalCtx::new().with_fuel(5);
    let result = evaluate(&rule, &json!({}), &ctx).unwrap();
    println!("short-circuit or: {result}"); // true — only ~2 nodes visited

    // ── budget exhausted ───────────────────────────────────────────────────
    let rule = json!({"and": [
        {"==": [1, 1]},
        {"==": [2, 2]},
        {"==": [3, 3]}
    ]});

    match evaluate(&rule, &json!({}), &EvalCtx::new().with_fuel(5)) {
        Ok(v) => println!("passed with fuel:5 → {v}"),
        Err(GuardError::FuelExceeded { limit }) => println!("exceeded limit:{limit}"),
        Err(e) => println!("error: {e}"),
    }

    // ── default fuel (200) handles realistic guards comfortably ───────────
    let ctx = EvalCtx::new(); // fuel: 200
    let rule = json!({"and": [
        {"==": [{"var": "status"}, "active"]},
        {">=": [{"var": "score"}, 80]},
        {"in": [{"var": "role"}, ["admin", "operator"]]}
    ]});
    let data = json!({"status": "active", "score": 95, "role": "admin"});
    println!("realistic guard: {}", evaluate(&rule, &data, &ctx).unwrap()); // true
}

examples/custom_operators.rs (line 11)

fn main() {
    // ── state_in: membership check ─────────────────────────────────────────
    let ctx = EvalCtx::new().with_op("state_in", |args| {
        Ok(Value::Bool(args[1..].contains(&args[0])))
    });

    let rule = json!({"state_in": [{"var": "status"}, "active", "pending"]});
    println!("active → {}", evaluate(&rule, &json!({"status": "active"}), &ctx).unwrap()); // true
    println!("blocked → {}", evaluate(&rule, &json!({"status": "blocked"}), &ctx).unwrap()); // false

    // ── multiple operators ─────────────────────────────────────────────────
    let ctx = EvalCtx::new()
        .with_op("state_in", |args| Ok(Value::Bool(args[1..].contains(&args[0]))))
        .with_op("days_since", |args| {
            // Stub: in production this would compute real elapsed days
            let recorded = args[0].as_f64().unwrap_or(0.0);
            let now = args[1].as_f64().unwrap_or(0.0);
            Ok(json!(now - recorded))
        });

    let rule = json!({"and": [
        {"state_in": [{"var": "status"}, "active", "pending"]},
        {"<": [{"days_since": [{"var": "created_at"}, 1722470400.0]}, 30]}
    ]});
    let data = json!({"status": "active", "created_at": 1720000000.0});
    println!("compound: {}", evaluate(&rule, &data, &ctx).unwrap());

    // ── Arc sharing across threads ─────────────────────────────────────────
    let shared_ctx = Arc::new(
        EvalCtx::new().with_op("always_true", |_| Ok(Value::Bool(true))),
    );

    let handles: Vec<_> = (0..4)
        .map(|i| {
            let ctx = Arc::clone(&shared_ctx);
            let rule = json!({"always_true": []});
            std::thread::spawn(move || {
                let result = evaluate(&rule, &json!({}), &ctx).unwrap();
                println!("thread {i}: {result}");
            })
        })
        .collect();

    for h in handles {
        h.join().unwrap();
    }
}

pub fn with_fuel(self, fuel: usize) -> Self

Override the fuel budget.

Example

use fsm_guards::EvalCtx;
let ctx = EvalCtx::new().with_fuel(50);
assert_eq!(ctx.fuel, 50);

Examples found in repository

examples/fuel_limits.rs (line 17)

fn main() {
    // ── short-circuit: or stops on first true ──────────────────────────────
    // Build a 200-node branch that would blow a pre-walk budget.
    let mut deep = json!({"==": [1, 2]});
    for _ in 0..50 {
        deep = json!({"and": [deep, {"==": [1, 2]}]});
    }
    let rule = json!({"or": [true, deep]});

    let ctx = EvalCtx::new().with_fuel(5);
    let result = evaluate(&rule, &json!({}), &ctx).unwrap();
    println!("short-circuit or: {result}"); // true — only ~2 nodes visited

    // ── budget exhausted ───────────────────────────────────────────────────
    let rule = json!({"and": [
        {"==": [1, 1]},
        {"==": [2, 2]},
        {"==": [3, 3]}
    ]});

    match evaluate(&rule, &json!({}), &EvalCtx::new().with_fuel(5)) {
        Ok(v) => println!("passed with fuel:5 → {v}"),
        Err(GuardError::FuelExceeded { limit }) => println!("exceeded limit:{limit}"),
        Err(e) => println!("error: {e}"),
    }

    // ── default fuel (200) handles realistic guards comfortably ───────────
    let ctx = EvalCtx::new(); // fuel: 200
    let rule = json!({"and": [
        {"==": [{"var": "status"}, "active"]},
        {">=": [{"var": "score"}, 80]},
        {"in": [{"var": "role"}, ["admin", "operator"]]}
    ]});
    let data = json!({"status": "active", "score": 95, "role": "admin"});
    println!("realistic guard: {}", evaluate(&rule, &data, &ctx).unwrap()); // true
}

pub fn with_op<F>(self, name: &str, f: F) -> Self

where F: Fn(&[Value]) -> Result<Value, Box<dyn Error + Send + Sync>> + Send + Sync + 'static,

Register a custom operator. Operators are matched by exact name string.

The handler receives already-evaluated argument values. It may be called from multiple threads if the EvalCtx is shared via Arc.

Example

use fsm_guards::{evaluate, EvalCtx};
use serde_json::json;

let ctx = EvalCtx::new().with_op("double", |args| {
    let n = args[0].as_f64().unwrap_or(0.0);
    Ok(serde_json::json!(n * 2.0))
});

// {"double": [5]} returns 10.0, which is truthy.
assert!(evaluate(&json!({"double": [5]}), &json!({}), &ctx).unwrap());

Examples found in repository

examples/custom_operators.rs (lines 11-13)

fn main() {
    // ── state_in: membership check ─────────────────────────────────────────
    let ctx = EvalCtx::new().with_op("state_in", |args| {
        Ok(Value::Bool(args[1..].contains(&args[0])))
    });

    let rule = json!({"state_in": [{"var": "status"}, "active", "pending"]});
    println!("active → {}", evaluate(&rule, &json!({"status": "active"}), &ctx).unwrap()); // true
    println!("blocked → {}", evaluate(&rule, &json!({"status": "blocked"}), &ctx).unwrap()); // false

    // ── multiple operators ─────────────────────────────────────────────────
    let ctx = EvalCtx::new()
        .with_op("state_in", |args| Ok(Value::Bool(args[1..].contains(&args[0]))))
        .with_op("days_since", |args| {
            // Stub: in production this would compute real elapsed days
            let recorded = args[0].as_f64().unwrap_or(0.0);
            let now = args[1].as_f64().unwrap_or(0.0);
            Ok(json!(now - recorded))
        });

    let rule = json!({"and": [
        {"state_in": [{"var": "status"}, "active", "pending"]},
        {"<": [{"days_since": [{"var": "created_at"}, 1722470400.0]}, 30]}
    ]});
    let data = json!({"status": "active", "created_at": 1720000000.0});
    println!("compound: {}", evaluate(&rule, &data, &ctx).unwrap());

    // ── Arc sharing across threads ─────────────────────────────────────────
    let shared_ctx = Arc::new(
        EvalCtx::new().with_op("always_true", |_| Ok(Value::Bool(true))),
    );

    let handles: Vec<_> = (0..4)
        .map(|i| {
            let ctx = Arc::clone(&shared_ctx);
            let rule = json!({"always_true": []});
            std::thread::spawn(move || {
                let result = evaluate(&rule, &json!({}), &ctx).unwrap();
                println!("thread {i}: {result}");
            })
        })
        .collect();

    for h in handles {
        h.join().unwrap();
    }
}

Trait Implementations

impl Default for EvalCtx

fn default() -> Self

Returns the “default value” for a type.