Struct Interpreter 

pub struct Interpreter {

    pub global_env: Environment,
    pub(crate) stdout: RefCell<Box<dyn Write>>,
    pub(crate) stderr: RefCell<Box<dyn Write>>,
    color_stderr: bool,
    s3_dispatch_stack: RefCell<Vec<S3DispatchContext>>,
    call_stack: RefCell<Vec<CallFrame>>,
    pub(crate) last_traceback: RefCell<Vec<TraceEntry>>,
    pub(crate) source_stack: RefCell<Vec<(String, String)>>,
    traceback_generation: Cell<u64>,
    traceback_captured_generation: Cell<u64>,
    pub(crate) pending_native_backtrace: RefCell<Option<NativeBacktrace>>,
    pub(crate) condition_handlers: RefCell<Vec<Vec<ConditionHandler>>>,
    rng: RefCell<InterpreterRng>,
    pub(crate) rng_kind: Cell<RngKind>,
    pub(crate) temp_dir: TempDir,
    pub(crate) temp_counter: Cell<u64>,
    pub(crate) env_vars: RefCell<HashMap<String, String>>,
    pub(crate) working_dir: RefCell<PathBuf>,
    pub(crate) start_instant: Instant,
    pub(crate) collections: RefCell<Vec<CollectionObject>>,
    pub(crate) connections: RefCell<Vec<ConnectionInfo>>,
    pub(crate) tcp_streams: RefCell<HashMap<usize, TcpStream>>,
    pub(crate) url_bodies: RefCell<HashMap<usize, Vec<u8>>>,
    pub(crate) finalizers: RefCell<Vec<RValue>>,
    interrupted: Arc<AtomicBool>,
    pub(crate) options: RefCell<HashMap<String, RValue>>,
    pub(crate) rd_help_index: RefCell<RdHelpIndex>,
    pub(crate) last_value_invisible: Cell<bool>,
    eval_depth: Cell<usize>,
    max_eval_depth: usize,
    stack_base: usize,
    pub(crate) s4_classes: RefCell<HashMap<String, S4ClassDef>>,
    pub(crate) s4_generics: RefCell<HashMap<String, S4GenericDef>>,
    pub(crate) s4_methods: RefCell<HashMap<(String, Vec<String>), RValue>>,
    pub(crate) loaded_namespaces: RefCell<HashMap<String, LoadedNamespace>>,
    pub(crate) search_path: RefCell<Vec<SearchPathEntry>>,
    pub(crate) s3_method_registry: RefCell<HashMap<(String, String), RValue>>,
    pub(crate) progress_bars: RefCell<Vec<Option<ProgressBarState>>>,
    pub(crate) par_state: RefCell<ParState>,
    pub(crate) grid_display_list: RefCell<Vec<RValue>>,
    pub(crate) grid_viewport_stack: RefCell<Vec<RValue>>,
    pub(crate) grid_grob_store: RefCell<GrobStore>,
    pub(crate) grid_rust_display_list: RefCell<DisplayList>,
    pub(crate) grid_rust_viewport_stack: RefCell<ViewportStack>,
    pub(crate) color_palette: RefCell<Vec<RColor>>,
    pub(crate) current_plot: RefCell<Option<PlotState>>,
    pub(crate) file_device: RefCell<Option<FileDevice>>,
    pub(crate) loaded_dlls: RefCell<Vec<LoadedDll>>,
}

Fields

global_env: Environment

stdout: RefCell<Box<dyn Write>>

Per-interpreter stdout writer. Defaults to std::io::stdout(). Use Vec<u8> for captured/embedded output.

stderr: RefCell<Box<dyn Write>>

Per-interpreter stderr writer. Defaults to std::io::stderr().

color_stderr: bool

Whether to emit colored diagnostics to stderr. True when stderr is a real terminal and the color feature is enabled; false for captured output sessions or when the feature is off.

s3_dispatch_stack: RefCell<Vec<S3DispatchContext>>

call_stack: RefCell<Vec<CallFrame>>

last_traceback: RefCell<Vec<TraceEntry>>

Snapshot of the call stack at the point the last error occurred. Populated by call_closure/call_closure_lazy when an error propagates, cleared at the start of each top-level eval().

source_stack: RefCell<Vec<(String, String)>>

