Struct Evaluator 

pub struct Evaluator {

    pub globals: Vec<EnvironmentItem>,
    pub environment: Vec<Vec<EnvironmentItem>>,
    pub scope_pool: Vec<Vec<EnvironmentItem>>,
    pub source_file: Option<SourceFile>,
    pub root_module: Module,
    pub return_value: Option<Value>,
    pub is_breaking: bool,
    pub is_continuing: bool,
    pub output_buffer: Option<String>,
    pub rng: Xoshiro256,
    pub resolver: Resolver,
    pub fn_names: HashMap<String, usize>,
    pub user_args_offset: usize,
    pub net_handles: HashMap<i64, NetHandle>,
    pub net_next_handle: i64,
    pub http_handles: HashMap<i64, HttpHandle>,
    pub http_next_handle: i64,
    pub records: HashMap<String, Vec<(String, TypeAnnotation)>>,
    pub tags: HashMap<String, Vec<String>>,
}

The tree-walking interpreter, carrying all runtime state.

Fields

globals: Vec<EnvironmentItem>

Global scope, addressed at the outermost depth

environment: Vec<Vec<EnvironmentItem>>

The environment stack - each frame is a scope; innermost is last. Holds only local call frames

scope_pool: Vec<Vec<EnvironmentItem>>

Pool of previously-used, now-empty scope frames. push_scope/ pop_scope recycle through here instead of allocating a fresh Vec on every function call and block entry - a hot recursive function otherwise pays one malloc+free per call just for its frame.

source_file: Option<SourceFile>

Source file for Ariadne error rendering; None in embedded/test contexts.

root_module: Module

The stdlib module tree, used for resolving std::* calls.

return_value: Option<Value>

Set by a return statement; cleared when the enclosing function call collects it.

is_breaking: bool

Set by break; cleared by the enclosing loop after it exits.

is_continuing: bool

Set by continue; cleared by the enclosing loop at the top of the next iteration.

output_buffer: Option<String>

When Some, print/println write here instead of stdout (used by the LSP and REPL).

rng: Xoshiro256

The Xoshiro256** PRNG instance shared across all std::random calls.

resolver: Resolver

The resolver, kept alive so import statements can resolve newly loaded files inline. Also owns ast_arena: Ast - the single expression arena for this session, shared by the resolver and evaluator alike. Never construct a second Ast anywhere else; everything reads/writes through self.resolver.ast_arena.

fn_names: HashMap<String, usize>

Maps top-level function names to their environment slot for call_path shortcut.

user_args_offset: usize

net_handles: HashMap<i64, NetHandle>

Side-table of native networking resources (std::net), keyed by handle id.

net_next_handle: i64

Next handle id to hand out for std::net resources; only ever increments.

http_handles: HashMap<i64, HttpHandle>

Side-table of native HTTP resources (std::http), keyed by handle id.

http_next_handle: i64

Next handle id to hand out for std::http resources; only ever increments.

records: HashMap<String, Vec<(String, TypeAnnotation)>>

Maps record type names to their declared (field name, field type) list, in declaration order. Populated when a RecordDeclaration statement runs.

tags: HashMap<String, Vec<String>>

Maps tag (enum) type names to their declared variant name list, in declaration order. Populated when a TagDeclaration statement runs.

Implementations

impl Evaluator

pub fn new() -> Self

pub fn with_source_file(self, file: SourceFile) -> Self

Attaches a source file for error rendering.

pub fn set_source_file(&mut self, file: SourceFile)

Attaches a source file for error rendering (mutable reference variant).

pub fn with_module(self, m: Module) -> Self

Registers a Module as a submodule of the root module.

pub fn with_function<F, A>(self, name: impl Into<String>, f: F) -> Self

where F: IntoNativeFn<A>,

Registers a typed Rust function directly on the root module.

pub fn with_stdlib(self) -> Self

Loads the full stdlib into the root module under std::*.

pub fn with_user_args_offset(self, offset: usize) -> Self

pub fn err(&self, message: impl Into<String>, span: Span) -> Error

Build a Reason::Runtime error anchored at span, with source attached when known.

pub fn infer_type(value: &Value, is_const: bool) -> TypeAnnotation

Infers the TypeAnnotation of a runtime Value.

For arrays, uses the type of the first element; empty arrays infer Null. is_const controls whether the result is the mutable or const variant.

pub fn value_compatible(value: &Value, expected: &TypeAnnotation) -> bool

Returns true if value’s inferred type is compatible with expected.

pub fn types_compatible( actual: &TypeAnnotation, expected: &TypeAnnotation, ) -> bool

Returns true if actual and expected types are assignment-compatible.

Compatibility rules (beyond equality):

• Null is compatible with anything
• Byte widens to Int / CInt
• Arrays are compatible if their element types are compatible (recursive)

pub fn check_not_null(&self, value: &Value, span: Span) -> Result<(), Error>

Return an error if value is Value::Null, pointing at span.

pub fn evaluate(&mut self, id: ExprId) -> Result<Value, Error>

pub fn call_value( &mut self, func: Value, args: Vec<Value>, span: Span, ) -> Result<Value, Error>

Calls a Value::Function, setting up the captured environment, inserting arguments into a new scope, running the body, and validating the return type.

Global scope mutations made inside the call are propagated back to the caller.

