x-lang Documentation
Getting Started
- Tutorial — Build, run, and write your first x-lang programs
- Pinning, step by step — Set up a pinned project, retrofit an existing one, pin the platform
- Sandboxing and type reflection, step by step — Make an isolated interpreter, hand it capabilities, teach it types, inspect anything
- README — Project overview, build instructions, feature summary
- AGENTS.md — the briefing for coding agents: running it, the
Lisp assumptions that fail here, and how to find what exists
(
CLAUDE.md symlinks to it; llms.txt indexes this page)
Language
- Specification — Normative language specification (maps 1:1 to test files)
- Glossary — One name per concept: the settled cross-layer vocabulary
- Syntax — The preferred forms and idioms (least surprise; aspirational items marked)
- Bare Syntax — The reader spec any implementation must match
- Architecture — System design, evaluation model, the contract pattern
- The Engine Contract — What an engine must provide, promise and report; how a second implementation is checked
- Type System — Objects, types, the base object, dispatch, extensibility
- Object System — Message-passing classes, single inheritance, encapsulated members,
super
- Dialects — the helium, xenon, and radon dialect layers
- The Lang Contract — what a lang may rely on, and how one is acquired as a pinned bundle
- Crafting a Lang — how one is actually built: the reader’s machinery, the type-system mapping, the rules that bite, distilled from building x-python
- Scaling to Many Langs — what has to be true for there to be twenty of them; measurements shipped, some rulings still proposals
- Modules — The provide/import module system, and pinning a project’s libraries (pin.xon)
- Namespaces — proposal: a scope per module,
provide and import as its doors, and a rule for every name conflict
- First-Class Environments — proposal: an environment as one pair of bindings and parent, and the six engine mechanisms it retires
- State Images — saving and loading a live base as a binary image: what is already reflective, what is measured, and the declarations still proposed
Reference
- The interactive session — the built-in line editor: keys, history, completion, as-you-type colour, and how to replace the loop
- Primitives and core forms — the engine’s instruction set, the coordinates reached through
prim-ref, and the operatives and procedures that boot on top (hand-written)
- Standard Library — Core library functions (hand-written)
- x-lang API Reference — complete library reference, auto-generated from the
(doc ...) forms in lib/x/**
- C API Reference — the C engine, generated by Doxygen from that engine’s own sources
Both generated references are published from main by CI and are not committed.
To read them offline, make doc-x and make doc-c write them to ref/x/ and
ref/c/html/.
- Dev tools — Formatter, linter, coverage, benchmarks, doc generation
Project