Stack of source contexts for file:line resolution in tracebacks. Pushed by source() / eval_file(), popped when done. Each entry is (filename, source_text) — byte offsets in Span resolve against source_text.

traceback_generation: Cell<u64>

Generation counter for traceback capture. Incremented at each top-level eval() so we can distinguish “same error propagating up” from “new error in a subsequent eval”.

traceback_captured_generation: Cell<u64>

The generation at which last_traceback was captured.

pending_native_backtrace: RefCell<Option<NativeBacktrace>>

Native backtrace from the most recent .Call/.C error (Rf_error in C code). Set by dot_call/dot_c on error, consumed by capture_traceback().

condition_handlers: RefCell<Vec<Vec<ConditionHandler>>>

Stack of handler sets from withCallingHandlers() calls.

rng: RefCell<InterpreterRng>

Per-interpreter RNG state. Defaults to SmallRng (Xoshiro256++) for speed; can be switched to ChaCha20Rng via RNGkind("ChaCha20") for cross-platform deterministic reproducibility.

Parallel RNG considerations

The RNG is behind RefCell on the single-threaded Interpreter, so there are no data races. If we ever add rayon-based parallel operations, each worker thread must get its own RNG seeded deterministically from the parent to avoid contention and ensure reproducibility.

rng_kind: Cell<RngKind>

Which RNG algorithm is currently selected.

temp_dir: TempDir

Session-scoped temporary directory, auto-cleaned on drop.

temp_counter: Cell<u64>

Counter for unique tempfile names within the session.

env_vars: RefCell<HashMap<String, String>>

Per-interpreter environment variables, snapshotted at interpreter creation and then mutated locally via Sys.setenv().

working_dir: RefCell<PathBuf>

Per-interpreter working directory, snapshotted at interpreter creation and then mutated locally via setwd().

start_instant: Instant

Instant when the interpreter was created, used by proc.time() for elapsed time.

collections: RefCell<Vec<CollectionObject>>

Collection objects (HashMap, BTreeMap, HashSet, BinaryHeap, VecDeque). Each collection is addressed by its index in this Vec.

connections: RefCell<Vec<ConnectionInfo>>

Connection table — slots 0-2 are stdin/stdout/stderr, lazily initialised.

tcp_streams: RefCell<HashMap<usize, TcpStream>>

TCP stream handles, keyed by connection ID. Stored separately from ConnectionInfo because TcpStream is not Clone.

url_bodies: RefCell<HashMap<usize, Vec<u8>>>

Buffered response bodies for URL connections, keyed by connection ID. URL connections eagerly fetch the entire HTTP response body, which is stored here for subsequent readLines() calls.

finalizers: RefCell<Vec<RValue>>

Finalizers registered with reg.finalizer(onexit = TRUE), run when the interpreter is dropped.

interrupted: Arc<AtomicBool>

Flag set by the SIGINT handler; checked at loop boundaries to interrupt long-running computations without killing the process.

options: RefCell<HashMap<String, RValue>>

Per-interpreter R options (accessed via options() and getOption()).

rd_help_index: RefCell<RdHelpIndex>

Rd documentation help index for package man/ directories.

last_value_invisible: Cell<bool>

Visibility flag — set to true by invisible() to suppress auto-printing

eval_depth: Cell<usize>

Recursion depth counter — prevents stack overflow on deeply nested expressions.

max_eval_depth: usize

Maximum eval depth for this interpreter, computed from the creating thread’s stack size. Different threads may have different stack sizes, so this adapts.

stack_base: usize

Stack pointer at interpreter creation — used to estimate remaining stack.

s4_classes: RefCell<HashMap<String, S4ClassDef>>

S4 class registry: class name -> class definition.

s4_generics: RefCell<HashMap<String, S4GenericDef>>

S4 generic registry: generic name -> generic definition.

s4_methods: RefCell<HashMap<(String, Vec<String>), RValue>>

S4 method dispatch table: (generic, signature) -> method function.

loaded_namespaces: RefCell<HashMap<String, LoadedNamespace>>

Loaded package namespaces, keyed by package name.

search_path: RefCell<Vec<SearchPathEntry>>

Search path entries (between .GlobalEnv and package:base).

s3_method_registry: RefCell<HashMap<(String, String), RValue>>

