c8e9c42 | plum | pyrossh

git clone https://git.pyrossh.dev/plum

A statically typed, imperative programming language inspired by rust, python

c8e9c42 — Peter John 2026-10-30T19:20:30+05:30

docs: refresh README, plans and example descriptions for current language

Files changed (22) hide show

README.md +428 -272
docs/plans/2026-10-26-game-engine.md +1 -1
docs/plans/2026-10-26-zig-generics-and-numbers.md +1 -1
docs/plans/2026-10-27-optionals-try.md +4 -0
docs/plans/2026-10-27-statics-primitive.md +1 -1
docs/plans/2026-10-27-zig-errors.md +1 -1
plum-examples/chains.plum +2 -0
plum-examples/closures.plum +2 -0
plum-examples/control_flow.plum +1 -0
plum-examples/forms.plum +2 -0
plum-examples/functions.plum +2 -0
plum-examples/generics.plum +2 -0
plum-examples/loops.plum +2 -0
plum-examples/match.plum +2 -0
plum-examples/methods.plum +2 -0
plum-examples/seq.plum +2 -0
plum-examples/strings.plum +2 -0
plum-examples/testing.plum +2 -0
plum-examples/typed_arrays.plum +2 -0
plum-examples/types.plum +2 -0
plum-examples/values.plum +2 -0
plum-std/Regex.mi +0 -1

README.md CHANGED Viewed

@@ -1,20 +1,98 @@
 # 👾 Plum
-A statically typed, imperative programming language with algebraic data types, inspired by Rust and Gleam.
+A statically typed, imperative programming language with algebraic data types, inspired by Rust, Zig, Go, Kotlin and Gleam.
-- Built on a [tree-sitter](plum-tooling/tree-sitter-plum) grammar, with syntax highlighting for Helix and VSCode out of the box (`plum editor helix` / `plum editor vscode`)
+- Built on a [tree-sitter](plum-tooling/tree-sitter-plum) grammar, with syntax highlighting and a language server for Helix and VSCode out of the box (`plum editor helix` / `plum editor vscode`)
-- Compiles to WebAssembly today, with plans to target amd64, arm64, and riscv64 via QBE (C-ABI compatible)
+- Compiles to WebAssembly (wasm-gc) and runs under wasmtime; `plum build` embeds the module into a native executable. Native targets (amd64, arm64, riscv64 via QBE, C-ABI compatible) are planned.
-## Requirements
+## Language at a glance
-```sh
+```plum
+module glance
+import std/Os
-node >= 23.1.0
+import std/Str
-npm >= 10.9.0
+import std/Int
-qbe >= 1.2
+import std/Float
+import std/List
+import std/Seq
+error ParseError = BadNum | Negative       # a named error set
+enum Shape =                               # a sum type; payload fields are named
-clang >= 16.0.0
+  | Circle(r: Float)
-```
+  | Rect(w: Float, h: Float)
-## Installing the `plum` CLI
+  SIDES_MAX = 4                            # associated constant: Shape.SIDES_MAX
+  fun area(self) -> Float =                # a method
+    match self
+      Circle(r) => r * r * 3.14
+      Rect(w, h) => w * h
+value enum Vec2 =                          # small copy-semantics value type
+  | Vec2(x: Float, y: Float)
+  ZERO = Vec2(x: 0.0, y: 0.0)              # Vec2.ZERO
+  fun add(self, o: Vec2) -> Vec2 =         # `a + b` calls a.add(b)
+    Vec2(x: self.x + o.x, y: self.y + o.y)
+fun parse(s: Str) -> ParseError!Int =      # an Int, or a ParseError
+  n := Int.parse(s) catch return error.BadNum
+  if n < 0
+    return error.Negative
+  n
+fun double(s: Str) -> error{BadNum, Negative}!Int =
+  n := try parse(s)                        # `try` propagates the error
+  n * 2
+fun firstEven(xs: List[Int]) -> Int? =     # `T?` is a T or null
+  for x := range xs.find()                 # a Seq terminal; the body is the predicate
+    x % 2 == 0
+fun main() =
+  total := 0
+  for i := range 10, if i % 2 == 0         # range, with a `, if` filter clause
+    total = total + i
+  big := for x := range List(1, 5, 9).map(), if x > 2
+    x * 10                                 # the body is the mapped value
+  e := firstEven(List(1, 3, 4)) ?: -1      # `?:` supplies a default for null
+  n := parse("42") catch 0                 # `catch` supplies a default for an error
+  pos := Vec2.ZERO + Vec2(x: 1.0, y: 2.0)
+  printLn("{total} {big.length()} {e} {n} {pos.y} {Shape.SIDES_MAX}")
+test "glance"
+  assert Rect(w: 2.0, h: 3.0).area() == 6.0
+  assert {double("21") catch 0} == 42
+  assert {parse("-1") catch 7} == 7
+  assert firstEven(List(1, 3)) == null
+```
+| You want | Write |
+|---|---|
+| declare a variable / reassign | `x := 1` / `x = 2` |
+| a block | indent by 2 spaces, no braces |
+| group an expression | `{1 + 2} * 3` (braces; parentheses are for calls) |
+| a conditional expression | `if c then a else b` (there is no `?:` ternary) |
+| loop | `while c`, `for x := range src`, `for i := range n` |
+| a sum type / record | `enum Shape = \| Circle(r: Float) \| Rect(w: Float, h: Float)` |
+| a small value type | `value enum Vec2 = \| Vec2(x: Float, y: Float)` |
+| a method / static / constant | `fun area(self)` / `fun origin()` / `NAME = expr` inside the type body |
+| generics | `fun id(x: T) -> T`, `enum Box[T]`, duck-typed, one copy per type |
+| operators on your types | define `add`, `sub`, `mul`, `div`, `neg`, `eq`, `lt`, `le`, `gt`, `ge` |
+| an optional | `T?`, `null`, `opt ?: default`, `if x := opt`, `opt?.field`, `opt!` |
+| a fallible function | `-> !T`, `-> error{A, B}!T`, `-> ParseError!T`, `return error.A` |
+| propagate / default / crash | `try f()` / `f() catch default` / `f()!` |
+| an iterator | `fun* name(..) *T` with `yield`, used as a `for` source |
+| a sequence chain | `for x := range xs.skip(1).take(3).map()` with the mapped value as the body |
+| a namespace of constants and functions | `primitive Math =` |
+| a test | `test "name"` with `assert` |
+| host function | `extern fun printLn(s: Str)` |
+## Installing
+Prebuilt binaries need nothing else. To build from source you need a recent stable Rust toolchain and a C compiler (for the tree-sitter parser). `node` and `npm` are only needed to rebuild the VSCode extension bundle (`npm install && npm run build` in `plum-tooling/vscode-plum`); without them `plum editor vscode` still installs syntax highlighting.
 ```sh
 cargo install --path plum-cli
@@ -44,6 +122,19 @@ mv plum ~/.cargo/bin/plum   # or anywhere else already on your PATH
 Maintainers: `cargo make release` builds macOS/Linux/Windows binaries (Linux/Windows via [cross](https://github.com/cross-rs/cross), needs Docker), tags `v<version>`, regenerates the links above, and uploads all three to R2 (see `Makefile.toml`; needs [cargo-make](https://github.com/sagiegurari/cargo-make) and the `git` rclone remote configured for R2).
+### Using the CLI
+```sh
+plum run file.plum            # compile and run under wasmtime
+plum test file.plum dir/      # run the `test` blocks of files and directories (recursive)
+plum compile file.plum        # write file.wasm
+plum build file.plum          # embed the module into a native executable
+plum format file.plum         # rewrite in place (--check, --stdin)
+plum editor helix|vscode      # install highlighting and the language server
+```
+`import std/Name` resolves to `<lib-path>/plum-std/Name.plum`, and `--lib-path` defaults to the current directory, so run the commands from a checkout of this repository (or pass `--lib-path`).
 ## Layout and comments
 Blocks are indentation-sensitive (2 spaces), like Python — there's no `{ }` for grouping statements. `#` starts a line comment.
