Crate grift 

Grift

A minimal no_std, no_alloc R7RS-compliant Scheme implementation built on arena-based garbage collection. Perfect for embedded systems, WebAssembly, or any environment where heap allocation is unavailable or undesirable.

Features

• no_std, no_alloc by default — Runs on bare metal
• Arena-based allocation — Fixed memory footprint, no heap
• Mark-and-sweep GC — Controllable from Scheme code
• Proper tail-call optimization — Via trampolining
• Lexical closures — First-class functions with captured environments
• R7RS-compliant — Scheme semantics following the Revised⁷ Report
• Pluggable I/O — Trait-based I/O boundary (IoProvider) keeps the evaluator no_std while allowing real I/O on hosted platforms
• Native FFI — Register Rust functions callable from Scheme
• Embedded support — Optional hardware natives for GPIO, memory peek/poke, and bit manipulation

Quick Start

use grift::{Lisp, Evaluator, Value};

// Create a Lisp interpreter with a 20,000-cell arena
let lisp: Lisp<20000> = Lisp::new();
let mut eval = Evaluator::new(&lisp).unwrap();

// Evaluate expressions
let result = eval.eval_str("(+ 1 2 3)").unwrap();
assert!(matches!(lisp.get(result), Ok(Value::Number(6))));

Optional std Feature

Enable the std feature for an interactive REPL and real I/O:

[dependencies]
grift = { version = "1.3", features = ["std"] }

The std feature brings in:

• grift_repl — Interactive REPL with line editing, GC commands, and help
• grift_std — StdIoProvider, an IoProvider implementation using std::io for stdin/stdout/stderr and dynamic string ports

Then run:

cargo install grift --features std
grift

I/O Architecture

The evaluator is fully no_std and performs no I/O itself. Instead, an IoProvider trait (defined in grift_core) abstracts all port operations:

• NullIoProvider — No-op implementation that silently discards output and rejects reads. Used in no_std/embedded contexts where there is no real I/O.
• StdIoProvider (behind std feature) — Full implementation backed by std::io, providing stdin/stdout/stderr and dynamic string ports.

Pass any IoProvider to the evaluator at runtime:

use grift::{Lisp, Evaluator, NullIoProvider};

let lisp: Lisp<20000> = Lisp::new();
let mut eval = Evaluator::new(&lisp).unwrap();
let mut io = NullIoProvider;
eval.set_io_provider(&mut io);

Crate Organization

This crate re-exports the complete Grift stack:

• grift_arena — Fixed-size arena allocator with mark-and-sweep GC
• grift_core — Core types (Value, Builtin, StdLib, Lisp) and the IoProvider trait boundary
• grift_parser — Lexer and parser
• grift_eval — Fully-trampolined evaluator with native FFI
• grift_repl — Interactive REPL (behind std feature)
• grift_std — StdIoProvider for hosted I/O (behind std feature)
• [grift_macros] — Procedural macros (include_stdlib!)
• [grift_util] — Shared utilities (Scheme-name ↔ Rust-name conversion)
• [grift_arena_embedded] — Embedded hardware natives (GPIO, peek/poke, bit manipulation)

Modules

arena

Arena allocator and garbage collection primitives.

core_types

Core value types and Lisp context.

eval

Evaluator, error handling, and native function interop.

parser

Parser, lexer, value types, and built-in definitions.

replstd

REPL and formatting utilities (requires std feature).

std_iostd

Standard library I/O provider (requires std feature).

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.

EvalError

Evaluation error with context - optimized for minimal size.

Evaluator

The Lisp evaluator with full trampolined TCO.

GcStats

Statistics returned by garbage collection.

LexError

Lexer error with location

Lexer

A standalone lexer that produces tokens on demand without heap allocation.

Lisp

A Lisp execution context wrapping an arena

NativeEntry

A registered native function with its name.

NativeRegistry

Registry for native functions.

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.

Replstd

The REPL structure (for API convenience)

SourceLoc

Source location for error reporting

SpannedToken

A token with its source location

StackFrame

A stack frame for error reporting

StdIoProviderstd

An IoProvider implementation backed by Rust’s standard I/O.

Enums

ArenaError

Errors that can occur during arena operations.

Builtin

Built-in functions (optimization to avoid symbol lookup)

ErrorKind

Error kind enumeration

IoErrorKind

Error kinds for I/O operations in no_std environments.

LexErrorKind

Lexer error kinds

ParseErrorKind

StdLib

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

Token

A token produced by the lexer.

Value

A Lisp value

Constants

MAX_NATIVE_FUNCTIONS

Maximum number of native functions that can be registered.

Traits

FromLisp

Trait for converting Lisp values to Rust types.

IoProvider

Trait for providing I/O operations to the evaluator.

ToLisp

Trait for converting Rust types to Lisp values.

Trace

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

Functions

args_empty

Check if the argument list is empty (nil).

count_args

Count the number of arguments in a list.

eval_to_stringstd

Evaluate a string and return the result as a string

extract_arg

Extract a single argument from a Lisp argument list.

format_errorstd

Format an evaluation error with full context

format_valuestd

Format a Lisp value as a string

parse

Parse a string into a Lisp expression

parse_all

Parse multiple expressions

run_replstd

Run a REPL session

value_to_stringstd

Convert a Lisp value to a string

Type Aliases

ArenaResult

Result type for arena operations.

EvalResult

Result type for evaluation

IoResult

Result type for I/O operations.

NativeFn

A native function that can be called from Lisp.