S3 method registry for methods declared via S3method() in NAMESPACE files. Key is (generic, class), value is the method function. Checked by dispatch_s3 after the environment chain lookup fails.

progress_bars: RefCell<Vec<Option<ProgressBarState>>>

Active progress bars, keyed by integer ID.

par_state: RefCell<ParState>

Graphics parameters (par state) — per-interpreter, not global.

grid_display_list: RefCell<Vec<RValue>>

Grid graphics display list — records grob objects drawn on the page (R-level).

grid_viewport_stack: RefCell<Vec<RValue>>

Grid viewport stack — tracks pushed viewports for grid graphics (R-level).

grid_grob_store: RefCell<GrobStore>

Grid grob store — stores Rust-level grobs indexed by GrobId for rendering.

grid_rust_display_list: RefCell<DisplayList>

Grid Rust-level display list — records viewport pushes/pops and grob draws for replay.

grid_rust_viewport_stack: RefCell<ViewportStack>

Grid Rust-level viewport stack — tracks pushed viewports for rendering.

color_palette: RefCell<Vec<RColor>>

Color palette for indexed color access (e.g. col=1 means palette[0]).

current_plot: RefCell<Option<PlotState>>

Current plot being accumulated (for egui_plot rendering).

file_device: RefCell<Option<FileDevice>>

Active file device (SVG/PNG/PDF) — when set, dev.off() writes to file.

loaded_dlls: RefCell<Vec<LoadedDll>>

Loaded native shared libraries (dyn.load).

Implementations

impl Interpreter

pub(crate) fn bind_closure_call( &self, params: &[Param], positional: &[RValue], named: &[(String, RValue)], closure_env: &Environment, function: &RValue, call: Option<Expr>, ) -> Result<BoundClosureCall, RFlow>

impl Interpreter

pub(super) fn eval_assign( &self, op: &AssignOp, target: &Expr, val: RValue, env: &Environment, ) -> Result<RValue, RFlow>

impl Interpreter

pub(crate) fn add_collection(&self, obj: CollectionObject) -> usize

Allocate a new collection, returning its integer ID.

impl Interpreter

pub(crate) fn ensure_connections(&self)

Ensure the connections table is initialised with the three standard streams. Called lazily on first access.

pub(crate) fn add_connection(&self, info: ConnectionInfo) -> usize

Allocate a new connection slot, returning its integer ID.

pub(crate) fn get_connection(&self, id: usize) -> Option<ConnectionInfo>

Get a clone of the connection info at id, or None if out of range.

pub(crate) fn with_connection_mut<F>( &self, id: usize, f: F, ) -> Result<(), RError>

where F: FnOnce(&mut ConnectionInfo),

Mutate a connection in place. Returns an error if the ID is invalid.

pub(crate) fn store_tcp_stream(&self, id: usize, stream: TcpStream)

Store a TCP stream for the given connection ID.

pub(crate) fn take_tcp_stream(&self, id: usize) -> Option<TcpStream>

Remove and return a TCP stream for the given connection ID, if present.

pub(crate) fn with_tcp_stream<F, T>(&self, id: usize, f: F) -> Result<T, RError>

where F: FnOnce(&mut TcpStream) -> Result<T, RError>,

Execute a closure with mutable access to the TCP stream for id. Returns an error if no TCP stream exists for that connection.

pub(crate) fn store_url_body(&self, id: usize, body: Vec<u8>)

Store a fetched URL response body for the given connection ID.

pub(crate) fn take_url_body(&self, id: usize) -> Option<Vec<u8>>

Take (remove) the URL response body for the given connection ID.

pub(crate) fn get_url_body(&self, id: usize) -> Option<Vec<u8>>

Get a clone of the URL response body for the given connection ID.

impl Interpreter

pub(crate) fn add_progress_bar(&self, state: ProgressBarState) -> usize

Allocate a new progress bar, returning its integer ID.

pub(crate) fn close_progress_bar(&self, id: usize) -> bool

Finish and remove a progress bar by ID. Returns true if the bar existed and was removed.

impl Interpreter

pub(crate) fn current_call_frame(&self) -> Option<CallFrame>

pub(crate) fn call_frame(&self, which: usize) -> Option<CallFrame>

pub(crate) fn call_frames(&self) -> Vec<CallFrame>

