Architecture: the Rust Floor

Everything above the floor is .naj source: Pink is lib/pink-forms.naj, the tower is lib/tower.naj, the session is lib/purple.naj. The floor itself is a Rust crate, and this chapter is a map into its API documentation — build it with cargo doc --no-deps (or nix build .#docs) and start at the crate page, which carries the same three-layer picture this book does.

Modules

• core — the data. Exp is the expression tree over de Bruijn levels; Val is the runtime value: numbers, symbols, pairs, closures, cells, and Code — staged expressions are values like any other, which is half of what Part II rests on.
• parse — reader, surface desugaring (sug, the cadr family), quasiquote expansion for loaded files, and lowering of names to de Bruijn levels, where n-ary applications curry left-to-right. Unbound names fail at lowering, before any evaluation.
• eval — the machine. evalms drives a CK-style interpreter (an explicit continuation stack rather than host recursion), with the staging state — fresh-name counter, residual block accumulation — in EvalCtx. The staging submodule is the reflection surface the upper layers boot through: the trans and evalms primitives that turn read data into running code.
• io — the NarjuIo boundary. Terminal I/O for interactive use; HeadlessIo for embedding, tests, and this book.
• repl — TopLevel, the parse→lower→evaluate driver, and the interactive floor REPL built on it.
• error, colours — error values (Part I’s catchable payloads) and terminal colour constants.

The crate embeds cleanly: construct a TopLevel with TopLevel::with_io(Box::new(HeadlessIo::…)), feed it forms, read the printed output back from the shared sink. The test suite drives whole Purple sessions this way.

How this book’s examples run

The book is built by mdbook with a custom preprocessor, mdbook-narju — a second binary in the same crate, linked against the library. At build time it walks every chapter and executes the fenced code blocks:

• narju blocks are floor forms, evaluated in order against a per-chapter floor session;
• narju,error blocks must fail, and their error text is captured;
• purple blocks are prompt inputs; all the purple blocks of a chapter are fed to one Purple session, booted from lib/purple.naj through a scripted NarjuIo;
• the ;=>, ;; prints:, and ;! lines in the rendered book are the captured outputs, injected into the markdown.

A block that errors (or an error block that succeeds) fails the build. Every output shown in this book was produced, at the moment the book was built, by the same binary the book documents.