@@ -60,7 +151,7 @@ fun main() =
 | Case | Used for |
 |---|---|
-| `PascalCase` | types, enums |
+| `PascalCase` | types, enums, error sets, namespaces |
 | `camelCase` | functions, methods, fields |
 | `snake_case` | variables, params |
 | `SCREAMING_SNAKE_CASE` | associated constants (`Float.PI`) |
@@ -68,12 +159,16 @@ fun main() =
 ## Modules and imports
+A file may start with `module name`, then its imports, then everything else; `test` blocks go last.
 ```plum
 module basics
 import std/Os
 ```
+Nothing is implicit: `Int`, `Float`, `Str`, `List`, ... are available once the file imports `std/Int`, `std/Float`, `std/Str`, `std/List`, ...
 ## Literals
 ```plum
@@ -90,6 +185,17 @@ yes := true
 no := false
 ```
+An integer literal that does not fit in an `Int` is a compile error (`-0x8000_0000_0000_0000` is `Int.MIN`).
+### String interpolation
+```plum
+fun greet(name: Str) -> Str =
+  "Hello, {name}!"
+```
+`{expr}` interpolates any expression: a variable, literal, attribute access, method call, `&&`/`||`/comparison or an inline `if`.
 ## Operators
 From tightest to loosest binding:
@@ -104,7 +210,7 @@ From tightest to loosest binding:
 | | `^` | |
 | | `&` | |
 | | `\|` | |
-| | `<` `<=` `==` `!=` `>=` `>` `<>` | comparisons |
+| | `<` `<=` `==` `!=` `>=` `>` `<>` | comparisons (`<>` is another spelling of `!=`) |
 | | `!` | boolean not |
 | | `&&` | |
 | | `\|\|` | |
@@ -112,9 +218,12 @@ From tightest to loosest binding:
 | | `if c then a else b` | inline if (the else branch extends as far right as possible) |
 | lowest | `catch` | `x catch default` (the default extends as far right as possible) |
-There's no range operator — every `for` is `for <binders> := range <source>`: `for i := range n` counts 0 to n-1, and the `Int` methods `a.until(b)` (a to b-1), `a.to(b)` (inclusive) and `a.downTo(b)` give other ranges (`for i := range 1.to(10)`). `{ }` is used to group a sub-expression (not `( )`, which is reserved for calls):
+There's no range operator — every `for` is `for <binders> := range <source>` (see [Iteration](#iteration)). `{ }` is used to group a sub-expression (not `( )`, which is reserved for calls):
 ```plum
+sum := 3
+bits := 4
+cmp := true
 grouped := {1 + 2} * {3 - 1}
 picked := if cmp then sum else bits
 negated := -sum
@@ -190,6 +299,8 @@ assert n > 0    # traps at runtime if false
 todo            # traps at runtime — marks a body as not yet implemented
 ```
