Documentation
Three layers, and they are not interchangeable.
The guide is read in order and teaches. The reference is not read in order and answers, and most of it is generated from the compiler rather than written about it. The rationale says why each decision went the way it did and what it cost.
Guide
Eighteen chapters in the order a reader needs them rather than the order the language was built in. Every one has something to run.
- Hello The smallest complete DriftScript program, and what it means that it needs no host at all.
- Values and mutability let binds immutably, var does not, and mut sits on a parameter rather than on a type.
- Types The whole primitive set, and why Vec3 is not one of them.
- Expressions and statements Precedence, and the two things the language will not guess: truthiness and widening.
- Records data declarations, literals that give every field a value, and why records have no methods.
- Lists and loops A list, the loops that walk it, and constants a whole file can name.
- Enums and match Variants that carry a value, and a match the compiler will not let you leave open.
- Options There is no null. Absence is a type, and the compiler will not let you forget it.
- Results Failure is a returned value rather than an exception, and ? is how it travels.
- Integers and overflow Three spellings for arithmetic, and choosing between them is the point.
- Units Erased at compile time, with no runtime representation whatsoever.
- Modules and imports A .drs file importing another, and a record extending another.
- Capabilities Importing declares a requirement; a target declares what it provides.
- Effects Inferred from the calls a function makes, and checked against what it claims.
- The entity model Components hold the data, a system is a rule on a schedule, a query is how it finds what to run on, and uses is how a system is handed something the host owns.
- Tasks and scopes Asynchronous behaviour with an owner, on three clocks that are not interchangeable.
- Events and state machines Typed events over the host queue, and state as a declaration rather than a variable.
- Hot reload The four categories of change, and who decides what a restart means.
- Setting it up The bundler plugin, the one required compiler flag, and driving the runtime from a loop.
Reference
What to look up rather than read. Most of it is generated from the compiler and the capability registry, so a page here cannot describe a language that has moved on.
- Syntax Every keyword, primitive, annotation and unit suffix, generated from the compiler token table.
- Type system The primitives, the two parameterised types, and the rules for conversion between them.
- std/* The standard library: what the language provides in every host, and why all of it is pure.
- drift/* Every capability this host binds, with its effects and whether it is deterministic.
- The effect set What a function can be doing, tracked whether or not a subsystem is available.
- Diagnostics The compiler talking, captured by compiling a program per entry rather than transcribed.
- Hosting the language What a host implements to run DriftScript: a capability described as data, a function to back it, and a target that declares what it provides. Generic, and the same three steps whatever the host is.
- Surfaces with no provider What a script may name today and be refused for by name, read from the compiler.
Rationale
Why each decision went the way it did, and what it cost. This is the part a reader cannot reconstruct from a reference, and the part most languages never write down.
- Why there is no null What an option costs, and what it buys that a nullable reference cannot.
- Why immutable is the default What it serves, and why mut is a property of a parameter rather than of a type.
- Why units are erased A wrapper would cost an object per value in the one path that budgets zero allocations.
- Why overflow has three spellings A health bar saturates, a hash wraps, and a count should fail.
- Why records have no methods The decision that makes hot reload possible, and what it takes away.
- Why std and drift do not share a prefix One line in a consumer file, and what it costs to move later.
- Why an unprovided module is refused A refusal in words against a silent no-op, and which one a reader can act on.
- Why JavaScript is a backend The single most important technical rule in the language, and what it protects.
- Why the compiler is on this page The language keeps a parser out of production bundles. This site loads one deliberately.