pub(crate) fn current_call_expr(&self) -> Option<Expr>

pub(crate) fn capture_traceback(&self)

Snapshot the current call stack into last_traceback.

Within the same top-level eval() (same generation), only the deepest trace is kept (the first capture wins as the error bubbles up and frames are popped). Across different evals, a new error always replaces the old traceback, matching R’s traceback() behavior.

pub fn format_traceback(&self) -> Option<String>

Format the last traceback for display, R-style (deepest frame first). Returns None if there is no traceback.

impl Interpreter

pub(super) fn eval_call( &self, func: &Expr, args: &[Arg], span: Option<Span>, env: &Environment, ) -> Result<RValue, RFlow>

pub fn call_function( &self, func: &RValue, positional: &[RValue], named: &[(String, RValue)], env: &Environment, ) -> Result<RValue, RFlow>

pub(crate) fn call_function_with_call( &self, func: &RValue, positional: &[RValue], named: &[(String, RValue)], env: &Environment, call_expr: Option<Expr>, ) -> Result<RValue, RFlow>

impl Interpreter

pub(super) fn eval_pipe( &self, lhs: &Expr, rhs: &Expr, env: &Environment, ) -> Result<RValue, RFlow>

pub(super) fn eval_if( &self, condition: &Expr, then_body: &Expr, else_body: Option<&Expr>, env: &Environment, ) -> Result<RValue, RFlow>

pub(super) fn eval_while( &self, condition: &Expr, body: &Expr, env: &Environment, ) -> Result<RValue, RFlow>

pub(super) fn eval_repeat( &self, body: &Expr, env: &Environment, ) -> Result<RValue, RFlow>

pub(super) fn eval_ns_get( &self, namespace: &Expr, name: &str, env: &Environment, ) -> Result<RValue, RFlow>

pub(super) fn eval_for( &self, var: &str, iter_val: &RValue, body: &Expr, env: &Environment, ) -> Result<RValue, RFlow>

impl Interpreter

pub(super) fn eval_index( &self, object: &Expr, indices: &[Arg], env: &Environment, ) -> Result<RValue, RFlow>

pub(crate) fn index_by_integer( &self, v: &Vector, indices: &[Option<i64>], ) -> Result<RValue, RFlow>

pub(super) fn eval_index_double( &self, object: &Expr, indices: &[Arg], env: &Environment, ) -> Result<RValue, RFlow>

pub(super) fn eval_dollar( &self, object: &Expr, member: &str, env: &Environment, ) -> Result<RValue, RFlow>

impl Interpreter

pub(crate) fn dyn_load(&self, path: &Path) -> Result<String, RError>

Load a shared library and register it. Returns the DLL name.

pub(crate) fn dyn_unload(&self, name: &str) -> Result<(), RError>

Unload a shared library by name.

pub(crate) fn is_symbol_loaded(&self, name: &str) -> bool

Check if a symbol is loaded in any DLL.

fn find_native_symbol_with_dll( &self, name: &str, ) -> Result<(*const (), usize), RError>

Look up a symbol across all loaded DLLs. Returns the function pointer and the index of the DLL that contains it.

pub(crate) fn find_native_symbol(&self, name: &str) -> Result<*const (), RError>

Look up a symbol across all loaded DLLs. Returns the function pointer.

fn find_c_symbol(&self, name: &str) -> Result<*const (), RError>

Look up a .C symbol across all loaded DLLs — checks registered .C methods first.

pub(crate) fn dot_call( &self, symbol_name: &str, args: &[RValue], ) -> Result<RValue, RError>

Execute a .Call() invocation using the C trampoline for error safety.

Flow:

1. Convert RValue args → SEXP (using C allocator)
2. Look up the native function symbol
3. Look up the C trampoline _minir_call_protected in the same DLL
4. Call the trampoline (which does setjmp + dispatch)
5. If the C function called Rf_error(), the trampoline returns 1 and we convert the error message to an RError
6. Convert the result SEXP → RValue
7. Free all C-side allocations via _minir_free_allocs
8. Free Rust-side input SEXPs

pub(crate) fn dot_external( &self, symbol_name: &str, args: &[RValue], ) -> Result<RValue, RError>

Execute a .External() invocation.

