Crate grift_eval 

Scheme Evaluator

An R7RS-compliant Scheme evaluator with fully trampolined evaluation - no Rust stack recursion, enabling unlimited recursion depth (bounded only by heap/arena size).

Key Features

• Full Trampolining: All evaluation uses continuation-passing style with an explicit continuation stack. No Rust recursion means no stack overflow.
• Strict Evaluation: Call-by-value semantics - all arguments are evaluated before function application
• Proper TCO: Tail calls reuse the same continuation frame
• Lexically Scoped Closures: First-class functions with captured environments
• Rich Error Handling: Error messages with stack traces
• Pattern Matching: case for value matching
• Iteration: do loops for imperative-style iteration
• Meta-programming: eval for runtime code evaluation, quasiquote/unquote
• Mutation: set!, set-car!, set-cdr! for imperative programming
• Pluggable I/O: Accepts any IoProvider at runtime for port operations (display, read, write, string ports, etc.) without breaking no_std compatibility
• Native FFI: Register Rust functions callable from Scheme via NativeRegistry and the FromLisp/ToLisp conversion traits

Evaluation Strategy

This evaluator uses strict (call-by-value) evaluation:

• All function arguments are fully evaluated before the function is called
• This provides predictable evaluation order and side-effect timing
• Tail call optimization is supported for constant-space recursion

Mutation

This Lisp supports mutation operations for imperative programming:

• set! - Mutate a variable binding
• set-car! - Mutate the car of a cons cell
• set-cdr! - Mutate the cdr of a cons cell

Note: Mutation breaks referential transparency but enables imperative patterns.

Truthiness

Only #f is false. Everything else (including the empty list '()) is truthy.

Special Forms

• quote - Return expression unevaluated
• if - Conditional
• cond - Multi-way conditional
• case - Pattern matching on values
• lambda - Create closure
• define - Define variable/function
• set! - Mutate variable binding
• let - Local binding
• let* - Sequential local binding
• begin - Sequence of expressions
• and / or - Short-circuit boolean operations
• do - Iteration with initialization and step expressions
• quasiquote - Template with unquote and unquote-splicing
• eval - Evaluate expression at runtime
• apply - Apply function to argument list
• values - Return multiple values as a list

Re-exports

pub use native::FromLisp;

pub use native::ToLisp;

pub use native::NativeRegistry;

pub use native::NativeEntry;

pub use native::NativeFn;

pub use native::extract_arg;

pub use native::args_empty;

pub use native::count_args;

pub use native::MAX_NATIVE_FUNCTIONS;

Modules

native

Native Function Interop

Macros

binary_div_op

Macro for binary division operations with zero check.

binary_int_cmp

Macro for binary numeric comparison (returns boolean).

binary_int_op

Macro for binary numeric arithmetic (returns number).

builtin_char_to_int

Macro for unary char-to-integer conversion.

builtin_char_transform

Macro for unary character transformation.

builtin_div_op

Macro for binary integer operations with division-by-zero check.

builtin_numeric_pred

Macro for numeric predicate builtins.

builtin_rounding_op

Macro for rounding operations.

builtin_unary_int

Macro for unary integer operations.

builtin_unary_num

Macro for unary numeric operations (supports both int and float).

builtin_unary_pred

Macro for unary predicate builtins.

extract_args

Macro to extract arguments from a Lisp list using car/cdr.

register_native

Register a native Rust function as a Lisp builtin with automatic argument extraction.

Structs

Arena

Fixed-size arena allocator with O(1) allocation.

ArenaIndex

Index into the arena.

ArgCountInfo

Compact argument count info (expected, got) packed into u32. Uses u16 for each count, supporting up to 65535 arguments.

DisplayPort

Write a Value through an IoProvider port.

DisplayValue

A wrapper that enables core::fmt::Display for Lisp values.

EnvRef

A typed wrapper around ArenaIndex representing an environment chain.

EvalError

Evaluation error with context - optimized for minimal size.

Evaluator

The Lisp evaluator with full trampolined TCO.

ExprRef

A typed wrapper around ArenaIndex representing an expression to evaluate.

GcStats

Statistics returned by garbage collection.

Lisp

A Lisp execution context wrapping an arena

NullIoProvider

A no-op I/O provider that silently discards all output and returns IoErrorKind::Unsupported for reads.

ParseError

Parser error with location

PortId

Identifies an I/O port.

SourceLoc

Source location for error reporting

StackFrame

A stack frame for error reporting

Enums

ArenaError

Errors that can occur during arena operations.

Builtin

Built-in functions (optimization to avoid symbol lookup)

ContType

Continuation types for the arena-based trampoline.

ErrorKind

Error kind enumeration

IoErrorKind

Error kinds for I/O operations in no_std environments.

ParseErrorKind

StdLib

Standard library functions (stored in static memory, not arena)

TrampolineState

Trampoline state - what we’re currently doing

Value

A Lisp value

Traits

GcRoots

Trait for types that contain GC roots.

IoProvider

Trait for providing I/O operations to the evaluator.

Trace

Trait for types that can be traced by the garbage collector.

Functions

parse

Parse a string into a Lisp expression

Type Aliases

ArenaResult

Result type for arena operations.

EvalResult

Result type for evaluation

IoResult

Result type for I/O operations.

OutputCallback

Function pointer type for output callbacks

fsize

Platform-dependent floating-point type, matching the width of isize/usize.