Crate grift_parser 

Scheme Parser

An R7RS-compliant Scheme parser with arena-allocated values.

Design

• Symbols use contiguous string storage for memory efficiency
• Symbol interning ensures the same symbol name returns the same index
• All values are stored in a grift_arena arena
• Supports garbage collection via the Trace trait
• Explicit boolean values (#t, #f) separate from nil/empty list
• Strict evaluation - All arguments are evaluated before function application (call-by-value)

Core Types

Core types (Value, Builtin, StdLib, Lisp) are defined in the grift_core crate and re-exported here for backward compatibility.

Value Representation

• Nil - The empty list (NOT false!)
• True - Boolean true (#t)
• False - Boolean false (#f)
• Number(isize) - Integer numbers
• Char(char) - Single character
• Cons { car, cdr } - Pair/list cell with inline indices
• Symbol(ArenaIndex) - Symbol pointing to interned string
• Lambda { params, body_env } - Closure with inline indices
• Builtin(Builtin) - Optimized built-in function
• StdLib(StdLib) - Standard library function (static code, parsed on-demand)
• Array { len, data } - Vector with inline length
• String { len, data } - String with inline length
• Native { id } - Native Rust function reference

Reserved Slots

The Lisp singleton values (nil, true, false) are pre-allocated in reserved slots at initialization time.

The first 4 slots of the arena are reserved:

• Slot 0: Value::Nil - empty list singleton
• Slot 1: Value::True - boolean true singleton
• Slot 2: Value::False - boolean false singleton
• Slot 3: Value::Cons - intern table reference cell

Pitfalls and Gotchas

Truthiness

• Only #f is false! Everything else is truthy, including:
  • nil / '() (the empty list)
  • 0 (the number zero)
  • Empty strings

Garbage Collection

• The intern table is always a GC root - interned symbols are never collected
• Reserved slots (nil, true, false) are implicitly preserved
• Run gc() with appropriate roots to reclaim memory

StdLib Functions

• Body is parsed on each call (minor overhead, but keeps code out of arena)
• Recursive stdlib functions work via the global environment
• Errors in static source strings are only caught at runtime

Re-exports

pub use lexer::Lexer;

pub use lexer::Token;

pub use lexer::SpannedToken;

pub use lexer::LexError;

pub use lexer::LexErrorKind;

pub use parser::SourceLoc;

Modules

lexer

Lexer/Tokenizer for Lisp expressions

libraries

Embedded R7RS standard library source registry.

Macros

define_builtins

Macro for defining built-in functions.

define_stdlib

Macro for defining standard library functions.

Structs

Arena

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

ArenaIndex

Index into the arena.

DisplayPort

Write a Value through an IoProvider port.

DisplayValue

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

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

Parser

Parser state — wraps a Lexer and builds arena-allocated AST nodes.

PortId

Identifies an I/O port.

Enums

ArenaError

Errors that can occur during arena operations.

Builtin

Built-in functions (optimization to avoid symbol lookup)

IoErrorKind

Error kinds for I/O operations in no_std environments.

ParseErrorKind

StdLib

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

Value

A Lisp value

Constants

PRELUDE_SOURCE

The combined prelude source containing all macro and function definitions.

RESERVED_SLOTS

Number of reserved slots in the arena:

Traits

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

parse_all

Parse multiple expressions

Type Aliases

ArenaResult

Result type for arena operations.

IoResult

Result type for I/O operations.

fsize

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