.External() passes a single SEXP pairlist to the C function. The pairlist’s first CAR is the function symbol; CDR is the argument chain.

pub(crate) fn dot_c( &self, symbol_name: &str, args: &[RValue], arg_names: &[Option<String>], ) -> Result<RValue, RError>

Execute a .C() invocation using the C trampoline for error safety.

.C() is simpler than .Call() — it passes pointers to raw data buffers directly to C functions. The C function receives double*, int*, char**, etc. and modifies them in place. After the call, the modified buffers are read back into R values.

Flow:

1. Convert each RValue arg to a C-compatible buffer
2. Look up the native function symbol
3. Call the trampoline with void* pointers
4. Read back modified buffers into R values
5. Return a named list of the (possibly modified) arguments

pub(crate) fn find_include_dir(&self) -> Option<PathBuf>

Find miniR’s include/ directory containing Rinternals.h.

Search order:

1. MINIR_INCLUDE environment variable
2. <exe_dir>/../include (installed layout)
3. <working_dir>/include (development layout)

pub(crate) fn load_package_native_code( &self, pkg_name: &str, pkg_dir: &Path, dyn_libs: &[DynLibDirective], ) -> Result<(), RError>

Load native code for a package based on its useDynLib directives.

For each useDynLib directive in the NAMESPACE:

