Struct Interpreter 

pub struct Interpreter { /* private fields */ }

Runtime interpreter state.

The Interpreter manages the execution environment for Ruchy programs. It maintains:

• A value stack for computation
• Environment stack for lexical scoping
• Inline caches for field/method optimization
• Type feedback for future JIT compilation
• Conservative garbage collection

Implementation Strategy

This follows a two-tier execution model:

• Tier 0: AST interpretation (current)
• Tier 1: JIT compilation (future)

Type feedback and execution counts are collected for hot code identification and optimization.

Implementations

impl Interpreter

pub fn new() -> Self

Create a new interpreter instance.

Initializes the interpreter with:

• Pre-allocated stack for performance
• Global environment with builtin functions (max, min, floor, ceil, etc.)
• Type feedback collection for future JIT compilation
• Conservative garbage collector

Examples

use ruchy::runtime::interpreter::Interpreter;

let mut interpreter = Interpreter::new();
// Interpreter is ready to evaluate expressions

pub fn eval_expr(&mut self, expr: &Expr) -> Result<Value, InterpreterError>

Evaluate an AST expression directly.

This is the main entry point for interpreting Ruchy expressions. It walks the AST recursively, evaluating expressions and returning their values.

Examples

use ruchy::runtime::interpreter::Interpreter;
use ruchy::frontend::parser::Parser;

let mut interpreter = Interpreter::new();
let mut parser = Parser::new("42");
let expr = parser.parse().unwrap();
let result = interpreter.eval_expr(&expr).unwrap();
assert_eq!(result.to_string(), "42");

use ruchy::runtime::interpreter::Interpreter;
use ruchy::frontend::parser::Parser;

let mut interpreter = Interpreter::new();
let mut parser = Parser::new("2 + 3");
let expr = parser.parse().unwrap();
let result = interpreter.eval_expr(&expr).unwrap();
assert_eq!(result.to_string(), "5");

Errors

Returns an error when:

• Type error (e.g., adding string to number)
• Runtime error (e.g., undefined variable)
• Stack overflow/underflow
• Division by zero

pub fn current_env(&self) -> &HashMap<String, Value>

Get the current (innermost) environment

pub fn push(&mut self, value: Value) -> Result<(), InterpreterError>

Push value onto stack

Errors

Returns error if stack overflow occurs

pub fn pop(&mut self) -> Result<Value, InterpreterError>

Pop value from stack

Errors

Returns error if stack underflow occurs

pub fn peek(&self, depth: usize) -> Result<Value, InterpreterError>

Peek at top of stack without popping

Errors

Returns error if stack underflow occurs

pub fn binary_op(&mut self, op: BinaryOp) -> Result<(), InterpreterError>

Binary arithmetic operation with type checking

Errors

Returns error if stack underflow, type mismatch, or arithmetic error occurs

pub fn set_variable_string(&mut self, name: String, value: Value)

Set a variable in the current scope (public for try/catch)

pub fn push_scope(&mut self)

Scope management for pattern bindings

pub fn pop_scope(&mut self)

pub fn get_field_cached( &mut self, obj: &Value, field_name: &str, ) -> Result<Value, InterpreterError>

Access field with inline caching optimization

Errors

Returns error if field access fails

pub fn get_cache_stats(&self) -> HashMap<String, f64>

Get inline cache statistics for profiling

pub fn clear_caches(&mut self)

Clear all inline caches (for testing)

pub fn get_type_feedback_stats(&self) -> TypeFeedbackStats

Get type feedback statistics

pub fn get_specialization_candidates(&self) -> Vec<SpecializationCandidate>

Get specialization candidates for JIT compilation

pub fn clear_type_feedback(&mut self)

Clear type feedback data (for testing)

pub fn gc_track(&mut self, value: Value) -> usize

Track a value in the garbage collector

pub fn gc_collect(&mut self) -> GCStats

Force garbage collection

pub fn gc_stats(&self) -> GCStats

Get garbage collection statistics

pub fn gc_info(&self) -> GCInfo

Get detailed garbage collection information

pub fn gc_set_threshold(&mut self, threshold: usize)

Set garbage collection threshold

pub fn gc_set_auto_collect(&mut self, enabled: bool)

Enable or disable automatic garbage collection

pub fn gc_clear(&mut self)

Clear all GC-tracked objects (for testing)

pub fn gc_alloc_array(&mut self, elements: Vec<Value>) -> Value

Allocate a new array and track it in GC

pub fn gc_alloc_string(&mut self, content: String) -> Value

Allocate a new string and track it in GC

pub fn gc_alloc_closure( &mut self, params: Vec<String>, body: Arc<Expr>, env: Arc<HashMap<String, Value>>, ) -> Value

Allocate a new closure and track it in GC

pub fn get_global_bindings(&self) -> HashMap<String, Value>

Get all bindings from the global environment (for SharedSession state persistence)

pub fn set_global_binding(&mut self, name: String, value: Value)

Set a binding in the global environment (for SharedSession state restoration)

pub fn clear_user_variables(&mut self)

Clear all user variables from global environment, keeping only builtins

pub fn get_current_bindings(&self) -> HashMap<String, Value>

Get all bindings from the current environment (for SharedSession extraction)

pub fn eval_match( &mut self, expr: &Expr, arms: &[MatchArm], ) -> Result<Value, InterpreterError>

Evaluate a match expression

pub fn eval_method_call( &mut self, receiver: &Expr, method: &str, args: &[Expr], ) -> Result<Value, InterpreterError>

Evaluate a method call

pub fn push_error_scope(&mut self)

Push an error handling scope for try/catch blocks

Complexity

Cyclomatic complexity: 1

pub fn pop_error_scope(&mut self)

Pop an error handling scope

Complexity

Cyclomatic complexity: 1

pub fn set_variable(&mut self, name: &str, value: Value)

Set a variable in the current scope

Complexity

Cyclomatic complexity: 1

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

Get a variable from the environment stack

Searches the environment stack from innermost to outermost scope. Returns None if the variable is not found.

pub fn pattern_matches( &mut self, pattern: &Pattern, value: &Value, ) -> Result<bool, InterpreterError>

Pattern matching for try/catch

Complexity

Cyclomatic complexity: 8 (delegates to existing pattern matcher)

pub fn capture_stdout(&mut self, output: String)

Capture println output to stdout buffer Complexity: 1 (single operation)

Examples

use ruchy::runtime::interpreter::Interpreter;

let mut interpreter = Interpreter::new();
interpreter.capture_stdout("Hello, World!".to_string());
assert_eq!(interpreter.get_stdout(), "Hello, World!");

pub fn get_stdout(&self) -> String

Get captured stdout as a single string with newlines Complexity: 2 (join + conditional)

Examples

use ruchy::runtime::interpreter::Interpreter;

let mut interpreter = Interpreter::new();
interpreter.capture_stdout("Line 1".to_string());
interpreter.capture_stdout("Line 2".to_string());
assert_eq!(interpreter.get_stdout(), "Line 1\nLine 2");

pub fn clear_stdout(&mut self)

Clear stdout buffer Complexity: 1 (single operation)

Examples

use ruchy::runtime::interpreter::Interpreter;

let mut interpreter = Interpreter::new();
interpreter.capture_stdout("test".to_string());
interpreter.clear_stdout();
assert_eq!(interpreter.get_stdout(), "");

pub fn has_stdout(&self) -> bool

Check if stdout has any captured output Complexity: 1 (single check)

Trait Implementations

impl Debug for Interpreter

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Interpreter

fn default() -> Self

Returns the “default value” for a type.