Crate grift_eval 

Lisp Evaluator

A Lisp 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

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::simple_hash;

pub use native::MAX_NATIVE_FUNCTIONS;

Modules

native

Native Function Interop

Macros

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.

ErrorMessage

Fixed-size message buffer for no_std

EvalError

Evaluation error with context

Evaluator

Maximum number of macros that can be defined The Lisp evaluator with full trampolined TCO

GcStats

Statistics returned by garbage collection.

Lisp

A Lisp execution context wrapping an arena

ParseError

Parser error with location

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)

ErrorKind

Error kind enumeration

Num

Numeric value that can be either an integer or a float. Used internally for arithmetic operations with type promotion.

ParseErrorKind

StdLib

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

Value

A Lisp value

Traits

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