1. Look for a pre-compiled .so/.dylib in <pkg_dir>/libs/
2. If not found, compile <pkg_dir>/src/*.c on demand
3. Load the shared library via dyn_load

fn resolve_linking_to_includes(&self, pkg_dir: &Path) -> Vec<PathBuf>

Resolve include paths for LinkingTo dependencies.

Reads the package’s DESCRIPTION, finds LinkingTo packages, and returns their inst/include directories (or include/ at package root).

impl Interpreter

pub(super) fn eval_unary( &self, op: UnaryOp, val: &RValue, ) -> Result<RValue, RFlow>

pub(super) fn eval_binary( &self, op: BinaryOp, left: &RValue, right: &RValue, env: &Environment, ) -> Result<RValue, RFlow>

fn try_s3_binary_dispatch( &self, op_name: &str, left: &RValue, right: &RValue, env: &Environment, ) -> Result<Option<RValue>, RFlow>

Try S3 dispatch for a binary operator on either operand’s class. Returns Ok(Some(result)) if a method was found, Ok(None) otherwise.

impl Interpreter

pub(crate) fn find_package_dir(&self, pkg_name: &str) -> Option<PathBuf>

Find a package directory by name, searching .libPaths().

Returns the path to the package directory (e.g. /path/to/lib/myPkg/) if found, or None if the package is not installed in any library path.

pub(crate) fn get_lib_paths(&self) -> Vec<String>

Get the library search paths (same logic as .libPaths() builtin).

Builds the search path from (in order):

1. R_LIBS environment variable (colon-separated on Unix, semicolon on Windows)
2. R_LIBS_USER environment variable
3. The default miniR library directory (<data_dir>/miniR/library)

pub(crate) fn default_library_path(&self) -> String

Return the default miniR library directory path.

Uses dirs::data_dir() when available (feature-gated), otherwise falls back to $HOME/.miniR/library.

fn fallback_data_dir(&self) -> String

Fallback data directory when dirs crate is not available.

pub(crate) fn is_base_package(name: &str) -> bool

Load a package namespace without attaching it to the search path.

This is the core of loadNamespace(). It:

1. Finds the package on .libPaths()
2. Parses DESCRIPTION and NAMESPACE
3. Creates a namespace environment
4. Sources R files
5. Builds exports
6. Registers S3 methods
7. Calls .onLoad()

Returns the namespace environment. R’s base packages are built into miniR — they don’t exist as installable directories. library(base), library(stats), etc. should be no-ops.

pub(crate) fn load_namespace( &self, pkg_name: &str, ) -> Result<Environment, RError>

fn load_namespace_from_dir( &self, pkg_name: &str, pkg_dir: &Path, ) -> Result<Environment, RError>

Load a namespace from a specific directory.

pub(crate) fn base_env(&self) -> Environment

Get the base environment (root of the environment chain).

fn populate_imports( &self, namespace: &PackageNamespace, namespace_env: &Environment, ) -> Result<(), RError>

Populate the namespace environment with imports from other packages.

fn source_r_directory( &self, r_dir: &Path, env: &Environment, collate: Option<&str>, ) -> Result<(), RError>

Source all .R files from a directory into an environment.

If collate is provided (from the DESCRIPTION Collate field), files listed there are sourced first in that exact order. Any files in the directory not mentioned in the Collate list are sourced afterwards in alphabetical order (C locale). If collate is None, all R/S files are sourced alphabetically (the default).

fn source_file_into(&self, path: &Path, env: &Environment) -> Result<(), RError>

Source a single R file into an environment.

fn build_exports( &self, namespace: &PackageNamespace, namespace_env: &Environment, exports_env: &Environment, )

Build the exports environment from namespace directives.

fn register_s3_methods( &self, namespace: &PackageNamespace, namespace_env: &Environment, )

Register S3 methods declared in NAMESPACE into the per-interpreter S3 method registry so they’re discoverable by S3 dispatch.

pub(crate) fn attach_package(&self, pkg_name: &str) -> Result<(), RError>

Attach a loaded package to the search path.

Inserts the package’s exports environment right after .GlobalEnv in the environment parent chain, and adds it to the search path list.

pub(crate) fn detach_package(&self, entry_name: &str) -> Result<(), RError>

Detach a package from the search path by name (e.g. “package:dplyr”).

pub(crate) fn get_search_path(&self) -> Vec<String>

Get the search path as a vector of names.

impl Interpreter

pub(crate) fn dispatch_next_method( &self, positional: &[RValue], named: &[(String, RValue)], env: &Environment, ) -> Result<RValue, RFlow>

pub(crate) fn eval_use_method( &self, args: &[Arg], env: &Environment, ) -> Result<RValue, RFlow>

fn eval_generic_name( &self, generic_expr: &Expr, env: &Environment, ) -> Result<String, RFlow>

fn default_use_method_object( &self, frame: &CallFrame, ) -> Result<Option<RValue>, RFlow>

fn dispatch_s3( &self, generic: &str, positional: &[RValue], named: &[(String, RValue)], dispatch_object: Option<RValue>, env: &Environment, call_expr: Option<Expr>, ) -> Result<RValue, RFlow>

S3 method dispatch: look up generic.class in the environment chain, then fall back to the per-interpreter S3 method registry (populated by S3method() directives in NAMESPACE files).

pub(crate) fn s3_classes_for(&self, dispatch_object: &RValue) -> Vec<String>

fn call_s3_method(&self, dispatch: S3MethodCall<'_>) -> Result<RValue, RFlow>

impl Interpreter

const DEFAULT_STACK_SIZE: usize

Maximum evaluation recursion depth before returning an error. Stack reserved for non-eval overhead: main thread setup, native code compilation (cc crate spawns compiler processes but builds argument vectors on the stack), C trampoline, signal handlers, and serde deserialization for sysdata.rda. Default stack size assumed when we can’t query the actual thread stack.

const STACK_RESERVED_BYTES: usize

fn ensure_builtin_min_arity( name: &str, min_args: usize, actual_args: usize, ) -> Result<(), RError>

fn ensure_builtin_max_arity( name: &str, max_args: Option<usize>, actual_args: usize, ) -> Result<(), RError>

pub fn new() -> Self

pub fn index_package_help(&self, package_name: &str, man_dir: &Path)

Index all .Rd files in a package’s man/ directory for help() lookup.

pub(crate) fn set_invisible(&self)

Mark the current result as invisible (suppresses auto-printing).

pub(crate) fn take_invisible(&self) -> bool

Check and consume the invisible flag. Returns true if the last value was marked invisible. The flag is reset after reading.

pub fn interrupt_flag(&self) -> Arc<AtomicBool>

Return a clone of the interrupt flag so the SIGINT handler can set it.

pub(crate) fn check_interrupt(&self) -> Result<(), RFlow>

Check the interrupt flag; if set, clear it and return an interrupt error.

pub(crate) fn signal_condition( &self, condition: &RValue, env: &Environment, ) -> Result<bool, RError>

Signal a condition to withCallingHandlers handlers (non-unwinding). Returns Ok(true) if muffled, Ok(false) if not handled, or Err if a handler raised an unwinding condition (e.g. tryCatch’s unwind handler).

fn default_options() -> HashMap<String, RValue>

Default R options, matching GNU R defaults where sensible.

pub(crate) fn rng(&self) -> &RefCell<InterpreterRng>

pub(crate) fn get_env_var(&self, name: &str) -> Option<String>

Get an environment variable from the interpreter-local snapshot.

pub(crate) fn env_vars_snapshot(&self) -> HashMap<String, String>

Return a clone of the interpreter-local environment snapshot.

pub(crate) fn set_env_var(&self, name: String, value: String)

Set a per-interpreter environment variable (does not mutate process state).

pub(crate) fn remove_env_var(&self, name: &str)

Remove a per-interpreter environment variable (does not mutate process state).

pub(crate) fn register_s3_method( &self, generic: String, class: String, method: RValue, )

Register an S3 method in the per-interpreter registry. This is used by NAMESPACE S3method() directives to make methods discoverable by S3 dispatch without polluting the base environment.

pub(crate) fn lookup_s3_method( &self, generic: &str, class: &str, ) -> Option<RValue>

Look up an S3 method from the per-interpreter registry. Returns the method function if one was registered for the given generic/class combination.

pub(crate) fn get_working_dir(&self) -> PathBuf

Get the interpreter-local working directory.

pub(crate) fn set_working_dir(&self, path: PathBuf)

Set the per-interpreter working directory (does not mutate process state).

pub(crate) fn resolve_path(&self, path: impl AsRef<Path>) -> PathBuf

Resolve a user-supplied path against the interpreter-local working directory.

pub(crate) fn write_stdout(&self, msg: &str)

Write a message to the interpreter’s stdout writer.

pub(crate) fn write_stderr(&self, msg: &str)

Write a message to the interpreter’s stderr writer.

pub fn color_stderr(&self) -> bool

Whether colored stderr output is enabled for this interpreter.

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

Enable or disable colored stderr output.

pub(crate) fn write_stderr_colored(&self, msg: &str, style: DiagnosticStyle)

Write a colored diagnostic message to the interpreter’s stderr writer.

When the color feature is enabled and color_stderr is true, the message is written with the appropriate ANSI color. Otherwise, the message is written as plain text.

fn try_write_colored(&self, msg: &str, style: DiagnosticStyle) -> bool

Attempt to write colored text. Returns true if color was applied, false if the caller should fall back to plain text.

pub fn force_value(&self, value: RValue) -> Result<RValue, RFlow>

Force a value: if it’s a Promise, evaluate the promise expression and cache the result. Returns the concrete (non-promise) value.

Non-promise values pass through unchanged. This is the main entry point for transparent promise forcing throughout the interpreter.

pub fn force_args( &self, positional: &[RValue], named: &[(String, RValue)], ) -> Result<(Vec<RValue>, Vec<(String, RValue)>), RFlow>

Force all promises in a slice of values, returning concrete values. Used at builtin dispatch boundaries.

pub fn eval(&self, expr: &Expr) -> Result<RValue, RFlow>

fn stack_bytes_per_eval_frame() -> usize

Compute the per-frame stack cost from actual type sizes.

Each eval recursion goes through: eval_in → eval_in_inner → (match arms with RValue/Expr temps) → call_function → eval_in (next level)

The dominant cost is the Expr match in eval_in_inner (holds RValue temporaries) and call_function (holds CallFrame + argument vectors). We use size_of for the key types and add overhead for locals, return values, and alignment padding.

fn compute_max_eval_depth() -> usize

Compute the max eval depth from the available stack budget.

fn current_stack_addr() -> usize

Get the approximate current stack address (for stack usage estimation).

fn stack_is_low(&self) -> bool

Check if we’re running low on stack space (within STACK_RESERVED_BYTES of the estimated stack limit). This catches recursion that bypasses the eval_depth counter (e.g. Rust-level recursion in the loader).

pub fn eval_in(&self, expr: &Expr, env: &Environment) -> Result<RValue, RFlow>

fn eval_in_inner(&self, expr: &Expr, env: &Environment) -> Result<RValue, RFlow>

Trait Implementations

impl Default for Interpreter

fn default() -> Self

Returns the “default value” for a type.

impl Drop for Interpreter

fn drop(&mut self)

Executes the destructor for this type.