# x-lang

> A language built from computational-expression layers over a minimal,
> type-agnostic engine. The engine provides atoms, pairs, an adaptive runtime
> type system, and fexpr-based evaluation; everything above it — semantics,
> standard library, object system, numeric tower, JIT compiler, and the whole
> toolchain — is written in x-lang. s-expressions are the initial syntax, not
> the only one: the reader is extensible and whole surface languages load on
> top. A research and teaching vehicle for layered language construction, not
> a general-purpose application language.

x-lang looks like a Lisp and is not one. It has no `car`/`cdr` (they are
`first`/`rest`) and no `print` (it is `write`/`display`); methods dispatch
subject-last, as in `("a,b" split ",")`; every closure receives itself as
argument 0; and `op`, which takes its arguments unevaluated together with the
caller's environment, is the core form that the applicative `fn` is built
from. Read AGENTS.md before writing any x-lang — it is the short briefing
written for this purpose, and it lists the assumptions that fail.

The library documents itself. `(apropos "split")` searches every documented
name, `(help Str8/split)` returns a signature with argument types and a
runnable example, and `(modules)` lists everything available. From a shell:
`sh x.sh -q -c '(apropos "split")'`.

## Start here

- [AGENTS.md](https://jonruttan.github.io/x-lang/AGENTS.html): the briefing for coding agents — how to run it, what it is not, how to find what exists, and the conventions that bite
- [Documentation index](https://jonruttan.github.io/x-lang/docs/): the front door, with a suggested reading order
- [README](https://jonruttan.github.io/x-lang/): project overview, build, install, feature summary
- [Tutorial](https://jonruttan.github.io/x-lang/docs/tutorial.html): build, run, and write your first programs
- [Glossary](https://jonruttan.github.io/x-lang/docs/glossary.html): one name per concept — fexpr, operative, dialect, the base, contract

## Language

- [Specification](https://jonruttan.github.io/x-lang/docs/spec.html): the normative specification, mapping 1:1 to the test suite
- [Syntax](https://jonruttan.github.io/x-lang/docs/syntax.html): the preferred forms and idioms
- [Architecture](https://jonruttan.github.io/x-lang/docs/architecture.html): system design, the evaluation model, the contract pattern
- [Type system](https://jonruttan.github.io/x-lang/docs/type-system.html): objects, types, the base object, dispatch, extensibility
- [Object system](https://jonruttan.github.io/x-lang/docs/object-system.html): message-passing classes, single inheritance, encapsulated members, `super`
- [Dialects](https://jonruttan.github.io/x-lang/docs/dialects.html): helium (default, no numeric tower), xenon (full stack), radon (experimental)
- [Modules](https://jonruttan.github.io/x-lang/docs/modules.html): the provide/import system, and pinning a project's libraries

## Reference

- [x-lang API reference](https://jonruttan.github.io/x-lang/docs/ref/x/index.html): every module, generated from the `(doc ...)` forms in the library source
- [Primitives and core forms](https://jonruttan.github.io/x-lang/docs/primitives.html): the engine's instruction set and the operatives that boot on top
- [Standard library](https://jonruttan.github.io/x-lang/docs/standard-library.html): the core library functions
- [C API reference](https://jonruttan.github.io/x-lang/docs/ref/c/html/index.html): the C engine, generated by Doxygen

## Building on it

- [The engine contract](https://jonruttan.github.io/x-lang/docs/engine-contract.html): what an engine must provide, promise and report
- [The lang contract](https://jonruttan.github.io/x-lang/docs/lang-contract.html): what a surface language may rely on, and how one is acquired as a pinned bundle
- [Crafting a lang](https://jonruttan.github.io/x-lang/docs/crafting-a-lang.html): how a surface language is actually built, distilled from building x-python
- [Contributing](https://jonruttan.github.io/x-lang/docs/contributing.html): build prerequisites, code style, testing, commit conventions

## Optional

- [Pinning tutorial](https://jonruttan.github.io/x-lang/docs/pinning-tutorial.html): set up a pinned project, retrofit an existing one, pin the platform
- [Sandboxing tutorial](https://jonruttan.github.io/x-lang/docs/sandboxing-tutorial.html): make an isolated interpreter, hand it capabilities, inspect anything
- [Scaling to many langs](https://jonruttan.github.io/x-lang/docs/lang-scale.html): what has to be true for there to be twenty surface languages
- [Bootstrap tool closure](https://jonruttan.github.io/x-lang/docs/bootstrap-closure.html): the self-hosting scorecard
- [Changelog](https://jonruttan.github.io/x-lang/CHANGELOG.html)