Crate grift_parser 

Lisp Parser

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

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, name_hash } - 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

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.

GcStats

Statistics returned by garbage collection.

Lisp

A Lisp execution context wrapping an arena

ParseError

Parser error with location

Parser

Parser state

SourceLoc

Source location for error reporting

Enums

ArenaError

Errors that can occur during arena operations.

Builtin

Built-in functions (optimization to avoid symbol lookup)

ParseErrorKind

StdLib

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

Value

A Lisp value

Constants

RESERVED_SLOTS

Number of reserved slots in the arena:

Traits

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.