pub fn call_path( &mut self, path: &[String], args: Vec<Value>, span: Span, ) -> Result<Value, Error>

Resolves a call path and dispatches to either a stdlib [NativeFn] or a user-defined function looked up via [fn_names].

Resolution order:

1. Full stdlib path via [root_module.resolve]
2. Single-name shorthand via [fn_names]
3. Error with “did you mean?” suggestion from stdlib keywords

impl Evaluator

pub fn slot_ref(&self, depth: usize, slot: usize) -> Option<&EnvironmentItem>

pub fn slot_mut( &mut self, depth: usize, slot: usize, ) -> Option<&mut EnvironmentItem>

pub fn index_read_value( &self, arr: &Value, idx: &Value, target_span: Span, index_span: Span, span: Span, ) -> Result<Value, Error>

Reads arr[idx] given already-evaluated arr/idx values. Used by the general (non-fast-path) Index evaluation, for arrays, tuples, and maps alike.

pub fn index_read( &self, depth: usize, slot: usize, indices: &[usize], span: Span, ) -> Result<Value, Error>

Reads a value by walking indices from the root (depth, slot), borrowing at every step and cloning only the single final element avoids cloning the whole container just to read one item out of it.

impl Evaluator

pub fn index_assign( &mut self, target: ExprId, index: ExprId, value: ExprId, span: Span, ) -> Result<Value, Error>

impl Evaluator

pub fn push_scope(&mut self)

Pushes a new empty scope frame onto the scope pool stack.

pub fn pop_scope(&mut self)

Pops the innermost scope frame.

fn ensure_slot( frame: &mut Vec<EnvironmentItem>, slot: usize, item: EnvironmentItem, )

pub fn get_value( &self, depth: usize, slot: usize, span: Span, ) -> Result<Value, Error>

Reads the value at (depth, slot) in the environment.

depth counts from the innermost frame outward (0 = current). depth >= environment.len() means the target is the global scope.

pub fn insert_value( &mut self, slot: usize, value: Value, type_annotation: TypeAnnotation, _: Span, ) -> Result<(), Error>

Inserts a mutable value at slot in the current (innermost) frame.

Grows the frame with Null placeholders if slot is past the end.

pub fn insert_global( &mut self, slot: usize, value: Value, type_annotation: TypeAnnotation, )

Inserts a mutable value at slot in the global scope.

Used for top-level dec declarations, which live in self.globals rather than the local environment stack.

pub fn insert_const( &mut self, slot: usize, value: Value, type_annotation: TypeAnnotation, span: Span, ) -> Result<(), Error>

Inserts an immutable (const) value at slot in the current frame.

Returns an error if the slot already holds a const.

pub fn insert_const_global( &mut self, slot: usize, value: Value, type_annotation: TypeAnnotation, span: Span, ) -> Result<(), Error>

Inserts an immutable (const) value at slot in the global scope.

Used for top-level const declarations. Returns an error if the slot already holds a const.

pub fn assign_value( &mut self, depth: usize, slot: usize, value: Value, value_type: TypeAnnotation, span: Span, ) -> Result<(), Error>

Overwrites the value at (depth, slot), enforcing type compatibility and immutability.

depth >= environment.len() means the target is the global scope.

pub fn get_value_raw(&self, name: &str) -> Option<Value>

Looks up a variable by name via the resolver - used only in tests.

pub fn get_declared_type( &self, depth: usize, slot: usize, ) -> Option<TypeAnnotation>

Returns the declared TypeAnnotation of the slot at (depth, slot), if it exists.

impl Evaluator

fn type_mismatch_binary( &self, op: &str, left: &Value, left_span: Span, right: &Value, right_span: Span, span: Span, ) -> Error

pub fn match_binary_operator( &mut self, left: Value, left_span: Span, right: Value, right_span: Span, operator: &TokenType, span: Span, ) -> Result<Value, Error>

impl Evaluator

pub fn evaluate_statement(&mut self, statement: &Statement) -> Result<(), Error>

Evaluates a single statement, mutating the environment and control-flow flags.

Loop control (break, continue) and function return (return) are signalled via is_breaking, is_continuing, and return_value flags on Evaluator rather than exceptions, so callers must check these flags after each statement.

fn evaluate_branch(&mut self, statement: &Statement) -> Result<bool, Error>

Evaluates a [ConditionalBranch] or [Conditional] and returns true if the branch was taken (condition was true or it was an else).

pub fn evaluate_program( &mut self, statements: &[Statement], ) -> Result<(), Error>

The top-level entry point for a full rl program.

If a function is annotated !#[entry] or named main, only declarations and imports are evaluated first, then that function is called with no arguments. If no entry point exists, all statements are evaluated top-to-bottom (script mode).

Returns an error if multiple !#[entry] functions are found.

pub fn evaluate_block(&mut self, statements: &[Statement]) -> Result<(), Error>

Evaluates a list of statements inside a fresh scope, used for inline blocks.

impl Evaluator

fn type_mismatch_unary( &self, op: &str, operand: &Value, operand_span: Span, span: Span, ) -> Error

pub fn match_unary_operator( &mut self, operand: Value, operand_span: Span, operator: &TokenType, span: Span, ) -> Result<Value, Error>

Trait Implementations

impl Default for Evaluator

fn default() -> Self

Returns the “default value” for a type.