Crate grift_core 

Grift Core Types

Core types and Lisp context for the Grift R7RS-compliant Scheme implementation.

This crate contains the fundamental types shared between the parser and evaluator:

• Value — The core value enum representing all Lisp types
• Builtin — Enum of built-in functions
• StdLib — Enum of standard library functions
• Lisp — The Lisp execution context wrapping an arena

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)
• Pluggable I/O - The io module defines the IoProvider trait so the evaluator stays no_std while real I/O can be supplied on hosted platforms (see grift_std::StdIoProvider). A NullIoProvider is provided for environments without I/O.

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 io::IoProvider;

pub use io::NullIoProvider;

pub use io::PortId;

pub use io::IoErrorKind;

pub use io::IoResult;

pub use io::DisplayPort;

Modules

io

I/O trait boundary for the Grift Scheme evaluator.

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.

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

Enums

ArenaError

Errors that can occur during arena operations.

Builtin

Built-in functions (optimization to avoid symbol lookup)

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

Trace

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

Type Aliases

ArenaResult

Result type for arena operations.

fsize

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