+`match` is covered under [Types](#match).
 ## Functions
 ```plum
@@ -203,212 +314,123 @@ fun withDefault(a: Int, step: Int = 1) -> Int =
   a + step
 fun sumAll(nums: ...Int) -> Int = # variadic param
+  total := 0
+  for v := range nums
+    total = total + v
-  todo
+  total
 ```
-### Iteration: `for`, `fun*` and `Seq`
-`while` and `for` are the only loops. A `for` has binders, a source, optional clauses and a body:
-```plum
-for u := range units              # a list
-  total = total + u.hp
-for i := range 10           # an Int: 0, 1, ... 9
-  total = total + i
-for i := range 2.until(10)  # an Int fun* method (also to, downTo)
-  total = total + i
-for i, u := range units           # two binders: (position, element)
-  printLn("{i}: {u.name}")
-for _, v := range scores          # a Map: (key, value); `_` ignores a value
-  total = total + v
-for k := range scores.keys()      # a fun* method of Map (also values(), entries())
-  printLn(k)
-```
-#### The iteration protocol
-The protocol is resolved on the type of the source, after type inference:
-- one binder: the type has `length()` and `at(i)` (a `List`, `Array`, `Deque`, a variadic parameter, your own type);
-- two binders: if the type declares a `fun* entries(self) *(A, B)` method it is used (`Map` does: `(key, value)`), otherwise `(position, element)` over `length()`/`at(i)`;
-- `x.name(args)` where the type of `x` declares `fun* name(self, ..)`: the method is expanded like any `fun*`, with `self` bound to `x`.
-A `for` takes clauses after the source: `, if cond` skips an element and `, name := expr` binds a value for the later clauses and the body. A `for` is an expression when its source has a result (`-> R`), with the body's last expression as the value of each step:
-```plum
-alive := for u := range units.filter(), if u.team == me.team
-  u.hp > 0.0
-```
+A function without a return type returns `Unit`; the last expression of a body is its value. A call can name its arguments only for constructors (`Cat(name: "Whiskers", age: 3)`); functions take positional arguments.
-#### `fun*` iterators
+## Types: enums, records and value enums
-A `fun*` is an iterator. `*T` (or `*(A, B)`) is what each `yield` hands to the `for` binders, `-> R` is the optional result of the whole `for`. `yield a, b` runs the `for` body; as an expression (`if yield x`, `acc = yield acc, x`) its value is the body's last expression. A `fun*` is expanded at the use site (hygienic, one loop, no closure, no `call_indirect`); it can't be recursive, can't `return`, and can only be used as a `for` source. `break` and `continue` in the body act on the innermost loop around the `yield`. A `fun*` declared inside a `type`/`enum` body takes `self` and is used as `xs.name()`.
+`enum` is the one declaration form for data. A record type is just a single-variant enum whose one variant shares the enum's own name:
 ```plum
-primitive Int =
+enum Point =
-  fun* until(self, end: Int) *Int =
+  | Point(x: Int, y: Int)
-    i := self
-    while i < end
-      cur := i
-      i = i + 1
-      yield cur
-```
+enum Named =
-#### `Seq[T]` and the chain methods
+  | Named(name: Str)
-`Seq[T]` is a compiler primitive and `*T` is sugar for it. A `Seq` never exists at runtime: it can't be stored, returned or captured, it only flows into a `for` source or into the next method call. The methods live in [`plum-std/Seq.plum`](plum-std/Seq.plum) under `primitive Seq[T]`; `xs.m()` where the type of `xs` has no `m` of its own and is iterable (`length()`/`at(i)`, or an `entries()` method) resolves to `Seq.m`, so they work on every list-like type:
+enum Color =
+  | Red
+  | Green
+  | Blue
-- **adapters** reshape a sequence, have no result and may appear anywhere in a chain: `take(n)`, `skip(n)`, `stepBy(n)`, `zip(other)`, `reversed()`, `chunks(n)` (the last three need a `List` receiver);
-- **terminals** take the `for` body (the predicate, the mapping, the step) and must be the last call: `filter()` (`-> List[T]`), `map()` (`-> List[U]`), `find()` (`-> T?`), `fold(init)` (binders `acc, x`), `count()`, `any()`, `all()`, `each()`, `firstN(n)` (the first n elements the body accepts), and `toList()`, which has no body and needs no `for`: `ys := xs.skip(1).take(3).toList()`.
+enum Maybe =
+  | Just(Int) # unnamed positional payload — Just(5)
+  | Nothing
+enum Shape =
-A terminal in the middle of a chain is an error (`'filter' needs the for body; it must be the last call in the chain`), and so is storing an adapter's result (`s := xs.take(2)`).
+  | Circle(radius: Int) # named payload fields — Circle(radius: 5) or Circle(5)
+  | Square(x: Int, y: Int)
-```plum
+enum Step(n: Int) = # a shared field on every variant ...
-# the first five living units' names, as one fused loop
+  | ReadMin(10) # ... each variant supplies its own value for it
-names := for u := range units.take(5).map(), if u.hp > 0.0
-  u.name
+  | ReadMax(20)
 ```
-Performance guarantee: a whole chain is ONE loop with no closure allocation, no `call_indirect` and no intermediate `List`. The method chain below compiles to the same single loop as the hand-written one:
+The other declaration forms are `value enum` (below), `error Name = A | B` ([Error handling](#error-handling)) and `primitive Name =` ([Constants, statics and `primitive`](#constants-statics-and-primitive)).
-```plum
-total := for acc, u := range units.skip(1).take(10).fold(0.0), if u.team == me.team
+### Methods, `self` and field access
-  acc + u.hp
-total := 0.0                       # the loop you would have written by hand
-seen := 0
-i := 0
-while i < units.length()
-  u := units.at(i)
-  i = i + 1
-  if seen >= 1 && seen < 11
-    if u.team == me.team
-      total = total + u.hp
-  seen = seen + 1
-```
-List and Map have no closure-taking iteration methods; closures remain in the language for passing behavior around as values (`Num` below). See [`plum-examples/seq.plum`](plum-examples/seq.plum) (one test per adapter and terminal), [`plum-examples/chains.plum`](plum-examples/chains.plum) and [`plum-examples/forms.plum`](plum-examples/forms.plum).
-#### Iteration cheat sheet
-| Go / Rust / streams | Plum |
-|---|---|
-| `for _, u := range units` / `for u in &units` | `for u := range units` |
-| `for i, u := range units` / `.iter().enumerate()` | `for i, u := range units` |
-| `for k, v := range m` / `for (k, v) in &m` | `for k, v := range m` (identical to Go) |
-| `for i := 0; i < n; i++` / `for i in 0..n` | `for i := range n` or `range a.until(b)` |
-| `for i := n; i >= 0; i--` / `for i in (0..=n).rev()` | `for i := range n.downTo(0)` |
-| `for i := 0; i < n; i += 2` | `for i := range 0.until(n).stepBy(2)` |
-| `.iter().filter(p).collect()` / `stream.filter(p)` | `for u := range units.filter()` then the predicate as the body |
-| `.iter().map(f).collect()` / `stream.map(f)` | `for u := range units.map()` then the mapped value as the body |
-| `.iter().find(p)` / `findFirst(p)` | `for u := range units.find()` (`-> T?`) |
-| `.iter().fold(0, f)` / `reduce(0, f)` | `for acc, u := range units.fold(0)` |
-| `.iter().take(n).skip(m)` / `limit(n).skip(m)` | `units.skip(m).take(n)` |
-| `.iter().step_by(n)` / `.rev()` / `.zip(o)` / `chunks(n)` | `stepBy(n)` / `reversed()` / `zip(o)` / `chunks(n)` |
-| `.count()` / `.any(p)` / `.all(p)` / `forEach(f)` | `count()` / `any()` / `all()` / `each()` |
-| `if p(x) { continue }` | `, if cond` clause after the source |
-| generator / `yield` | `fun* name(..) *T` with `yield` |
-## Constants, statics and `primitive`
-There are no top-level constants and no free-standing statics. A constant lives inside a type's body (`enum`, `value enum`) or a `primitive`; `NAME = expr` declares an associated constant, and a `fun` without `self` is a static function. Both are reached through the type, `Type.NAME` and `Type.f(args)`, from anywhere, and by their bare name inside the same body. A constant is evaluated lazily, once (a heap value such as a `List` is cached and shared), and names are unique per type, so `Alpha.X` and `Beta.X` coexist.
+A `fun` declared indented directly inside an `enum` body is a method; its first parameter is `self`:
 ```plum
-enum Level =
+enum Cat =
-  | Low
-  | High
-  LIMIT = 10                      # Level.LIMIT
+  | Cat(name: Str, age: Int)
-  fun cap(self, n: Int) -> Int =
+  fun getAge(self) -> Int =
-    if n > LIMIT then LIMIT else n
+    self.age
-value enum Vec2 =
-  | Vec2(x: Float, y: Float)
+  fun birthday(self) -> Int =
+    self.age + 1
+enum Wrapper =
-  ZERO = Vec2(x: 0.0, y: 0.0)     # Vec2.ZERO
+  | Wrapper(inner: Cat, tag: Int)
+fun main() -> Int =
-  fun unit() -> Vec2 =            # a static: Vec2.unit()
+  c := Cat(name: "Whiskers", age: 3)
-    Vec2(x: 1.0, y: 1.0)
+  a := c.getAge()
+  w := Wrapper(inner: c, tag: 1)
+  a + w.inner.age # chained field access
 ```
-The built-in types carry theirs: `Int.MIN`, `Int.MAX`, `Float.PI`, `Float.TAU`, `Float.EPSILON`, `Float.MAX`, ... and the statics `Int.parse(s)` and `Float.parse(s)`.
+A named field of any enum can be read with `.field`, even on a multi-variant enum (the field must have a unique owning variant; a checked downcast does the access).
-#### `primitive`
+### Constructing values
-`primitive Name =` has two meanings, by name:
-- **a namespace**: any name that is not a built-in type declares a stateless namespace of constants and static functions, usable anywhere. It has no `self`, no values and no fields, so `Name` is not a type and can't be constructed or used as a value; it only appears as `Name.NAME` or `Name.f()`. Use an `enum` when you need markers or a set of cases.
-- **a built-in's API**: `primitive Int =`, `primitive Float =`, `primitive Bool =`, `primitive Str =`, `primitive Byte =`, `primitive ByteSlice =`, `primitive Array[T] =` and `primitive Seq[T] =` declare the methods (`fun` and `fun*`), statics and constants of a compiler built-in, without declaring a dummy `enum X = | X` just to hang them on. This is only allowed in `plum-std`; anywhere else it is an error (`primitive Int declares a built-in type and is only allowed in std`).
+Construct a record-shaped enum value by calling its name with `field: value` pairs (any order; every field required), or positionally:
 ```plum
-primitive Config =
-  MAX_RETRIES = 3
-  GREETING = "hello"
+cat := Cat(name: "Whiskers", age: 3)
-  fun retries() -> Int =
-    MAX_RETRIES
-fun main() =
-  n := Config.MAX_RETRIES + Config.retries()
 ```
+Fields are mutable (`cat.age = cat.age + 1`), and a Gleam-style spread updates a copy from an existing value, overriding just the fields you name:
 ```plum
-primitive Byte =                  # in plum-std/Byte.plum
-  fun toInt(self) -> Int =
+older := Cat(..cat, age: cat.age + 1)
-    Int(self)
 ```
-The std library uses namespaces where free functions clearly belong together: `Math.sqrt(x)`, `Math.sin(x)`, ... (`import std/Math`). `Time.now()`, `Uuid.v4()`, `Uuid.fromStr(s)`, `Random.float()` and `Random.intBelow(n)` are statics of their types. See [`plum-examples/constants.plum`](plum-examples/constants.plum) and [`plum-examples/numbers.plum`](plum-examples/numbers.plum).
-## Testing
-Zig-style `test` blocks are a native language feature, compiled and run only by `plum test`:
+### `match`
 ```plum
-fun add(a: Int, b: Int) -> Int =
-  a + b
+match n
-test "add works"
+  0 => 1
+  x =>
-  assert add(1, 2) == 3
+    if x < 0
+      -1
-```
+    else
+      2
-```sh
+match maybe
-$ plum test plum-examples/testing.plum
-└─ add works ✔
+  Just(v) => v
+  Nothing => 0
-1 passed, 0 failed
+match book
+  FantasyBook(title, _, hasMythicalCreatures) when hasMythicalCreatures =>
+    "Fantasy book \"{title}\" features mythical creatures"
+  FantasyBook(title, _, _) => "Fantasy book \"{title}\" has no mythical creatures"
 ```
-## Types: records and enums
+Patterns can be literals, a bare identifier (binds), a bare capitalized name (an enum variant, or an error name when matching an error value, also written `error.Name`; compared), a constructor pattern (`Just(v)`, binding its argument, possibly nested), or `_` (wildcard). `match a, b, ...` supports multiple subjects, and a case can carry a `when <expr>` guard. A `match` over an enum must be exhaustive. See [`plum-examples/match.plum`](plum-examples/match.plum), [`plum-examples/dop_visitor.plum`](plum-examples/dop_visitor.plum) and [`plum-examples/oop_visitor.plum`](plum-examples/oop_visitor.plum).
-There's a single declaration form, `enum` — a record type is just a single-variant enum whose one variant shares the enum's own name:
+Mixed kinds of value live in one enum with a `match self` method per operation:
 ```plum
-enum Point =
-  | Point(x: Int, y: Int)
-enum Named =
-  | Named(name: Str)
-enum Color =
-  | Red
-  | Green
-  | Blue
-enum Maybe =
-  | Just(Int) # unnamed positional payload — Just(5)
-  | Nothing
 enum Shape =
-  | Circle(radius: Int) # named payload fields — Circle(radius: 5) or Circle(5)
+  | Circle(r: Float)
-  | Square(x: Int, y: Int)
+  | Rect(w: Float, h: Float)
-enum Step(n: Int) = # a shared field on every variant ...
+  fun area(self) -> Float =
-  | ReadMin(10) # ... each variant supplies its own value for it
-  | ReadMax(20)
+    match self
+      Circle(r) => r * r * 3.0
+      Rect(w, h) => w * h
 ```
+See [`plum-examples/shapes.plum`](plum-examples/shapes.plum) and [`plum-examples/types.plum`](plum-examples/types.plum).
 ### `value enum`
 `value enum` declares a small, copy-semantics value type (a vector, a color, a rectangle) that is flattened into wasm locals instead of being heap-allocated:
@@ -436,7 +458,7 @@ fun wrap(value: T) -> Bool =
   true
 ```
-Generic types, methods, and free functions are duck-typed and compiled once per distinct instantiation. `List[Int]` and `List(Int)` both parse as generic arguments. See [How generics compile](#how-generics-compile).
+A free function's generic parameters are its single-uppercase-letter type names (`T`, `U`); a type declares its own with `enum Box[T]`. Generic types, methods, and free functions are duck-typed and compiled once per distinct instantiation. See [How generics compile](#how-generics-compile).
 ### How generics compile
@@ -453,6 +475,7 @@ in outer[Plain] (called at main.plum:9:3):
 - **Unreachable generics are not emitted.** A generic that no root (a non-generic fn or a test) reaches is neither checked per type nor compiled.
 - **Typed arrays are native.** Each instantiation stores its elements in an array of its own element type, with no boxing at generic edges.
+- **Bare generic types need type arguments.** `p: Parcel` is an error when `Parcel` is generic; write `p: Parcel[Int]` (or `Parcel[T]` inside a generic).
 - **Explicit behavior values.** When a generic needs behavior that is not a method on `T`, pass it explicitly, like a Zig comptime parameter or a Haskell dictionary:
 ```plum
@@ -464,7 +487,9 @@ fun sumWith(xs: List[T], num: Num[T]) -> T =
   for x := range xs
     acc = num.add(acc, x)
   acc
+```
+```plum
 intNum := Num(add: |a, b| a + b, zero: 0)
 floatNum := Num(add: |a, b| a + b, zero: 0.0)
 sumWith(List(1, 2, 3), intNum)      # 6
@@ -473,22 +498,57 @@ sumWith(List(1.5, 2.5), floatNum)   # 4.0
   `num.add(a, b)` calls the closure stored in the fn-typed field `add`; if the type also declares a method named `add`, the method wins. See `num_record_passed_explicitly` in [`plum-examples/generics.plum`](plum-examples/generics.plum).
-- **Mixed types are enums.** To hold several kinds of value in one list, declare an enum and `match self`:
+## Constants, statics and `primitive`
+There are no top-level constants and no free-standing statics. A constant lives inside a type's body (`enum`, `value enum`) or a `primitive`; `NAME = expr` declares an associated constant, and a `fun` without `self` is a static function. Both are reached through the type, `Type.NAME` and `Type.f(args)`, from anywhere, and by their bare name inside the same body. A constant is evaluated lazily, once (a heap value such as a `List` is cached and shared), and names are unique per type, so `Alpha.X` and `Beta.X` coexist.
 ```plum
-enum Shape =
+enum Level =
+  | Low
-  | Circle(r: Float)
+  | High
-  | Rect(w: Float, h: Float)
+  LIMIT = 10                      # Level.LIMIT
-  fun area(self) -> Float =
+  fun cap(self, n: Int) -> Int =
+    if n > LIMIT then LIMIT else n
-    match self
+value enum Vec2 =
-      Circle(r) => r * r * 3.0
+  | Vec2(x: Float, y: Float)
+  ZERO = Vec2(x: 0.0, y: 0.0)     # Vec2.ZERO
+  fun unit() -> Vec2 =            # a static: Vec2.unit()
-      Rect(w, h) => w * h
+    Vec2(x: 1.0, y: 1.0)
 ```
-See [`plum-examples/shapes.plum`](plum-examples/shapes.plum).
+The built-in types carry theirs: `Int.MIN`, `Int.MAX`, `Float.PI`, `Float.TAU`, `Float.EPSILON`, `Float.MAX`, ... and the statics `Int.parse(s)` and `Float.parse(s)`.
-- **Bare generic types need type arguments.** `p: Parcel` is an error when `Parcel` is generic; write `p: Parcel[Int]` (or `Parcel[T]` inside a generic).
+### `primitive`
+`primitive Name =` has two meanings, by name:
+- **a namespace**: any name that is not a built-in type declares a stateless namespace of constants and static functions, usable anywhere. It has no `self`, no values and no fields, so `Name` is not a type and can't be constructed or used as a value; it only appears as `Name.NAME` or `Name.f()`. Use an `enum` when you need markers or a set of cases.
+- **a built-in's API**: `primitive Int =`, `primitive Float =`, `primitive Bool =`, `primitive Str =`, `primitive Byte =`, `primitive ByteSlice =`, `primitive Array[T] =` and `primitive Seq[T] =` declare the methods (`fun` and `fun*`), statics and constants of a compiler built-in, without declaring a dummy `enum X = | X` just to hang them on. This is only allowed in `plum-std`; anywhere else it is an error (`primitive Int declares a built-in type and is only allowed in std`).
+```plum
+primitive Config =
+  MAX_RETRIES = 3
+  GREETING = "hello"
+  fun doubled() -> Int =
+    MAX_RETRIES * 2
+fun main() =
+  n := Config.MAX_RETRIES + Config.doubled()
+```
+```plum
+primitive Byte =                  # in plum-std/Byte.plum
+  fun toInt(self) -> Int =
+    Int(self)
+```
+The std library uses namespaces where free functions clearly belong together: `Math.sqrt(x)`, `Math.sin(x)`, ... (`import std/Math`). `Time.now()`, `Uuid.v4()`, `Uuid.fromStr(s)`, `Random.float()` and `Random.intBelow(n)` are statics of their types. See [`plum-examples/constants.plum`](plum-examples/constants.plum) and [`plum-examples/numbers.plum`](plum-examples/numbers.plum).
 ## Closures
@@ -506,86 +566,180 @@ fun main() -> Int =
   each(|v| v * 3) + useCapturingClosure()
 ```
-A closure literal is `|params| body`. Capture is snapshot-by-value: a closure copies the outer variables it references at creation time, not re-read live later. A `fn(...) -> T` type annotates a closure-typed parameter or field.
+A closure literal is `|params| body`. Capture is snapshot-by-value: a closure copies the outer variables it references at creation time, not re-read live later. A `fn(...) -> T` type annotates a closure-typed parameter or field, and a named function can be passed wherever a `fn` value is expected. `List` and `Map` have no closure-taking iteration methods (use `for`, below); closures are for passing behavior around as values (see `Num` under [Generics](#how-generics-compile)). See [`plum-examples/closures.plum`](plum-examples/closures.plum).
-## `self`, field access, and methods
+## Iteration
-A `fun` declared indented directly inside an `enum` body is a method, with an implicit `self`:
+`while` and `for` are the only loops. A `for` has binders, a source, optional clauses and a body:
 ```plum
-enum Cat =
-  | Cat(name: Str, age: Int)
-  fun getAge(self) -> Int =
-    self.age
-  fun birthday(self) -> Int =
-    self.age + 1
-fun main() -> Int =
-  c := Cat(name: "Whiskers", age: 3)
+for u := range units              # a list
-  a := c.getAge()
+  total = total + u.hp
-  w := Wrapper(inner: c, tag: 1)
+for i := range 10           # an Int: 0, 1, ... 9
+  total = total + i
+for i := range 2.until(10)  # an Int fun* method (also to, downTo)
+  total = total + i
+for i, u := range units           # two binders: (position, element)
-  w.inner.age # chained field access
+  printLn("{i}: {u.name}")
+for _, v := range scores          # a Map: (key, value); `_` ignores a value
+  total = total + v
+for k := range scores.keys()      # a fun* method of Map (also values(), entries())
+  printLn(k)
 ```
-## Constructing values
+`for i := range n` counts 0 to n-1, and the `Int` methods `a.until(b)` (a to b-1), `a.to(b)` (inclusive) and `a.downTo(b)` give other ranges (`for i := range 1.to(10)`).
+### The iteration protocol
+The protocol is resolved on the type of the source, after type inference:
+- one binder: the type has `length()` and `at(i)` (a `List`, `Array`, `Deque`, a variadic parameter, your own type);
+- two binders: if the type declares a `fun* entries(self) *(A, B)` method it is used (`Map` does: `(key, value)`), otherwise `(position, element)` over `length()`/`at(i)`;
+- `x.name(args)` where the type of `x` declares `fun* name(self, ..)`: the method is expanded like any `fun*`, with `self` bound to `x`.
+A `for` takes clauses after the source: `, if cond` skips an element and `, name := expr` binds a value for the later clauses and the body. A `for` is an expression when its source has a result (`-> R`), with the body's last expression as the value of each step:
 ```plum
-Cat(name: "Whiskers", age: 3)
+alive := for u := range units.filter(), if u.team == me.team
+  u.hp > 0.0
 ```
-Construct a record-shaped enum value by calling its name with `field: value` pairs (any order; every field required).
+### `fun*` iterators
-Fields are mutable (`c.age = c.age + 1`), and a Gleam-style spread updates a copy from an existing value, overriding just the fields you name:
+A `fun*` is an iterator. `*T` (or `*(A, B)`) is what each `yield` hands to the `for` binders, `-> R` is the optional result of the whole `for`. `yield a, b` runs the `for` body; as an expression (`if yield x`, `acc = yield acc, x`) its value is the body's last expression. A `fun*` is expanded at the use site (hygienic, one loop, no closure, no `call_indirect`); it can't be recursive, can't `return`, and can only be used as a `for` source. `break` and `continue` in the body act on the innermost loop around the `yield`. A `fun*` declared inside an `enum` body takes `self` and is used as `xs.name()`.
 ```plum
+primitive Int =
-older := Cat(..c, age: c.age + 1)
+  fun* until(self, end: Int) *Int =
+    i := self
+    while i < end
+      cur := i
+      i = i + 1
+      yield cur
 ```
-## `match`
+A user-defined one:
 ```plum
-match n
-  0 => 1
+fun* neighbours(x: Int, y: Int) *(Int, Int) =
-  x =>
-    if x < 0
+  for dx := range 3
+    for dy := range 3
+      if dx != 1 || dy != 1
-      -1
+        yield x + dx - 1, y + dy - 1
-    else
+```
-      2
-match maybe
-  Just(v) => v
-  Nothing => 0
+### `Seq[T]` and the chain methods
-match book
-  FantasyBook(title, _, hasMythicalCreatures) when hasMythicalCreatures =>
-    "Fantasy book \"{title}\" features mythical creatures"
-  FantasyBook(title, _, _) => "Fantasy book \"{title}\" has no mythical creatures"
+`Seq[T]` is a compiler primitive and `*T` is sugar for it. A `Seq` never exists at runtime: it can't be stored, returned or captured, it only flows into a `for` source or into the next method call. The methods live in [`plum-std/Seq.plum`](plum-std/Seq.plum) under `primitive Seq[T]`; `xs.m()` where the type of `xs` has no `m` of its own and is iterable (`length()`/`at(i)`, or an `entries()` method) resolves to `Seq.m`, so they work on every list-like type:
+- **adapters** reshape a sequence, have no result and may appear anywhere in a chain: `take(n)`, `skip(n)`, `stepBy(n)`, `zip(other)`, `reversed()`, `chunks(n)` (the last three need a `List` receiver);
+- **terminals** take the `for` body (the predicate, the mapping, the step) and must be the last call: `filter()` (`-> List[T]`), `map()` (`-> List[U]`), `find()` (`-> T?`), `fold(init)` (binders `acc, x`), `count()`, `any()`, `all()`, `each()`, `firstN(n)` (the first n elements the body accepts), and `toList()`, which has no body and needs no `for`: `ys := xs.skip(1).take(3).toList()`.
+A terminal in the middle of a chain is an error (`'filter' needs the for body; it must be the last call in the chain`), and so is storing an adapter's result (`s := xs.take(2)`).
+```plum
+# the first five living units' names, as one fused loop
+names := for u := range units.take(5).map(), if u.hp > 0.0
+  u.name
 ```
-Patterns can be literals, a bare identifier (binds), a bare capitalized name (an enum variant, or an error name when matching an error value, also written `error.Name`; compared), a constructor pattern (`Just(v)`, binding its argument), or `_` (wildcard). `match a, b, ...` supports multiple subjects, and a case can carry a `when <expr>` guard.
+Performance guarantee: a whole chain is ONE loop with no closure allocation, no `call_indirect` and no intermediate `List`. The method chain below compiles to the same single loop as the hand-written one:
+```plum
+total := for acc, u := range units.skip(1).take(10).fold(0.0), if u.team == me.team
-## String interpolation
+  acc + u.hp
+```
 ```plum
+total := 0.0                       # the loop you would have written by hand
+seen := 0
+i := 0
+while i < units.length()
+  u := units.at(i)
+  i = i + 1
-fun greet(name: Str) -> Str =
+  if seen >= 1 && seen < 11
-  "Hello, {name}!"
+    if u.team == me.team
+      total = total + u.hp
+  seen = seen + 1
 ```
-`{expr}` interpolates any expression: a variable, literal, attribute access, method call, `&&`/`||`/comparison or an inline `if`.
+See [`plum-examples/seq.plum`](plum-examples/seq.plum) (one test per adapter and terminal), [`plum-examples/chains.plum`](plum-examples/chains.plum), [`plum-examples/forms.plum`](plum-examples/forms.plum) and [`plum-examples/loops.plum`](plum-examples/loops.plum).
-## `extern` functions and printing
+### Iteration cheat sheet
+| Go / Rust / streams | Plum |
+|---|---|
+| `for _, u := range units` / `for u in &units` | `for u := range units` |
+| `for i, u := range units` / `.iter().enumerate()` | `for i, u := range units` |
+| `for k, v := range m` / `for (k, v) in &m` | `for k, v := range m` (identical to Go) |
+| `for i := 0; i < n; i++` / `for i in 0..n` | `for i := range n` or `range a.until(b)` |
+| `for i := n; i >= 0; i--` / `for i in (0..=n).rev()` | `for i := range n.downTo(0)` |
+| `for i := 0; i < n; i += 2` | `for i := range 0.until(n).stepBy(2)` |
+| `.iter().filter(p).collect()` / `stream.filter(p)` | `for u := range units.filter()` then the predicate as the body |
+| `.iter().map(f).collect()` / `stream.map(f)` | `for u := range units.map()` then the mapped value as the body |
+| `.iter().find(p)` / `findFirst(p)` | `for u := range units.find()` (`-> T?`) |
+| `.iter().fold(0, f)` / `reduce(0, f)` | `for acc, u := range units.fold(0)` |
+| `.iter().take(n).skip(m)` / `limit(n).skip(m)` | `units.skip(m).take(n)` |
+| `.iter().step_by(n)` / `.rev()` / `.zip(o)` / `chunks(n)` | `stepBy(n)` / `reversed()` / `zip(o)` / `chunks(n)` |
+| `.count()` / `.any(p)` / `.all(p)` / `forEach(f)` | `count()` / `any()` / `all()` / `each()` |
+| `if p(x) { continue }` | `, if cond` clause after the source |
+| generator / `yield` | `fun* name(..) *T` with `yield` |
+## Optionals
+An optional is `T?`: a `T`, or `null`. It is its own type, not an error: it carries no error name, and `catch` and `try` do not apply to it. A plain `T` in a `T?` slot is the present value, and `null` is the absent value wherever a `T?` is expected (a call or constructor argument, a `return`, a tail, a list element, a parameter default such as `n: Int? = null`). `null` with nothing to say what it is an optional of is an error (`x := null`: `cannot infer the type of null`). For a reference type (a class, enum, `Str`, `List`, ...) a `T?` is stored as a nullable reference, so a present value costs no allocation; for `Int`, `Float`, `Bool` and value enums it is the value plus a present flag. A doubled `T??` is not allowed.
 ```plum
+enum Person =
-extern fun printLn(s: Str)
+  | Person(name: Str, age: Int)
+fun find(n: Int) -> Person? =
+  if n > 0
+    return Person(name: "a", age: n)
+  return null
 ```
-`extern fun` declares a function backed by a host-provided wasm import, with no Plum body. At the boundary `Int` is narrowed to a wasm `i32` (the rest of the language uses 64-bit `Int`), so extern parameters and results are 32-bit. `plum-std/Os.plum` declares `printLn` for use via `import std/Os`.
+| Form | Meaning |
+|---|---|
+| `opt ?: default` | the value, or `default` when `opt` is null. The default may diverge: `opt ?: return null`, `opt ?: return error.Absent`, `opt ?: crash "msg"` |
+| `if x := opt` + block | runs the block with `x: T` bound when present (an optional `else` block runs on null). Also inline: `if x := opt then f(x) else 0` |
+| `while x := opt` + block | loops while the expression is non-null, re-evaluated each iteration: `while job := queue.next()` |
+| `opt!` | the value, or crashes with `<callee> returned null at file:line:col` |
+| `opt == null`, `opt != null` | presence test (either order) |
+| `opt?.field`, `opt?.method()` | maps over a present value; null passes through. A field that is itself `U?` flattens |
+`?:` binds looser than comparison, arithmetic and `||`, tighter than `if`/`catch`, and is right-associative, so `a ?: b ?: c` is `a ?: {b ?: c}`. `catch` is for error unions and `?:` for optionals; using the wrong one is a type error (`catch is for errors; use ?:`, `?: is for optionals; use catch`).
-```sh
+```plum
+fun port(cfg: Config) -> error{Unconfigured}!Int =
+  p := cfg.port ?: return error.Unconfigured     # absence becomes an error
+  p
-$ plum run plum-examples/io.plum
+fun total(xs: List[Int?]) -> Int =
+  sum := 0
+  for x := range xs
+    if n := x
-hello from plum
+      sum = sum + n
+  sum
 ```
+### Safe navigation: `?.`
+`obj?.field` / `obj?.method(args)` (safe navigation, Groovy/Kotlin-style) reaches into an optional (or an error union) without unwrapping it -- a present value maps the field or method access over the inner value and re-wraps it, null (or an error) passes through untouched. A field that is itself a `T?` flattens, so a chain is one `?` value, not a nested one:
+```plum
+enum Target =
+  | Target(name: Str)
+enum User =
+  | User(name: Str, target: Target?)
+fun targetName(u: User?) -> Str? =
+  u?.target?.name
+```
+It's sugar for `obj.andThen(|v| v.field)` -- nothing more than that; chain it as many times as needed. See [`plum-examples/optionals.plum`](plum-examples/optionals.plum) and [`plum-examples/safe_navigation.plum`](plum-examples/safe_navigation.plum).
 ## Error handling
 There are no exceptions. A fallible function returns `!T` (Zig-style: a `T`, *or* an error). An error is an ordinary value written `error.Name` -- `return error.NegativeNum` -- that needs no declaration and carries no data; return details in a normal value instead. Error names are global, and the *set* of names a function can fail with is inferred from its body:
@@ -694,68 +848,70 @@ enum Failure =
   | BadRequest(Str)
 ```
-### Optionals: `T?`
+An error union can have an optional as its success value: `!T?` (`error{Bad}!Int?`). `try x` gives the `T?`, and `?:` then handles the null: `v := try parse(s)` followed by `v ?: 0`. An error union can also be the success type of another (`List[!Int].get(i)` is a `!!Int`): unwrap it one level at a time with `!`, `try` or `catch`. See [`plum-examples/error_propagation.plum`](plum-examples/error_propagation.plum).
-An optional is `T?`: a `T`, or `null`. It is its own type, not an error: it carries no error name, and `catch` and `try` do not apply to it. A plain `T` in a `T?` slot is the present value, and `null` is the absent value wherever a `T?` is expected (a call or constructor argument, a `return`, a tail, a list element, a parameter default such as `n: Int? = null`). `null` with nothing to say what it is an optional of is an error (`x := null`: `cannot infer the type of null`). For a reference type (a class, enum, `Str`, `List`, ...) a `T?` is stored as a nullable reference, so a present value costs no allocation; for `Int`, `Float`, `Bool` and value enums it is the value plus a present flag. A doubled `T??` is not allowed.
+### Runtime representation
-```plum
-fun find(n: Int) -> Person? =
-  if n > 0
-    return Person(name: "a", age: n)
-  return null
-```
+Each error name gets a global `i32` code, interned in sorted order from 1 (0 means success). An optional `T?` of a value type is `(T..., i32)` too (the `i32` is 0 when present, and the code of `null` when absent), and of a reference type a nullable reference. A `!T` result is a multi-value return `(T..., i32)`, so neither success nor failure allocates; stored in a heap slot (a field, a `List` element, a generic container) it is boxed into a `{value, code}` struct.
-| Form | Meaning |
+## Testing
-|---|---|
-| `opt ?: default` | the value, or `default` when `opt` is null. The default may diverge: `opt ?: return null`, `opt ?: return error.Absent`, `opt ?: crash "msg"` |
-| `if x := opt` + block | runs the block with `x: T` bound when present (an optional `else` block runs on null). Also inline: `if x := opt then f(x) else 0` |
-| `while x := opt` + block | loops while the expression is non-null, re-evaluated each iteration: `while job := queue.next()` |
-| `opt!` | the value, or crashes with `<callee> returned null at file:line:col` |
-| `opt == null`, `opt != null` | presence test (either order) |
-| `opt?.field`, `opt?.method()` | maps over a present value; null passes through. A field that is itself `U?` flattens |
-`?:` binds looser than comparison, arithmetic and `||`, tighter than `if`/`catch`, and is right-associative, so `a ?: b ?: c` is `a ?: {b ?: c}`. `catch` is for error unions and `?:` for optionals; using the wrong one is a type error (`catch is for errors; use ?:`, `?: is for optionals; use catch`).
+Zig-style `test` blocks are a native language feature, compiled and run only by `plum test`. Test blocks go at the end of the file; `plum test` takes files and directories (searched recursively):
 ```plum
-fun port(cfg: Config) -> error{Unconfigured}!Int =
+fun add(a: Int, b: Int) -> Int =
-  p := cfg.port ?: return error.Unconfigured     # absence becomes an error
-  p
+  a + b
-fun total(xs: List[Int?]) -> Int =
+test "add works"
-  sum := 0
-  for x := range xs
+  assert add(1, 2) == 3
-    if n := x
-      sum = sum + n
-  sum
 ```
-An error union can have an optional as its success value: `!T?` (`error{Bad}!Int?`). `try x` gives the `T?`, and `?:` then handles the null: `v := try parse(s)` followed by `v ?: 0`. An error union can also be the success type of another (`List[!Int].get(i)` is a `!!Int`): unwrap it one level at a time with `!`, `try` or `catch`.
+```sh
+$ plum test plum-examples/testing.plum
+└─ add works ✔
-### Safe navigation: `?.`
+1 passed, 0 failed
+```
-`obj?.field` / `obj?.method(args)` (safe navigation, Groovy/Kotlin-style) reaches into an optional (or an error union) without unwrapping it -- a present value maps the field or method access over the inner value and re-wraps it, null (or an error) passes through untouched. A field that is itself a `T?` flattens, so a chain is one `?` value, not a nested one:
+A failing `assert` prints the actual and expected values for `==` comparisons. `import std/Testing` adds small assertion helpers (`expectEq`, `expectTrue`, `expectSome`, ...). The `plum-std` library and every file in `plum-examples` carry their own tests: `plum test plum-std plum-examples`.
+## `extern` functions and hosts
 ```plum
-fun cityName(person: Person?) -> Str? =
+extern fun printLn(s: Str)
-  person?.city?.name
 ```
-It's sugar for `obj.andThen(|v| v.field)` -- nothing more than that; chain it as many times as needed.
-### Runtime representation
+`extern fun` declares a function backed by a host-provided wasm import (module `plum`, the function's name), with no Plum body. At the boundary `Int` is narrowed to a wasm `i32` (the rest of the language uses 64-bit `Int`), so extern parameters and results are 32-bit, and an extern can't return an error union. `plum-std/Os.plum` declares `printLn` for use via `import std/Os`; `plum run`, `plum test` and `plum build` provide the standard host functions (printing, `crash`, clock and random, files, HTTP).
-Each error name gets a global `i32` code, interned in sorted order from 1 (0 means success). An optional `T?` of a value type is `(T..., i32)` too (the `i32` is 0 when present, and the code of `null` when absent), and of a reference type a nullable reference. A `!T` result is a multi-value return `(T..., i32)`, so neither success nor failure allocates; stored in a heap slot (a field, a `List` element, a generic container) it is boxed into a `{value, code}` struct.
+```sh
+$ plum run plum-examples/io.plum
+hello from plum
+hello, world!
+```
 ## Standard library highlights
 - **`Bool`** — built in (no import); `true`/`false`, `toStr` is a compiler intrinsic, `"true".parseBool()` (in `std/Str`) parses it
-- **`Str`** (`import std/Str`) — a byte array with a codepoint-aware layer for Unicode correctness: `runeLength`, `runeAt`, `codePointAt`, `codePointToStr`
-- **`Byte`** / **`[]Byte`** (`import std/Byte`) — a scalar unsigned 8-bit value and a fixed-length mutable byte slice
-- **`Buffer`** (`import std/Buffer`) — a growable, mutable byte sequence for building up a `Str`, amortized O(n) writes
-- **`Array[T]`** (`import std/Array`) — the compiler-intrinsic generic array that `List` and `Map` are written on
 - **`Int`** / **`Float`** (`import std/Int`, `import std/Float`) — built-in numbers with their API in `primitive Int` / `primitive Float`: `abs`, `sign`, `min`, `max`, `sqrt`, `pow`, `floor`, `round`, `toStr`, ..., the constants `Int.MAX`, `Float.PI`, ..., and `Int.parse` / `Float.parse`
 - **`Math`** (`import std/Math`) — a `primitive` namespace of floating-point functions: `Math.sqrt`, `Math.sin`, `Math.exp`, `Math.ln`, ...
+- **`Str`** (`import std/Str`) — a byte array with a codepoint-aware layer for Unicode correctness: `runeLength`, `runeAt`, `codePointAt`, `codePointToStr`
+- **`Byte`** / **`ByteSlice`** (`import std/Byte`, `import std/ByteSlice`) — a scalar unsigned 8-bit value and a fixed-length mutable byte slice
-- **`Map[K, V]`** (`import std/Map`) — a real bucketed hash table
+- **`Buffer`** (`import std/Buffer`) — a growable, mutable byte sequence for building up a `Str`, amortized O(n) writes
+- **`Array[T]`** (`import std/Array`) — the compiler-intrinsic generic array that `List` and `Map` are written on; `Grid[T]` is a flat 2D array
 - **`List[T]`** (`import std/List`) — a growable list built on `Array`, with `get`/`add`/`set`/`removeAt`/`remove`/`sort`/`join`/`chunk` (iteration and transformation via `for`)
+- **`Map[K, V]`**, **`Set[T]`**, **`Deque[T]`**, **`Heap[T]`** — a bucketed hash table, a set over it, a ring-buffer double-ended queue and a key-ordered min-heap
+- **`Seq[T]`** (`import std/Seq`) — the adapters and terminals of the `for` chains
+- **`Json`**, **`Base64`**, **`Uuid`**, **`Time`**, **`Random`** — parsing, encoding, ids, wall-clock time and a seeded deterministic generator (`Random.float()` and `Random.intBelow(n)` use the wall clock)
+- **`Os`**, **`Http`** — printing and the file system; HTTP requests through the host
+- **`Testing`** (`import std/Testing`) — assertion helpers for `test` blocks
 See [`plum-examples/`](plum-examples) for a runnable file per feature above, and [`plum-std/`](plum-std) for the standard library source.
+## Editor support
+```sh
+plum editor helix     # tree-sitter grammar, queries and plum-lsp for Helix
+plum editor vscode    # the VSCode extension (add --insiders for VSCode Insiders)
+```
+Both install syntax highlighting and the `plum-lsp` language server (syntax and type diagnostics, keyword and member completion). The grammar, queries and VSCode extension live in [`plum-tooling/`](plum-tooling); everything is embedded in the `plum` binary, so the commands work from any directory. Reload the editor window afterwards.

docs/plans/2026-10-26-game-engine.md CHANGED Viewed

@@ -43,7 +43,7 @@ Survey of `../kam_macroquad`:
    - **Constants:** large top-level constant tables must parse and be usable in expressions. A probe file with `LIMIT = 10` followed by a `type` failed to parse (cause not yet confirmed), and the notes record a SCREAMING_CASE constant gotcha. The fix needs tests with 1k-entry tables.
    - **Seeded RNG** (`Random(seed: Int)` with xorshift/PCG) for deterministic AI and simulation.
    - Lazy iteration is deferred. Hot loops use `for … range`, and it's revisited only if profiling shows `map`/`filter` allocation in `update`.
-5. **Value enums** (`value enum Vec2 = | Vec2(x: Float, y: Float)`, `Color`, `TilePos`). Exactly one constructor named like the type, fields only `Int`/`Float`/`Bool` or other value enums (no `Str`/`List`, no recursion). Lowering: flattened locals and params, multi-value returns, copy semantics and in-place field assignment. They are boxed only inside `List`/`Map`/`Try`, and by then they belong to a generic copy, so a `List[Vec2]` copy stores them as GC structs.
+5. **Value enums** (`value enum Vec2 = | Vec2(x: Float, y: Float)`, `Color`, `TilePos`). Exactly one constructor named like the type, fields only `Int`/`Float`/`Bool` or other value enums (no `Str`/`List`, no recursion). Lowering: flattened locals and params, multi-value returns, copy semantics and in-place field assignment. They are boxed only inside `List`/`Map`/error unions/optionals, and by then they belong to a generic copy, so a `List[Vec2]` copy stores them as GC structs.
 6. **Duck-typed operators** on value enums (`add`/`sub`/`mul`/`neg`/`eq`): `pos + dir * speed`.
 7. **SIMD (late):** `f32x4` (wasm v128) and `Mat4`/`Vec4` in `plum-std/Math.plum`. KaM is 2D, so this is low priority for the port and kept for future 3D work.
 8. **Port scope (simplified KaM):**

docs/plans/2026-10-26-zig-generics-and-numbers.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # Zig-style generics, no traits (Int/Float stay 64-bit)
-**Status:** running (user: "make all the language changes accordingly").
+**Status:** completed and merged to master (966bdab, b911c78).
 **Goal:**
 - Replace traits and erased generics with Zig-style duck-typed generics: no bounds, a body checked per instantiation at the use site, and one compiled copy per type.
 - Use enums for mixed-type values.

docs/plans/2026-10-27-optionals-try.md CHANGED Viewed

@@ -1,3 +1,7 @@
+# Optionals and prefix `try`
+**Status:** completed and merged to master (b911c78).
 ## Task NL (user decisions; runs after task N): optionals with `null`, Kotlin elvis `?:`, `if x := opt`, `while x := opt`, `!` unwrap
 User: drop `error.Missing` and `Missing` entirely; the compiler handles null; add Zig-like sugar.

docs/plans/2026-10-27-statics-primitive.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # Namespaced constants and statics: `primitive`, consts and statics in type bodies, `Number` removed
-**Status:** approved by the user. It runs after the audit and the two fixes (`?` in closures, the formatter).
+**Status:** completed and merged to master (1c1bfe8).
 ## User decisions
 - Remove `enum Number = | Int | Float`. Its methods move to `extend Int` and `extend Float`, and the compiler's primitive-wrapping hack (`primitiveWrapVariant`, the implicit Int/Float→Number wrap) is deleted.

docs/plans/2026-10-27-zig-errors.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # Zig-style error handling: `!T`, postfix `?` and `!`, `catch`, `fail`
-**Status:** running (user approved). **Superseded in part by `2026-10-27-zig-error-sets.md`:** `fail X` became `return error.X`, `!T [A, B]` became `error{A, B}!T` / `Set!T`, and generics are whitespace-free again; the pinned-set syntax and `fail` described below no longer exist. Before E1, an audit of the docs, samples, highlighting and LSP for the for/extend/Seq changes.
+**Status:** completed and merged to master (0dc0e16, 6463f46). **Superseded in part by `2026-10-27-zig-error-sets.md`:** `fail X` became `return error.X`, `!T [A, B]` became `error{A, B}!T` / `Set!T`, and generics are whitespace-free again; the pinned-set syntax and `fail` described below no longer exist. Before E1, an audit of the docs, samples, highlighting and LSP for the for/extend/Seq changes.
 **Goal:** replace the overlapping spellings (`Try`/`Ok`/`Err`, `Int ! [..]`, postfix `?`, `??`, `? |e| X`, auto-wrapped bare tags) with one Zig-style model. The runtime stays the same: an error union is still a Try-shaped value whose error side is a structural tag union.
 ## Design (user decisions: postfix `?` propagates and postfix `!` crashes, replacing the earlier `try`-prefix choice; catch default / catch e block; inferred `!T` with optional explicit set)

plum-examples/chains.plum CHANGED Viewed

@@ -1,3 +1,5 @@
+# Sequence chaining: combines collection adapters (skip, take, map, filter)
+# into single-pass loops via `std/Seq`.
 import std/Str
 import std/Int
 import std/Float

plum-examples/closures.plum CHANGED Viewed

@@ -1,3 +1,5 @@
+# Closures: function-typed parameters (`fn(...) -> R`), closure literals (`|x| expr`),
+# and lexical variable capture from enclosing scopes.
 import std/Str
 import std/Int
 import std/Float

plum-examples/control_flow.plum CHANGED Viewed

@@ -1,3 +1,4 @@
+# Control flow: `if`/`else` branching, `while` loops, and `for ... := range` iteration.
 import std/Str
 import std/Int
 import std/Float

plum-examples/forms.plum CHANGED Viewed

@@ -1,3 +1,5 @@
+# Fused loop forms: `for` loops with `, if cond` filter clauses and inline
+# mapping expressions, plus custom `fun*` generators with `yield`.
 import std/Str
 import std/Int
 import std/Float

plum-examples/functions.plum CHANGED Viewed

@@ -1,3 +1,5 @@
+# Functions: top-level function declarations, typed arguments, return expressions,
+# and recursion.
 import std/Str
 import std/Int
 import std/Float

plum-examples/generics.plum CHANGED Viewed

@@ -1,3 +1,5 @@
+# Generics: duck-typed parameterized functions and types (`Box[T]`),
+# specialized per concrete type without runtime boxing or trait bounds.
 module generics
 import std/Str
 import std/Int

plum-examples/loops.plum CHANGED Viewed

@@ -1,3 +1,5 @@
+# Loops: `while` condition loops, `for ... := range` iteration over ranges and
+# collections, with inline filtering and mapping.
 import std/Str
 import std/Int
 import std/Float

plum-examples/match.plum CHANGED Viewed

@@ -1,3 +1,5 @@
+# Pattern matching: exhaustive `match` expressions over enum variants, integer
+# values, and wildcard `_` patterns with guards.
 import std/Int
 import std/Float
 import std/Str

plum-examples/methods.plum CHANGED Viewed

@@ -1,3 +1,5 @@
+# Methods: defining methods inside type bodies with `self`, accessing and
+# mutating fields, and calling methods on instances.
 import std/Str
 import std/Int
 import std/Float

plum-examples/seq.plum CHANGED Viewed

@@ -1,3 +1,5 @@
+# Sequence adapters and terminals: using `std/Seq` methods (`take`, `skip`,
+# `map`, `filter`, `find`, `fold`) to process collections in `for` loops.
 import std/Int
 import std/Float
 import std/List

plum-examples/strings.plum CHANGED Viewed

@@ -1,3 +1,5 @@
+# Strings: string literals, interpolation `"{var}"`, and Unicode codepoint/rune
+# inspection methods.
 import std/Int
 import std/Float
 import std/Str

plum-examples/testing.plum CHANGED Viewed

@@ -1,3 +1,5 @@
+# Testing: native `test "name"` blocks and `assert` statements executed by
+# the `plum test` runner.
 import std/Str
 import std/Int
 import std/Float

plum-examples/typed_arrays.plum CHANGED Viewed

@@ -1,3 +1,5 @@
+# Typed arrays: unboxed native `Array[Int]` and `Array[Float]` lowering to
+# WebAssembly primitive arrays, along with flat 2D `Grid[T]`.
 module typed_arrays
 import std/Int
 import std/Float

plum-examples/types.plum CHANGED Viewed

@@ -1,3 +1,5 @@
+# Types: algebraic data types via `enum`, named and positional payload fields,
+# and shared fields across variants.
 import std/Str
 import std/Int
 import std/Float

plum-examples/values.plum CHANGED Viewed

@@ -1,3 +1,5 @@
+# Value enums: small copy-semantics value types declared with `value enum`,
+# lowered without heap allocation, supporting duck-typed operators.
 module values
 import std/Str
 import std/Int

plum-std/Regex.mi DELETED Viewed

	@@ -1 +0,0 @@
1	- TBD