The Praxis Book

Praxis is a small, statically typed, garbage-collected programming language for Advent of Code-style puzzle solving. It is procedural and expression-oriented, it infers essentially every type, and it is built around three things a puzzle solver spends the evening doing: reading a strange input format, manipulating data, and finding out why the program just fell over.

A whole program can be three lines:

var numbers = read lines(int)

out(numbers.sum())

$ praxis run sum.px --input sum.in
60

There is no main, no imports, no annotations. read lines(int) is not a library call — read is an expression in the language and lines(int) is a parser written in a small DSL the compiler checks and compiles alongside the rest of your program. numbers is a Vec[Int] because that is what the parser produces, and the compiler worked that out rather than being told.

The three things this book is mostly about

Reading input. Puzzle input is never a data format anybody would choose. Praxis makes the shape of the file the shape of the code. Structure is written outside backticks, where whitespace does not matter; the literal text of the input is written inside them, where it does:

var moves = read lines(`{dir:word} {amount:int}`)

var horizontal = 0
var depth = 0

for move in moves {
    match move.dir {
        "forward" => { horizontal = horizontal + move.amount }
        "down" => { depth = depth + move.amount }
        "up" => { depth = depth - move.amount }
        _ => {}
    }
}

out(horizontal * depth)

$ praxis run dive.px --input dive.in
150

moves is a Vec of records with a dir field and an amount field. Nothing declared that record; the template’s captures are where it came from. Reading input is the part of the book that covers this, and the cookbook has a recipe for every input shape Advent of Code has thrown so far.

Type inference. Praxis is statically typed and almost none of the types are written down. Inference runs over your whole program including the parsers, so a mistake about the shape of the input is a compile error rather than a surprise at line 400. The editor shows you what it concluded: fn foo(a, b) reads as fn foo(a: Int, b: Int) in VS Code, and you can accept the hint to write the annotation into the file. Type inference covers the model, what generalizes, and how to read the errors when the compiler disagrees with you.

The crash debugger. Praxis has no exceptions and no error handling. An index out of bounds, a missing key, an integer overflow, a parse mismatch or a failed assertion stops the program and hands you the wreckage:

error: program faulted: index out of bounds

Backtrace:
#0   window_sum
#1   <entry>

  locals:
    values: Vec[Int] = [12, 7, 41]
    start: Int = 1
  temps:
    <tmp#3: Int> @ "values[start]" = 7
    <tmp#5: Int> @ "start + 1" = 2
    <tmp#6: Int> @ "values[start + 1]" = 41
    <tmp#9: Int> @ "start + 2" = 3

Those are not only the locals — they are the intermediate values of the expression that faulted, each labelled with the source text it came from. In a terminal you get a prompt instead of an exit code, and can walk the frames, print expressions against the captured state, look at the input near the parser’s cursor, then fix the file and reload without losing your input. The crash debugger is the part of the book that covers it.

What Praxis is not

It does not build standalone binaries; the compiler and the runtime are one executable and your program is JIT-compiled every time you run it. There is no ownership, no lifetimes, no manual memory management. There are no user-visible traits, no operator overloading, no macros, and no exceptions. There is no concurrency. There is no package registry.

These are deliberate, and when two of the goals conflict there is an order that settles it: correctness and diagnostics first, then input ergonomics, then edit-run-debug speed, then language simplicity, and only then runtime performance.

How this book is arranged

• Getting started — build the compiler, run a program, learn the command surface.
• The language — the whole surface, from bindings to pattern matching to the collection set, with the prelude and the method catalog as reference tables at the end.
• Reading input — the read expression and its DSL.
• Type inference — what the compiler works out, and why it sometimes will not.
• The crash debugger — the fault model, and the prompt you get instead of an exit code.
• Tooling — the language server, the VS Code extension, and an index of every diagnostic code.
• Under the hood — for the reader who wants to change the compiler rather than use it.
• Appendix A has complete programs; Appendix B has the grammar.

Every example here was run

No code block in this book that shows a program and its output was written by hand. Each one is a real file under docs/book/examples/, and

docs/book/examples/verify.sh

re-runs every one of them against the compiler in this repository and diffs the result against the output printed in the chapter. That includes the programs that are supposed to fail: the diagnostics and the debugger transcripts are captured the same way. If the language changes, this book breaks loudly.

Installing Praxis

Praxis is built from source. There are no binary releases and no installer: you need a Rust toolchain, and at the end of it you have a praxis binary that JIT-compiles .px files. cargo will fetch and build it for you, or you can build it from a checkout.

What you need

A stable Rust toolchain. The repository pins one in rust-toolchain.toml:

[toolchain]
channel = "stable"
components = ["rustfmt", "clippy"]

rustup reads that file when you run any cargo command inside the checkout, so it selects — and if necessary installs — the right toolchain for you. The workspace declares rust-version = "1.88" as its minimum — the floor its own dependencies impose — and anything newer on the stable channel is fine.

Nothing else is required to build the compiler. Praxis links Cranelift for code generation, so there is no LLVM to install.

Installing from crates.io

The compiler is published as fifteen crates and the binary lives in praxis-cli, which depends on the other fourteen:

$ cargo install praxis-cli

That builds in release mode and puts praxis in ~/.cargo/bin — worth having on your PATH, because the VS Code extension looks for it there by default. The crate is praxis-cli and the binary is praxis; the bare name praxis on crates.io belongs to an unrelated project.

Everything below is for building from a checkout instead, which is what you want if you are working on the compiler itself.

Building the compiler

The praxis binary is the praxis-cli crate. From the repository root:

$ cargo build --release -p praxis-cli

That produces target/release/praxis. Confirm it works:

$ ./target/release/praxis --version
praxis 0.1.0

cargo build -p praxis-cli without --release writes target/debug/praxis instead. The debug binary is a complete compiler and builds a good deal faster, which matters while you are working on the compiler itself. Use the release binary for anything you care about the running time of: the code generator and the GC heap are ordinary Rust, and an unoptimized build of them is unoptimized.

To put the binary you just built on your PATH, install from the checkout rather than from the registry:

$ cargo install --path crates/praxis-cli

That builds in release mode and copies the binary into ~/.cargo/bin, overwriting whatever cargo install praxis-cli put there.

The just runner

The repository’s quality gate is a just file. You do not need just to build or use the compiler, only to run the checks the way CI runs them.

$ cargo install just

The recipes are small, and just with no arguments lists them:

just ci is the gate, and the point of it is that it is the only gate: the hosted CI job checks out the tree, installs the toolchain, installs just, and runs just ci. It has no logic of its own, so what CI does and what you do before pushing cannot drift apart. fmt is deliberately not a dependency of ci — CI verifies formatting, it never rewrites your files. Neither is book-bless, which rewrites the book’s expectations from whatever the compiler prints today and would paper over the regression book-verify exists to catch.

Two things about just ci are worth knowing before you run it the first time.

It takes about seventeen minutes on a development laptop, and most of that is not compilation. On macOS the bulk is XProtect scanning each freshly linked test binary the first time it is executed.

Doctests are not part of it. Every library crate sets doctest = false. An example in a /// comment is still compiled by cargo doc, but it is never executed, so an assertion written there checks nothing — put it in a unit test. The reason is cost, not principle: rustdoc --test has to analyze a whole crate before it can discover that the crate has no doctests, that work is never cached, and it was costing 95 seconds a run to execute the single doctest the workspace had.

just asan needs a nightly toolchain (rustup toolchain install nightly) and is not part of ci, because an instrumented build is a second full compile of the workspace; hosted CI runs it on a nightly schedule instead. It does not cover JIT-generated code — Cranelift emits that raw and no -Z flag reaches it — so a green ASan run is necessary and not sufficient for a change that puts new unsafe behaviour in generated code.

The VS Code extension

The extension lives in editors/vscode. It is thin on purpose: it registers the .px extension, launches praxis lsp, contributes three commands and a TextMate grammar for highlighting before the server attaches. There is no parsing and no type logic in it. Everything the editor knows about your program arrives from the compiler over the protocol, so the two cannot disagree about what a file means.

Build it, then package it:

$ cd editors/vscode
$ npm install
$ npm run compile
$ npx @vscode/vsce package

That writes praxis-0.1.0.vsix in the same directory. Install it from the Extensions view’s … menu → Install from VSIX…, or from a shell:

$ code --install-extension editors/vscode/praxis-0.1.0.vsix

The .vsix is gitignored, and reinstalling the same version replaces the previous one.

Then point the extension at your binary. The setting is praxis.binaryPath; it defaults to the bare name praxis, resolved on PATH. If you did not run cargo install, set it to an absolute path to target/release/praxis. That one path is used for the language server and for the run and check commands, so there is a single thing to get right; changing it restarts the server.

If the server cannot start, you get an error message naming the command it tried and the setting to change, rather than a stack trace. It is nearly always a praxis.binaryPath that points at nothing.

The three commands are Praxis: Run File, Praxis: Check File and Praxis: Restart Language Server. The first two save the buffer and then run the binary in an integrated terminal — a terminal rather than an output channel, because the crash debugger is interactive and a write-only pane cannot answer a prompt. Run File appends --input input.txt when a file by that name sits beside the source.

Everything else arrives without the extension contributing anything, because it is a server capability: diagnostics, hover, completion, signature help, go-to-definition, document symbols, semantic tokens, find references, rename, workspace symbols, inlay hints and quick fixes. See Editor support for what each of them does.

One default is worth knowing about. Inlay hints are on, so an unannotated binding or parameter shows the type the compiler inferred, and ?T where inference has not pinned one; accepting a hint writes the annotation into the file wherever that is legal.

Other editors

Any LSP client can drive praxis lsp — it speaks JSON-RPC over stdio and takes no arguments. Clients that append --stdio to the server’s argv are fine: the flag is accepted and ignored, because stdio is the only transport there is.

Running the book’s examples

Every program in this book that is shown together with its output is a real file under docs/book/examples/, and docs/book/examples/verify.sh re-runs all of them against the expectations printed here:

$ ./docs/book/examples/verify.sh getting-started

6 ok, 0 failed

If a chapter and the compiler ever disagree, that script is what says so.

Your first program

A Praxis program is one file with a .px extension. It has no imports, no main and no module declaration — the top-level statements in the file are the program.

out("Hello, Praxis!")

Save that as hello.px and run it:

$ praxis run hello.px
Hello, Praxis!

out is the print function; it writes its argument and a newline to standard output. run parses, type-checks, lowers, JIT-compiles and executes in one step — there is no separate build product and nothing lands on disk.

A program that reads its input

Praxis exists to solve puzzles that arrive as a text file, so the interesting first program reads one. Here is the sonar-sweep problem from Advent of Code 2021 day 1: given a list of depth measurements, count how many are larger than the one before.

The input is a file of integers, one per line — call it sonar.in:

199
200
208
210
200
207
240
269
260
263

And the first draft of the program:

var depths = read lines(int)

var increases = 0
for i in 1..depths.length() {
    if depths.get(i) > depths.get(i - 1) {
        increases = increases + 1
    }
}

out(increase)

Three things are worth naming before we run it. var is the only binding form, and every binding is assignable; there is no let, and no mut either — a parameter, a for variable and a name bound by a pattern are all writable too. read lines(int) is an input parser, not a library call — lines(int) is a shape the compiler understands, and the type of depths is derived from it as Vec[Int] rather than declared. And 1..depths.length() is a half-open range, so it stops one short of the end, which is what a loop that looks backwards wants.

Getting it wrong

$ praxis run sonar-draft.px --input sonar.in
error[Y110]: no method `length` on type `Vec[Int]` taking 0 argument(s)

  sonar-draft.px:4:20
  4 | for i in 1..depths.length() {
    |                    ^^^^^^ no method `length` on type `Vec[Int]` taking 0 argument(s)

error[N001]: `increase` is not defined

  sonar-draft.px:10:5
  10 | out(increase)
     |     ^^^^^^^^ `increase` is not defined

help: did you mean `increases`?
      increases

praxis: 2 error(s)

Two mistakes, both reported. That is the normal case: analysis does not stop at the first error, so one run tells you everything the front end knows.

Read one diagnostic and you can read all of them. It opens with a severity and a code — Y110 is a type error, N001 a name-resolution error, and the letter says which phase found it. Then the file, line and column, then the source line with the exact span underlined. help: is a suggestion, and where the compiler is confident enough to write the replacement — as it is for increase here — the same suggestion is the quick fix your editor offers. Every code is listed in Diagnostic codes.

The compiler declined to run the program at all. Nothing was JIT-compiled and nothing was executed: a file with an error in it never reaches the back end, so you cannot get partial output from a program that does not type-check. praxis check sonar-draft.px prints exactly the same report and skips even trying.

Note also what the first error did not say. There is no “did you mean len?” under length. A near miss is offered when it is within an edit distance of max(1, n / 3) for a name of n characters — so length, at six characters, gets a budget of two, and len is three edits away. A suggestion that fires too eagerly is worse than none, because an editor that offers to rewrite x as y teaches you to stop reading the quick-fix list.

Getting it right

length is spelled len, and the variable is increases:

var depths = read lines(int)

var increases = 0
for i in 1..depths.len() {
    if depths.get(i) > depths.get(i - 1) {
        increases = increases + 1
    }
}

out(increases)

$ praxis run sonar.px --input sonar.in
7

--input FILE is one of two ways to feed a program. The other is standard input, which is what you get when you leave the flag off:

$ praxis run sonar.px < sonar.in
7

They differ in one respect that matters when something goes wrong: --input is read up front, so an unreadable file is reported before your program starts, while standard input is not read until the program’s first read actually evaluates. A program with no read in it never touches stdin at all.

The shorter way

The loop above is the one you would write in any language. Praxis would rather you wrote a pipeline:

var depths = read lines(int)

out(depths.zip(depths.skip(1)).count(|pair| pair.1 > pair.0))

$ praxis run sonar-pipeline.px --input sonar-pipeline.in
7

skip(1) drops the first measurement and zip pairs the two sequences positionally, stopping at the shorter — so each pair is a measurement and the one after it. |pair| pair.1 > pair.0 is a closure over the resulting tuple, and count answers how many satisfy it. There is no .collect() at the end because there is nothing to collect: every stage materializes, so the chain already is a value. See Pipelines.

When a program compiles and still goes wrong

A clean praxis check means the types work out, not that the program does. Division by zero, an index past the end of a Vec, integer overflow and a read that does not match its input are all runtime faults:

var total = 10
var n = 0

out(total / n)

Run that on a terminal and Praxis drops you into an interactive debugger at the faulting instruction, with the locals still alive. Run it anywhere else — a pipe, a CI job, a --debug never — and it prints the same state noninteractively and exits 1:

$ praxis run divide-by-zero.px --debug never
error: program faulted: division by zero

Backtrace:
#0   <entry>

  locals:
    total: Int = 10
    n: Int = 0
  temps:
    <tmp#1: Int> @ "10" = 10
    <tmp#3: Int> @ "0" = 0
    <tmp#5: Int> @ "total / n" = <uninit>
    <tmp#6: Unit> @ "out(total / n)" = <uninit>

The temps are the compiler’s own intermediate values, each labelled with the expression that produced it, and <uninit> marks the ones the fault stopped from ever being assigned — which is how you find the instruction that failed. The fault model explains the fault kinds, and Entering the debugger explains when you get a prompt.

Where to go next

The three commands you will use are run, check and — through your editor — lsp; The command line is the complete surface, including the exit codes. A file is a program explains what the top level really is, and why a fn main is just another function. And The read expression is the part of Praxis that most repays reading early: lines(int) is the simplest shape it has, and the puzzle input you are about to paste in is probably not that shape.

The command line

praxis has three commands — run, check and lsp — and one global flag, --color. The only other flags are run’s --input and --debug, and lsp’s --stdio.

$ praxis --help
Praxis is a small, statically typed, garbage-collected language for Advent of Code-style puzzle solving.

Homepage: https://github.com/tljubej/praxis

Usage: praxis [OPTIONS] <COMMAND>

Commands:
  run    Parse, type-check, JIT-compile, and run the program
  check  Run the front end (lex + parse + type-check) without executing
  lsp    Start the language server over stdio. Speaks JSON-RPC LSP on stdin/stdout; not meant to be run by hand
  help   Print this message or the help of the given subcommand(s)

Options:
      --color <COLOR>
          When to color diagnostic output: `auto` (default) colors iff stderr is a terminal; `always` forces color; `never` emits plain text
          
          [default: auto]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

praxis run

praxis run <FILE> [--input <FILE>] [--debug auto|always|never] [--color auto|always|never]

run is the whole pipeline: lex, parse, resolve, infer, lower to typed HIR, monomorphize, lower to MIR, verify, JIT-compile with Cranelift, execute. Nothing is written to disk and there is no build artifact to clean up.

$ praxis run hello.px
Hello, Praxis!

If the front end finds an error, nothing is compiled and nothing runs:

$ praxis run sonar-draft.px --input sonar.in
error[Y110]: no method `length` on type `Vec[Int]` taking 0 argument(s)

  sonar-draft.px:4:20
  4 | for i in 1..depths.length() {
    |                    ^^^^^^ no method `length` on type `Vec[Int]` taking 0 argument(s)

error[N001]: `increase` is not defined

  sonar-draft.px:10:5
  10 | out(increase)
     |     ^^^^^^^^ `increase` is not defined

help: did you mean `increases`?
      increases

praxis: 2 error(s)

What gets printed, and where

A program’s own output goes to stdout. Everything the compiler says goes to stderr. That split holds for diagnostics, for the runtime-fault report and for the crash debugger’s prompt. So praxis run day05.px > answer.txt captures the answer and still shows you the errors, and 2>/dev/null gets you the answer and nothing else.

Everything a program reports, it prints itself. run adds nothing of its own to stdout — there is no result line, because a file’s top level has no answer value:

var values = read lines(int)
out(values.len())

$ praxis run count-lines.px --input count-lines.in
6

That 6 is the out call and nothing else — which is why out(...) at the top level never echoes its argument twice. A file is a program has the rule in full.

--input FILE

Read the process input from a file rather than from standard input.

$ praxis run sonar.px --input sonar.in
7

$ praxis run sonar.px < sonar.in
7

The two are equivalent to the program and differ in when the bytes are read. --input is read eagerly, before the program starts, so an unreadable path is reported before any output is produced:

$ praxis run sonar.px --input nope.txt
error: failed to read input file `nope.txt`: No such file or directory (os error 2)
$ echo $?
2

Standard input is read lazily, by the program’s first read and never before. A program with no read in it never touches stdin, which is what stops praxis run hello.px from blocking forever on a terminal or on a CI harness that is holding the pipe open. A terminal stdin reads as empty rather than waiting for a human who was not asked for anything.

An I/O error on either path is reported and exits 2. It is never laundered into empty input: a truncated read would otherwise produce a confidently wrong answer. An empty file, on the other hand, is input — a zero-byte --input is passed through as the empty text, and what a parser makes of that is the parser’s business. read lines(int) over nothing is []; a parser that needs content faults at offset 0..0 and says what it expected to find there.

--debug auto|always|never

What to do when the program faults at run time — division by zero, an index out of bounds, integer overflow, a failed read, an explicit panic.

The default is the useful one at a keyboard and the safe one everywhere else: piped, redirected or run from a script, auto behaves as never, so nothing ever hangs waiting on a prompt nobody can see.

$ praxis run divide-by-zero.px --debug never
error: program faulted: division by zero

Backtrace:
#0   <entry>

  locals:
    total: Int = 10
    n: Int = 0
  temps:
    <tmp#1: Int> @ "10" = 10
    <tmp#3: Int> @ "0" = 0
    <tmp#5: Int> @ "total / n" = <uninit>
    <tmp#6: Unit> @ "out(total / n)" = <uninit>

That report is the same state the interactive debugger would show you, printed once instead of offered as a prompt. --debug always is how you drive the debugger from a script: it reads its commands from stdin, which is what this book’s own debugger examples do. See Noninteractive mode and Entering the debugger.

praxis check

praxis check <FILE> [--color auto|always|never]

The front end only: lex, parse, resolve names, infer types, check match coverage. No code is generated and the program is not run, so it is the fast answer to “does this file make sense”, and it is the command an editor’s save-hook wants.

On success it prints nothing:

$ praxis check sonar.px
$ echo $?
0

check and the language server are not two implementations of the front end. praxis check routes through the same query layer the LSP server answers from, so a divergence between what the command line prints and what your editor underlines is unrepresentable rather than merely unlikely. The sort order, the decision to analyze a tree that already has parse errors, and the set of diagnostics that reaches you are settled once, inside the query, and both consumers read them from there.

run performs the same analysis before it compiles anything, so a file check rejects is a file run refuses, with the same text. The reverse does not hold, and in two ways. check cannot tell you about a fault that only happens when the program runs. It also stops one pass earlier than run does: lowering to typed HIR reports a handful of errors of its own — Y013 for an integer literal outside the range of Int, Y125 for a for or closure binding that can fail to match — and those reach you from praxis run only. Not from check, and not from the editor either, which publishes the same query layer’s diagnostics. A clean check means the front end is satisfied, not that the file compiles.

praxis lsp

praxis lsp [--stdio]

The language server. It speaks JSON-RPC over stdin and stdout and is not meant to be run by hand — the VS Code extension launches it, and so will any other LSP client you point at the binary. Run it in a terminal and it will sit waiting for a protocol header, then exit 1 when its stdin closes.

--stdio is accepted and ignored. Several clients append it to the server’s argv to select a transport, and stdio is the only transport this server has, so the flag names something already true. It exists because the alternative was exiting 2 on an argument the convention says is harmless — before a byte of protocol was spoken — which every client reports as “the server crashed” rather than as a bad flag.

The server is one synchronous loop with no async runtime. Its working set is a single file and the front end answers in single-digit milliseconds, so there is nothing for a second thread to do: the loop owns the document store and the query cache outright, and holds no lock, because there is no other thread that could want one. A $/cancelRequest drops a request still sitting in the queue; one already being served runs to completion. Editor support lists what it serves.

--color auto|always|never

Global: it may be given before or after the subcommand. It styles diagnostics throughout, and the error: label of the fault report. The rest of that report — the backtrace, the locals, the temps — and every line the crash debugger prints once it has a prompt are plain text whatever you pass.

--color never is what you want when capturing output for a test or a transcript. auto already does the right thing when you redirect — the ANSI codes are omitted because stderr is not a terminal — so never is for the case where stderr is a terminal and you want plain text anyway.

Exit codes

1 covers both “did not compile” and “compiled and then died”, which are distinguishable from the output but not from the status. If you need to tell them apart in a script, run praxis check first: it returns 1 for exactly the first case.

An internal compiler error — a MIR verifier failure, a JIT failure — also exits 1, with a message that begins internal error: or error: JIT compilation failed. Those are compiler bugs, not program errors.

A file is a program

A .px file is a whole program. Its top-level statements are what runs, in source order, and there is no entry-point ceremony to write around them.

out("first")

fn double(n) { n * 2 }

var answer = double(21)
out(answer)

struct Point { x: Int, y: Int }

out(Point { x: 1, y: 2 })

first
42
{ x: 1, y: 2 }

Statements and declarations may be interleaved. The compiler collects the statements out from between the declarations into one generated function, and that function is what the host calls; the declarations stay where they are, as their own items. That is why a fn may appear after code that calls it, and why a var may not — a declaration is visible everywhere in the file, a binding only after the statement that introduces it. (A struct and an enum are declarations too, and are visible everywhere on the same terms.)

A program has no answer value. Every top-level statement runs for effect, the generated entry function is Unit, and what a program reports is whatever it printed with out — which is also what keeps out(x) at the top level from printing twice.

There is no main

main is not a name the language knows. A fn main is an ordinary function, and nothing calls it for you:

fn main() {
    out("main ran")
}

out("the top level ran")

the top level ran

Write main() yourself if you want it run. A file that declares one and never calls it has no program at all — and because that is the shape other languages ask for, praxis run names both ways out of it:

fn main() {
    out("main ran")
}

error: no statements to run
note: this file declares `fn main`, but a Praxis program is its top-level statements — call it with `main()`, or move its body to the top level

A file of declarations that never mentions main gets the first line alone:

fn helper(n) {
    n + 1
}

error: no statements to run

praxis check accepts both files and exits 0. Having nothing to run is not a type error; it is discovered by the thing that wanted to run it.

A function does not see the bindings around it

Top-level bindings are the natural style for a file that is its own program, and they are the one thing a fn cannot reach. A function is not a closure and captures nothing:

var limit = 10

fn over_limit(n) {
    n > limit
}

out(over_limit(11))

error[N007]: `over_limit` cannot use `limit`: a function does not capture the bindings around it (pass `limit` as a parameter, or use a closure)

  fn-does-not-capture.px:4:9
  4 |     n > limit
    |         ^^^^^ `over_limit` cannot use `limit`: a function does not capture the bindings around it (pass `limit` as a parameter, or use a closure)

praxis: 1 error(s)

The message names both fixes, when both exist — a recursive function is told to pass a parameter and nothing else, because a closure cannot name itself. A closure written at the top level does capture; see functions and closures.

A fn cannot be declared inside another fn either — that is N005, and a struct or enum in a function body gets the same code. Declarations live at the top level; everything else is a statement.

A newline ends a statement

Statements are separated by newlines or by ;, and a semicolon is only required when two of them share a line.

// A line comment runs to the end of the line.
/* A block comment /* nests */ and may span lines. */

var a = 1; var b = 2; out(a + b)

var total = 1 +
    2 +
    3
out(total)

var scaled = [3, 1, 2]
    .sorted()
    .map(|n| n * 10)
out(scaled)

fn one() { 1; }
out(one())

3
6
[10, 20, 30]
1

A newline terminates a statement and never an operator chain. It is not consulted anywhere in the operator loop, so 1 + continues onto the next line and a .method() chain runs down as many lines as you like. A trailing ; is a separator and nothing else: fn one() { 1; } still answers 1.

Two statements adjacent on one line with neither separator is P002:

var a = 1 var b = 2
out(a + b)

error[P002]: expected `;` or a line break between statements

  run-on.px:1:11
  1 | var a = 1 var b = 2
    |           ^^^ expected `;` or a line break between statements

praxis: 1 error(s)

A newline is consulted at break and return too: a line break after the keyword means “no value”, whatever the next token is. return on its own line returns nothing and the line below it is a separate statement. It also stands in for the comma between struct fields, between enum variants and between match arms — but not inside a record literal, where the comma is required.

The two line-leading brackets

A ( and a [ each begin something and continue something, and the newline is what breaks the tie: one asked to continue the expression before it does not do so across a line break. So a call whose callee ends a line and whose argument list begins the next is two expressions rather than a call:

fn double(n) { n * 2 }

var doubled = double
(21)

out(doubled)

<closure:0>

doubled is the function itself; (21) is a parenthesized 21, evaluated and thrown away. Nothing is reported, because nothing is ill-formed — that is the cost of the rule, and it is paid so that a match arm beginning (a, b) => on its own line is an arm rather than an argument list for the arm above it. The same tie-break settles p.x followed by a line-leading (: that is a field read and a parenthesized expression, not a method call.

[ behaves the same way, and has to, because a line-leading [ is a list literal:

var rows = [[1, 2], [3, 4]]

var first = rows
[0]

out(first)
out(rows[0])

[[1, 2], [3, 4]]
[1, 2]

first is the whole of rows, and [0] is a one-element list nobody kept. The fix for both traps is the same: move the bracket up onto the previous line.

Source text

Source is UTF-8. Identifiers may be Unicode — ASCII is the recommendation, not the rule — and text is measured in characters, not bytes.

var π = 3.14159
var größe = "Fjörð"

out(π)
out(größe.len())

3.14159
5

// starts a line comment. /* … */ is a block comment and nests, so commenting out a region that already contains a comment works. An unterminated one is T001 rather than a silently swallowed file.

The keywords are var, fn, if, else, while, for, in, loop, match, return, break, continue, read, struct, enum, true and false. That is the whole list. out, panic, Vec, max and the rest of the prelude are ordinary identifiers that happen to be defined, and so are the builtin type names Int, Text, Bool, Char, Float, Unit and Never — var max = 5 is legal and shadows the builtin — and so is let, which is an ordinary identifier rather than a keyword. See bindings and shadowing.

Reading input

A program that reads its input does so with a read expression, usually as the first top-level statement:

var numbers = read lines(int)

out(numbers.sum())

Given 1, 2 and 3 on three lines:

6

The input file is named with --input, or arrives on stdin. The read expression is a small language of its own and has its own chapter; lines and int are that language’s vocabulary and not the program’s, so outside a read expression neither name is defined.

The generated function has a name you cannot write

It is <entry>, which is not an identifier, so no program can declare a second one and no program can call it. You meet it when a top-level statement faults:

var n = 0
out(10 / n)

error: program faulted: division by zero

Backtrace:
#0   <entry>

  locals:
    n: Int = 0
  temps:
    <tmp#1: Int> @ "0" = 0
    <tmp#3: Int> @ "10" = 10
    <tmp#4: Int> @ "10 / n" = <uninit>
    <tmp#5: Unit> @ "out(10 / n)" = <uninit>

The angle brackets are the point: frame #0 is the file, not something anybody wrote. Everything else about that frame is ordinary — the entry point goes through inference, monomorphization and the backend as a nullary Unit function like any other, so its locals are inspectable and a top-level call to a generic function specializes exactly as a call from a fn body does. What you see above is the non-interactive rendering, from praxis run --debug never. At a terminal the default --debug auto drops you into the crash debugger, stopped at that frame with those locals live.

Bindings and shadowing

var is the language’s one binding form. It introduces a name, that name may be reassigned, and the type it was inferred at is the type it keeps. There is no second keyword and no immutable binding class.

var score = 0
score += 10
score = 25
out(score)

var name: Text = "praxis"
out(name.len())

var seen: Vec[Int] = Vec()
seen.push(3)
out(seen)

25
6
[3]

The : Text and : Vec[Int] are optional. Inference reads the type off the initializer, and off the later uses when the initializer leaves it open — bare Vec() is fine, and the first push decides the element type. Writing the annotation pins the type at the declaration instead, which moves the error to the line that disagrees with you rather than the line after it.

let does not exist

let is not a keyword. The distinction it would draw is inferred rather than declared, and the word is not reserved either, so it is an ordinary identifier the compiler has never heard of.

let x = 5
out(x)

error[N009]: `let` is not a keyword; a binding is written with `var`

  let-is-gone.px:1:1
  1 | let x = 5
    | ^^^ `let` is not a keyword; a binding is written with `var`

help: replace it with `var`
      var

N009 is its own code, and the reason is the fix. let is not a misspelling of anything, so the near-miss search that answers totl with total has nothing useful to say about it: the budget is one edit for a three-letter name, and the name one edit away is Set. The rule is right in general and wrong for this word, so this word is answered before the search runs.

That is the first of four errors from those two lines: let and x run together with no separator (P002), and x is then never declared, so both mentions of it are N001. var let = 5 compiles, if you want the word — which is why this is reported where a statement starts rather than in the lexer.

Assignment keeps the type

Reassignment writes a new value into an existing binding. It never re-runs inference, so the value has to have the type the binding already has:

var score = 0
score = "high"

error[Y001]: expected Int, found Text

  retype.px:2:1
  2 | score = "high"
    | ^^^^^ expected Int, found Text

praxis: 1 error(s)

The span is on the target, not the value: the binding is the thing with the expectation.

The compound operators

There are five — +=, -=, *=, /= and %= — and each is its binary operator’s rule applied to a place. n += 1 is n = n + 1, so what the compound accepts is what the operator accepts, and the right-hand side types against the binding rather than being inferred on its own.

// Each compound is its binary operator applied to a place.
var n = 10
n += 3
n -= 2
n *= 4
n /= 3
n %= 5
out(n)

var f = 10.0
f += 3.0
f -= 2.0
f *= 4.0
f /= 4.0
out(f)

var s = "a"
s += "b"
out(s)

4
11.0
ab

Two consequences fall straight out of “it is the binary operator”:

• %= is Int-only, because % is. f %= 2.0 is Y016, the same refusal f % 2.0 gets. The other four are defined for Float.
• += on a Text is concatenation, because + is. It is the one compound that does not require a number.

Everything else needs a numeric target, and Y010 is the error when it does not get one. The operators are statements and not expressions, so var x = (n += 1) does not parse — see the grammar.

n = n + 1 is the rule and not the lowering: a target that is a field or an element is evaluated once, not once to read and again to write.

Every binding is assignable

A function parameter, a for loop’s variable and a name introduced by a pattern are bindings in exactly the sense a var is, and all of them may be written:

fn clamp_low(n) {
    if n < 0 { n = 0 }
    n
}

out(clamp_low(-3))
out(clamp_low(7))

for i in 0..3 {
    i = i * 10
    out(i)
}

var total = 0
for (a, b) in [(1, 2), (3, 4)] {
    a = a * 100
    total += a + b
}
out(total)

0
7
0
10
20
406

Writing a for variable changes this step and nothing else — the next step rebinds it from the sequence. Writing a parameter changes the callee’s binding and nothing at the call site; see the binding and the object below for what is shared.

Shadowing

A later var may shadow an earlier binding of the same name in the same scope. This is not reassignment: it allocates a new binding, with a new symbol, and the new one may have an unrelated type.

var a = 4
var a = "Foo"
out(a)

var b = 4
var b = b + 1
out(b)

var c = 4
var show_old = || out(c)
var c = "Foo"
show_old()
out(c)

Foo
5
4
Foo

Three rules are in that program. The name resolves to the newest binding declared above the use, so out(a) is the Text. A shadowing initializer is resolved in the environment before the new binding enters scope, so the b on the right of var b = b + 1 is the old Int — this is Rust’s rule and the same trap when you meant to assign. And a closure made before a shadowing declaration keeps the binding it captured, so show_old still prints 4 after c has become a Text.

Shadowing is the only way to rebind a name at a new type. If you want the Text, shadow; if you want the same Int with a new value, assign.

The compiler decides the storage

Removing let removed two decisions the programmer used to make by choosing a keyword. The compiler makes them now, from one fact name resolution can see: whether anything ever writes the binding.

Generalization

A binding nothing writes is generalized, under the usual value restriction. A closure bound to such a name is generic and each use instantiates it fresh:

var id = |x| x

out(id(1))
out(id("text"))

1
text

Add one assignment to id and the same program stops compiling:

var id = |x| x
id = |x| x

out(id(1))
out(id("text"))

error[Y001]: expected (Int) -> Int, found (Text) -> ?T

  reassigned-not-generic.px:5:5
  5 | out(id("text"))
    |     ^^^^^^^^^^ expected (Int) -> Int, found (Text) -> ?T

praxis: 1 error(s)

id is monomorphic, out(id(1)) pinned it to (Int) -> Int, and the Text call is the error. This gate is a soundness requirement rather than a convenience: assignment instantiates a scheme and unifies the copy, so a generalized binding would not be constrained by being written, and id = |n| n + 1 followed by id("s") would type-check and reach the backend as a wrong-type call. Generalization covers the value restriction itself.

Capture

A captured binding that something writes is boxed into a GC-managed cell, so the closure observes the write. One that nothing writes is copied into the closure’s environment, which is cheaper. The choice is the compiler’s, made from the same fact:

var n = 1
var show_n = || out(n)
n = 2
show_n()

var fns = Vec[() -> Int]()
for i in 0..3 {
    i = i * 10
    fns.push(|| i)
}
for f in fns {
    out(f())
}

2
0
10
20

show_n prints 2, not 1: it shares n with the code that wrote it. The loop shows the other half of the rule — boxing is per binding event, not per name. A for variable is a fresh binding each step, so the closure made on step i keeps step i’s value even though the variable is assigned inside the loop.

The binding and the object

Rebinding a name and mutating an object are separate operations, and only the second is visible to anyone else. Passing an argument copies a reference: the callee’s parameter is its own binding pointing at the caller’s object.

fn rebind(xs) {
    xs = [9, 9]
    xs
}

fn mutate(xs) {
    xs.push(9)
}

var values = [1]
out(rebind(values))
out(values)

mutate(values)
out(values)

[9, 9]
[1]
[1, 9]

rebind writes its own binding and the caller’s values is untouched. mutate writes the object both names refer to, and the caller sees it.

Places: fields and elements

An assignment target may be a name, a field, or an index. A field or element store writes into an object; it is the second kind of write above, not a rebinding.

struct Point { x: Int, y: Int }

var p = Point { x: 1, y: 1 }
p.x = 5
p.y += 2
out(p)

var xs = [1, 2, 3]
xs[0] = 100
xs[2] += 1
out(xs)

var counts = Counter[Text]()
counts["a"] += 1
counts["a"] += 1
out(counts["a"])

{ x: 5, y: 3 }
[100, 2, 4]
2

A compound operator evaluates its place once. p.x += 1 loads and stores through the same receiver, so pick(log).x += 1 calls pick a single time.

A sequence store replaces and never appends. xs[xs.len()] = v is a fault, not a push:

var xs = [1, 2, 3]
xs[3] = 4

error: program faulted: index out of bounds

(followed by the backtrace described in a file is a program). Use push when you meant to grow the vector. Vec, Deque, Map, Counter and Grid accept an indexed store; Text is the one subscript you can read and not write, because a Text is an immutable payload with nothing to write through. A tuple element is not a place either:

var t = "abc"
t[0] = "z"

var pair = (1, 2)
pair.0 = 5

error[Y020]: values of type `Text` cannot be assigned through 1 index(es)

  not-a-place.px:2:1
  2 | t[0] = "z"
    | ^^^^ values of type `Text` cannot be assigned through 1 index(es)

error[Y021]: the left side of an assignment must be a name, a field, or an index

  not-a-place.px:5:1
  5 | pair.0 = 5
    | ^^^^^^ the left side of an assignment must be a name, a field, or an index

praxis: 2 error(s)

Y021 is also what you get for f() = 1 — a target that names no storage at all. Rebuild the tuple instead, or use a record, which is the thing in this language with named, writable fields.

Scalars

Praxis has six scalar types: Int, Float, Bool, Char, Text and Unit. They are the leaves of every value the language builds — the elements of a Vec[Int], the keys of a Map[Text, Int], the fields of a record. All six have a literal you can write.

// One value of every scalar type the language has.
var n: Int = 42
var f: Float = 3.5
var b: Bool = true
var t: Text = "praxis"
var c: Char = 'p'
var u: Unit = ()

out(n)
out(f)
out(b)
out(t)
out(c)
out(u)

42
3.5
true
praxis
p
Unit

The annotations are optional — each of those types is inferred from the initializer. See Bindings and shadowing.

One further name is legal in type position. Never is the type of an expression that produces no value (panic(...), return, break); see Control flow.

Literals

// Int literals, with `_` allowed between digits.
out(42)
out(1_000_000)

// Float literals: a fraction, an exponent, or both. `.5` is not one.
out(0.5)
out(3.141_592)
out(1.5e3)
out(2e-3)

// Bool, Unit, Text.
out(true)
out(())
out("praxis")

42
1000000
0.5
3.141592
1500.0
0.002
true
Unit
praxis

An underscore may appear between digits of any run — the integer part, the fraction and the exponent each accept them. A trailing _ is not part of the literal. A float needs a digit on both sides of its point: 0.5 is a float and neither .5 nor 2. is one. That is also what keeps 1..5 a range instead of a malformed number — a . joins a numeric literal only when a digit follows it.

A literal is typed by its syntax and by nothing else: 42 is an Int, 42.0 is a Float, and the two do not mix. That rule and everything that follows from it is Numbers.

An integer literal outside the signed 64-bit range is error[Y013]: `9223372036854775808` is outside the range of `Int` . It is raised while lowering, which praxis check does not run, so this is one of the few diagnostics a clean check will not show you and praxis run will.

-9223372036854775808 is therefore not a way to write the smallest Int: the - is a unary operator applied to a literal that is itself out of range, and the literal is what gets reported. 0 - 9223372036854775807 - 1 computes that value instead.

A text literal is a double-quoted run of UTF-8. Eight escapes are decoded: \n, \t, \r, \", \\, \0, \{ and \}. The last two exist because a { opens an interpolation hole, so a literal brace needs a spelling; a } closes nothing outside a hole and so needs no escape, but \} is accepted anyway to let a pair be written symmetrically. Anything else after a backslash is T005 invalid escape in text literal and stops compilation, with one exception: \` is accepted by the lexer — backticks delimit parser templates — and is not decoded, so it stays in the text as two characters. There is no \u{...} escape.

// The eight escapes a text literal decodes.
out("a\tb")
out("line\nbreak")
out("quote: \" backslash: \\")
out("a\rb".len())
out("a\0b".len())

// `\{` and `\}` are literal braces: a bare `{` opens an interpolation hole.
out("a hole is \{expr\}")

// A `\`` is accepted and left alone: two characters, not one.
out("a\`b".len())

a	b
line
break
quote: " backslash: \
3
3
a hole is {expr}
4

A character literal

A Char is written in single quotes: '#', 'a', ' '. It holds exactly one Unicode scalar value, and the escapes are a text literal’s plus \' for the quote itself — \', \\, \n, \r, \t, \0, \", \{ and \}. There are no \x or \u{…} escapes, in a character literal or in a text one.

// A character literal is one Unicode scalar in single quotes.
var wall = '#'
out(wall)
out(wall == "#"[0])

// The escapes are a text literal's, plus `\'` for the quote itself.
out('\n'.to_int())
out('\t'.to_int())
out('\''.to_int())
out('\\'.to_int())

// One scalar, not one byte: `é` is a single character.
out('é'.to_int())

// And a `Char` can be matched on, which is what the literal is for.
fn cell(c: Char) -> Text {
    match c {
        '#' => "wall"
        '.' => "open"
        _ => "something else"
    }
}

for c in "#.x" {
    out(cell(c))
}

#
true
10
9
39
92
233
wall
open
something else

Exactly one character is the whole rule, and the lexer holds it. '' names no character and 'ab' names two, so both are refused where they are written rather than becoming something the program did not mean:

// A character literal names exactly one character. These are lexical errors,
// which is the whole point: `"##"[0]` was a well-typed program that quietly
// meant `#`, and `""[0]` was a fault at run time.
var two = '##'
var none = ''
out(two)
out(none)

error[T007]: a character literal holds exactly one character

  char-literal-not-one-character.px:4:11
  4 | var two = '##'
    |           ^^^^ a character literal holds exactly one character

help: write it as a text literal
      "##"

error[T007]: empty character literal: `''` names no character

  char-literal-not-one-character.px:5:12
  5 | var none = ''
    |            ^^ empty character literal: `''` names no character

praxis: 2 error(s)

That is the point of the literal rather than a convenience. "##"[0] was a well-typed program that quietly meant #, and ""[0] was a fault at run time; neither is expressible as a literal.

"#"[0] still works and still means what it did. It is the spelling for a character read out of a text the program did not write down — a line it just parsed, a name it was given — and the literal is the spelling for one the program chose. t[i] == '#' is the common shape, with one of each.

The literal is also a load rather than a call. An Int literal is two loads out of an interned table, and an ASCII Char literal is the same; "#"[0] is a runtime call that re-evaluates every time it is reached.

The literal is what makes a Char matchable, which is the part that is not cosmetic — see pattern matching.

Every value is an object

All runtime values are garbage-collected objects reached through a handle, including an Int. No storage location a program can name holds an unboxed scalar: a variable, a field, a tuple element, an enum payload, a captured binding and a collection slot all hold a reference.

You cannot observe this. Scalars and Text are immutable, so aliasing one is indistinguishable from copying it, and the language has no identity comparison — == always asks about values. What the uniform model buys is that the crash debugger can print every live binding with its type, and that no generic function needs a boxing rule of its own.

What it does not cost is an allocation per number. The runtime interns Int values from -256 to 1024 and Char values from 0 to 127 into immortal tables, so the loop counters and ASCII characters a puzzle program actually handles are a table read rather than a heap block.

Equality

== and != are defined for every scalar, and they compare values rather than addresses. Two Texts built in different ways are equal when their characters are:

// `==` works on every scalar. `<` works on Int, Float, Char and Text.
out(42 == 42)
out(3.5 != 3.6)
out(true == true)
out(() == ())
out("abc" == "ab" + "c")
out('x' == 'x')

out(1 < 2)
out(1.5 <= 1.5)
out("Z" < "a")
out('a' < 'b')

true
true
true
true
true
true
true
true
true
true

Float equality is IEEE-754, so NaN == NaN is false and 0.0 == -0.0 is true. Both are in Numbers.

Equality extends structurally to tuples, records, enums and collections built out of equatable types. Function values are the one thing that is never equatable. See Capabilities.

Ordering

<, >, <= and >= are defined for exactly four types: Int, Float, Char and Text.

• Int compares as a signed 64-bit number.
• Float compares by IEEE-754, so any comparison involving NaN is false.
• Char compares by Unicode scalar value.
• Text compares lexicographically by UTF-8 bytes, which for UTF-8 is exactly code-point order.

Bool, Unit, tuples, records, enums, collections and functions have no order. Using one where an order is required is Y006, at check time:

// Bool and Unit have no order. Only Int, Float, Char and Text do.
var ready = true
var done = false
out(ready < done)

$ praxis check bool-order.px --color never
error[Y006]: values of type `Bool` cannot be ordered

  bool-order.px:4:13
  4 | out(ready < done)
    |             ^^^^ values of type `Bool` cannot be ordered

praxis: 1 error(s)

The same rule governs sorted() and heap elements: a Vec[(Int, Int)] cannot be sorted and a MinHeap[(Int, Int)] cannot be pushed to, because a tuple has no order. A lexicographic order over composites is conventional elsewhere and is not defined here: ordering a composite means choosing a semantics for it, and rejecting the program is the honest answer until one is chosen.

Ordering inside a container is a separate question, with one deliberate difference. A container needs a total order or it corrupts its own invariants, so the ordering a heap or a sort uses places a Float NaN after every number and ties it with itself. The source-level < is untouched and stays IEEE-754.

Where to go next

• Numbers — checked Int arithmetic, Float semantics, and the full operator and precedence table.
• Text and Char — concatenation, indexing, iteration, and the two Char conversions.
• The method catalog — every method on every type.

Numbers

Int is a signed 64-bit integer and every arithmetic operator on it is checked: an overflow is a fault that stops the program in the crash debugger, not a wrap that keeps going with a number nobody wrote. Float is IEEE-754 binary64 and behaves the way IEEE-754 says, including never faulting.

The two do not mix. A literal is typed by its syntax — 42 is an Int, 42.0 is a Float — and there is no implicit widening in either direction:

// There is no implicit widening: an Int and a Float never mix.
var scale = 2
out(scale * 1.5)

$ praxis check mixing-numbers.px --color never
error[Y001]: expected Float, found Int

  mixing-numbers.px:3:5
  3 | out(scale * 1.5)
    |     ^^^^^ expected Float, found Int

praxis: 1 error(s)

The conversions are explicit and are a matched pair: Int.to_float() always succeeds, and Float.to_int() truncates toward zero and faults on anything it cannot represent. Both types also render: Int.to_text() and Float.to_text() each answer exactly the characters out writes, because the method and the printer share one renderer. The rule that decides an operation’s type is the operands’: one Float operand makes the operation Float, otherwise it is Int. (A Text operand makes it Text — see Text and Char.)

Overflow is a fault

fn double(n) {
    n * 2
}

out(double(4611686018427387904))

$ praxis run overflow.px --debug never
error: program faulted: integer overflow

Backtrace:
#0   double
#1   <entry>

  locals:
    n: Int = 4611686018427387904
  temps:
    <tmp#2: Int> @ "2" = 2
    <tmp#3: Int> @ "n * 2" = <uninit>

+, -, * and unary - all check. So do / and %, on their one overflowing case: the smallest Int over -1 has no positive counterpart, and both fault with the same integer overflow rather than the division by zero below. The abs prelude helper faults there too, for the same reason.

An Int literal outside the 64-bit range never gets that far — it is Y013 at compile time, described in Scalars.

Opting out of the check

Three modes over the three operators that can overflow without a divisor. Nine methods, all on Int:

// The three modes over the three operators that overflow without a divisor.
var big = 9223372036854775807
out(big.wrapping_add(1))
out(big.saturating_add(1))
out(big.checked_add(1))
out(big.checked_mul(2))
out(5.checked_add(1))
out(2.wrapping_mul(big))

-9223372036854775808
9223372036854775807
None
None
Some(6)
-2

checked_* answers a real Option[Int], so a miss is something you match on rather than a sentinel value to remember.

There is deliberately no wrapping_div, checked_rem, wrapping_neg or checked_abs. Division by zero always faults, so a checked_div answering None would contradict that; 0.wrapping_sub(x) and 0.checked_sub(x) already spell the negation. Praxis has no bitwise operators at all, which is why wrapping_mul exists: modular multiplication has no other spelling.

Division and modulo

/ on two Ints is integer division truncating toward zero, and % is the remainder with the sign of the dividend: -7 / 2 is -3 and -7 % 2 is -1.

Both fault when the divisor is zero, and both report it the same way:

fn share(total, parts) {
    total / parts
}

out(share(10, 0))

$ praxis run divide-by-zero.px --debug never
error: program faulted: division by zero

Backtrace:
#0   share
#1   <entry>

  locals:
    total: Int = 10
    parts: Int = 0
  temps:
    <tmp#3: Int> @ "total / parts" = <uninit>

fn wrap(n, m) {
    n % m
}

out(wrap(10, 0))

$ praxis run modulo-by-zero.px --debug never
error: program faulted: division by zero

Backtrace:
#0   wrap
#1   <entry>

  locals:
    n: Int = 10
    m: Int = 0
  temps:
    <tmp#3: Int> @ "n % m" = <uninit>

Float division does not fault. 1.0 / 0.0 is inf, -1.0 / 0.0 is -inf and 0.0 / 0.0 is NaN, exactly as IEEE-754 requires.

Float

Float arithmetic never faults. % is not defined for Float at all — there is no float remainder to lower it to, so it is refused at check time rather than computing something else. %= is that same operation and is refused with it:

// `%` is defined for Int only, and `%=` is that same operation.
out(5.0 % 2.0)

var f = 5.0
f %= 2.0

$ praxis check float-remainder.px --color never
error[Y016]: `%` is not defined for `Float`

  float-remainder.px:2:5
  2 | out(5.0 % 2.0)
    |     ^^^^^^^^^ `%` is not defined for `Float`

error[Y016]: `%=` is not defined for `Float`

  float-remainder.px:5:1
  5 | f %= 2.0
    | ^ `%=` is not defined for `Float`

praxis: 2 error(s)

%= is worth stating separately because the rule that governs the other four compounds would let it through: they ask for a numeric target, and a Float is numeric. What refuses f %= 2.0 is not that rule but %’s own — the operator is Int-only wherever it appears. The four that do apply to a Float — +=, -=, *=, /= — are float arithmetic, on a binding and through a place alike.

Unary - on a Float is IEEE-754 negation — the sign bit flipped, nothing else — so -0.0 is a value distinct from 0.0, even though the two compare equal.

Float carries twelve methods: abs, sqrt, floor, ceil, round, sign, is_nan, is_infinite, min(other), max(other), to_int and to_text. round rounds half away from zero. min/max return the other operand when one is NaN. pi() and e() are prelude functions, not methods. to_int is the only one that faults: on NaN, on ±inf, and on a finite value outside the signed 64-bit range, with float-to-int conversion out of range.

How a Float prints

out() and to_text() render a finite Float in the shortest text that reads back as the same Float — one function, called from both, so the pair cannot come apart. Because 1 is an Int literal in this language and the two types never mix, a whole-numbered float keeps a fractional part:

// A Float prints in the shortest form that reads back as the same Float,
// so a whole-numbered one keeps its fractional part.
out(1.0)
out(2.5)
out(1e10)
out(0.1 + 0.2)
out(-0.0)
out(1.0 / 0.0)
out(-1.0 / 0.0)
out(0.0 / 0.0)
out(16.0.sqrt())
out(1.5.to_text())

1.0
2.5
10000000000.0
0.30000000000000004
-0.0
inf
-inf
NaN
4.0
1.5

There is no exponent notation on output: 1e10 prints its ten zeros and then takes a .0 like any other whole number. The three non-finite values print as inf, -inf and NaN and take no suffix, because they are not decimal literals.

The rendered form is an answer and nothing more. Map, Set and Counter order their entries by the number rather than by its printing, so a Set[Float] prints {1.5, 2.0, 10.25} and never puts 10.25 between 1.5 and 2.0.

NaN

NaN is unordered. ==, <, >, <= and >= follow IEEE-754, which means every one of them is false against a NaN — including NaN == NaN, and including NaN <= NaN. != is the mirror of ==, so it is the one that answers true:

// NaN is unordered: `==` and the four order comparisons are false against it.
var nan = 0.0 / 0.0
out(nan == nan)
out(nan != nan)
out(nan < 1.0)
out(nan > 1.0)
out(nan <= nan)
out(nan.is_nan())
// The two zeros compare equal and print differently.
out(0.0 == -0.0)
out(1.0 / 0.0 == 1.0 / -0.0)

false
true
false
false
false
true
true
false

is_nan() is how you actually test for one.

Inside a container the answer differs, deliberately. A heap or a sort needs a total order or it breaks its own invariants, so the ordering a container imposes places NaN after every number and ties it with itself, and treats -0.0 and 0.0 as one key. Source-level < is untouched.

The operators, and what binds tighter

This is the whole set. There are no bitwise operators, no exponent operator, no increment or decrement, and no ternary conditional — if is an expression, so it does that job.

Tightest first:

// Tightest first: postfix, then prefix, then the binary levels.
out(-1.5.abs())       // -(1.5.abs())
out((-1.5).abs())     // the other reading, spelled out
out(-2 * 3)           // (-2) * 3
out(2 + 3 * 4)        // 2 + (3 * 4)
out(2 - 3 - 4)        // (2 - 3) - 4
out(1 + 2 == 3)       // (1 + 2) == 3
out(1 == 1 && 2 == 3) // (1 == 1) && (2 == 3)
out(true || false && false)

var span = 0..3 - 1   // 0..(3 - 1)
var n = 0
for i in span { n += 1 }
out(n)

-1.5
1.5
-6
14
-5
true
false
true
2

Two of those rows are worth staring at.

A postfix chain binds tighter than a prefix -. -1.5.abs() is -(1.5.abs()), which is -1.5. Parenthesize when the receiver is meant to be the negative number.

.. binds looser than arithmetic and tighter than ||. 0..n - 1 is 0..(n - 1), which is how every range in the corpus is written.

Comparisons parse left-associatively but do not chain usefully: 1 < 2 < 3 is (1 < 2) < 3, which is a Bool compared with an Int and reports twice — Y001 for the mismatch and Y006 because Bool has no order.

Assignment is not in the table because it is not an expression. =, +=, -=, *=, /= and %= are statements; see Bindings. Each compound is its binary operator’s rule applied to a place, so %= is Int-only exactly as % is, and += concatenates a Text exactly as + does.

The Int helpers in the prelude

abs, sign, min, max, clamp, gcd and lcm are free functions, and every one of them is Int-only — min(1.0, 2.0) is a type error, not a polymorphic call. pi() and e() are the two Float constants. See The prelude.

Text and Char

A Text is an immutable UTF-8 string. A Char is one Unicode scalar value. They are two types with a small, deliberate surface between them: + concatenates two Texts, t[i] reads a Char out of one, a for walks the same Chars, and Char and Int convert in both directions. That is nearly everything there is.

// `+` builds a Text; `len`, `is_empty` and `[i]` take one apart.
var greeting = "héllo" + ", " + "world"
out(greeting)
out(greeting.len())
out(greeting.is_empty())
out(greeting[1])

var vowels = 0
for c in greeting {
    if c == 'o' || c == 'e' { vowels += 1 }
}
out(vowels)

héllo, world
12
false
é
2

len() is 12 and greeting[1] is é, not half of it: both count and index by Unicode scalar value, never by byte.

+ is the only arithmetic operator

Text + Text is concatenation and produces a new Text — a Text is immutable, so neither operand is touched. s += "x" is the same operator, since a compound assignment types its right-hand side against the binding.

Everything else is refused. -, *, / and % report Y016, and + does not stringify its other operand — there is no implicit conversion to Text in any direction:

// `+` is Text's only arithmetic operator, and it does not stringify its operand.
out("ab" * 3)
out("count: " + 3)

$ praxis check text-operators.px --color never
error[Y016]: `*` is not defined for `Text`

  text-operators.px:2:5
  2 | out("ab" * 3)
    |     ^^^^^^^^ `*` is not defined for `Text`

error[Y001]: expected Text, found Int

  text-operators.px:2:12
  2 | out("ab" * 3)
    |            ^ expected Text, found Int

error[Y001]: expected Text, found Int

  text-operators.px:3:17
  3 | out("count: " + 3)
    |                 ^ expected Text, found Int

praxis: 3 error(s)

"ab" * 3 is repetition in some languages. It is not a spelling here, which keeps it free to mean that later. The refusal to stringify is the load-bearing half: a language whose + renders its other operand has no error left to report, and 1 + 2 in the middle of a longer expression starts depending on what its neighbours are.

The conversion the second error asks for is written, and it is written explicitly:

out("count: " + (3).to_text())

Int, Float and Char each have a to_text(), and each answers exactly the characters out writes — the method and the printer share one renderer, so they cannot disagree. Bool has none, and there is no universal T.to_text(): a conversion defined on every type is the coercion + refuses, arriving under a method name.

For a labelled line you usually want the next section instead.

Interpolation: {…} renders a value

A { inside a text literal opens a hole. The expression in it is evaluated and rendered into the surrounding text:

// A hole renders its value exactly as `out` does — whatever type it holds.
var part2 = 42
out("Part 2: {part2}")

var a = 3
var b = 4
out("{a} + {b} = {a + b}")

// Any type at all, not only the ones with a `to_text()`.
var splits = [10, 20, 30]
var pair = (1, "x")
out("splits: {splits}, pair: {pair}, third: {splits[2]}, how many: {splits.len()}")

// A hole is a full expression, and a `"` inside one opens a literal of its own.
var scores = Map[Text, Int]()
scores["ada"] = 7
out("ada scored {scores["ada"]}, which is {if scores["ada"] > 5 { "a lot" } else { "not much" }}")

// `\{` is a literal brace.
out("a hole looks like \{name\}")

Part 2: 42
3 + 4 = 7
splits: [10, 20, 30], pair: (1, x), third: 30, how many: 3
ada scored 7, which is a lot
a hole looks like {name}

Two things about a hole are worth stating plainly, because both are decisions rather than conveniences.

A hole may hold any type, and it renders exactly what out renders — the same [10, 20, 30], the same (1, x), the same shortest round-tripping float. That is not a coincidence checked by a test: a hole and out call the same renderer through the value’s type descriptor, so a type that prints is a type that interpolates, and the two cannot drift apart. There is no list of interpolable types to fall out of.

A hole holds a full expression, not just a name. {a + b}, {p.0}, {xs.len()}, {m["k"]} and even {if c { "yes" } else { "no" }} are all holes, and a " inside one opens a literal of its own. The expression is parsed exactly as it would be anywhere else, which is why a name in a hole resolves, renames, reports N001 when it does not exist, and is captured when the hole is inside a closure.

A literal brace is \{, joining the escape table in Scalars. A } on its own closes nothing, so it needs no escape — "a } b" is three characters and a pair of spaces.

{{ is not an escape, and it is refused rather than left to mean something else. It is the escape in Rust, C# and Python, so it is the first thing most readers try — and here it would parse: { opens the hole, {} is an empty block, } closes it, so "a{{}}b" would quietly print aUnitb. Rather than let a doubled brace mean a block nobody wanted, the compiler names the spelling that works:

// `{{` is the escape in some other languages. It is not one here, and it is
// refused rather than left to mean something else: a `{` opens a hole, so `{{`
// would open a hole holding a block, and `"a{{}}b"` would quietly print `aUnitb`.
var n = 1
out("a{{}}b")
out("count: {{n}}")

error[P001]: `{{` is not an escape for a literal brace: write `\{` for a `{`, or a value to render between single braces

  text-interpolation-doubled-brace.px:5:8
  5 | out("a{{}}b")
    |        ^ `{{` is not an escape for a literal brace: write `\{` for a `{`, or a value to render between single braces

error[P001]: `{{` is not an escape for a literal brace: write `\{` for a `{`, or a value to render between single braces

  text-interpolation-doubled-brace.px:6:14
  6 | out("count: {{n}}")
    |              ^ `{{` is not an escape for a literal brace: write `\{` for a `{`, or a value to render between single braces

praxis: 2 error(s)

A hole is part of the program

The expression in a hole is an ordinary subtree, not text re-read later, and everything that follows from that is the point of the design. A name in a hole is a real reference: it is captured by an enclosing closure, it renames with every other occurrence, and your editor colours and hovers it as the binding it is rather than as string.

// A name in a hole is an ordinary reference, so a closure captures it like any
// other — the hole is a real part of the program, not text scanned later.
var label = "total"
var n = 7

var describe = |extra| "{label} = {n + extra}"
out(describe(0))
out(describe(3))

// It counts as a capture, which `out` on the closure makes visible.
out(describe)

total = 7
total = 10
<closure:2>

describe prints <closure:2> because it captured two bindings — label and n — and it named both of them only inside a hole.

This does not change what + does. "n = " + n is still Y001, and deliberately so: a hole is a rendering site the program wrote, where + coercing its operand would render values nobody asked to render. The two rules are complements: a hole has no neighbours to depend on, and exists for no purpose but to render what it names. An operator has both.

Indexing answers a Char

t[i] and t.get(i) are one row with two spellings, and both answer a Char. Indexing is by Unicode scalar value, and an index past the end faults:

fn fourth(t) {
    t[3]
}

out(fourth("ab"))

$ praxis run text-index-fault.px --debug never
error: program faulted: index out of bounds

Backtrace:
#0   fourth
#1   <entry>

  locals:
    t: Text = "ab"
  temps:
    <tmp#2: Int> @ "3" = 3
    <tmp#3: Char> @ "t[3]" = <uninit>

There is no store: t[0] = c is Y020 values of type Text cannot be assigned through 1 index(es), because a Text is immutable. Text is the one subscriptable type that reads and does not write.

There is also no slicing. t[1..3] is a type error — a subscript takes an Int, and a Range is not one. To take a piece of a line, either walk it or let the read expression cut it up as it parses.

A character the program chooses is written as a character literal, '#'; "#"[0] is the other spelling, for a character read out of a text the program did not write down. Comparing a Char with a one-character Text is a type error rather than a convenience — c == "a" is error[Y001]: expected Char, found Text, and the fix is c == 'a'.

Char and Int

Three rows, and they are the whole Char surface.

• Char.to_int() answers the Unicode scalar value. It never faults.
• Int.to_char() answers the Char with that scalar value. It is the narrowing half, so it faults on a negative value, on anything above 0x10FFFF, and on a surrogate.
• Char.to_text() answers the one-character Text holding it — the same character out writes. It never faults, because a Char is a validated scalar value by construction.

// Char and Int convert in both directions, and each renders as a Text.
var digits = "2026"
var value = 0
for c in digits {
    value = value * 10 + (c.to_int() - '0'.to_int())
}
out(value)
out('A'.to_int())
out(65.to_char())
out(233.to_char())
out('A'.to_text())
out("count: " + value.to_text())

2026
65
A
é
A
count: 2026

fn as_char(n) {
    n.to_char()
}

out(as_char(55296))

$ praxis run int-to-char-fault.px --debug never
error: program faulted: not a Unicode scalar value

Backtrace:
#0   as_char
#1   <entry>

  locals:
    n: Int = 55296
  temps:
    <tmp#2: Char> @ "n.to_char()" = <uninit>

A Char is not an arithmetic type: c - 48 does not compile. c.to_int() - 48 does, and that round trip is why to_int() exists at all. There is deliberately no is_digit, is_alpha, to_upper or to_lower — to_int() expresses every one of them, and four rows that save a comparison are still four rows.

A Text is iterable

for c in t walks the characters, and the Char it binds is the same one t[i] answers — one runtime function answers both, so the two cannot disagree about what the ith character is, including about counting scalars rather than bytes.

There is no Text.chars(). The for is the spelling, and two spellings for one question is what the catalog refuses. Char itself is not iterable: it is what iterating a Text produces.

A Text is also a full pipeline receiver — the tenth one, and the only one that is not a collection:

// A Text is a pipeline receiver, and its item is the Char `t[i]` answers.
var line = "a1b2c3"
out(line.count())
out(line.count(|c| c >= '0' && c <= '9'))
out(line.filter(|c| c >= 'a').to_vec().len())
out(line.map(|c| c.to_int()).sum())

6
3
3
444

The item type is the decision here, not merely that the loop is accepted. A one-character Text would have served and is not what you get: t[i] answers a Char, so the loop binds a Char, and a program that indexes and a program that iterates compare against the same thing.

The methods

Text’s own catalog is three rows plus the subscript:

Everything a bigger standard library would offer — split, trim, lines, replace, starts_with, repeat, chars, to_upper — is absent. That is not an oversight so much as a division of labour: the work those functions do is what the read expression is for, and it does it while parsing rather than afterwards. The method catalog is the authoritative list.

The two routes back into a Text

Those rows go the other way — a Text taken apart — and there are two that put one back together:

join is a pipeline row, so it works on any of the ten receivers; its items must be Text, and it renders nothing — [1, 2].join(",") is expected Text, found Int, and the spelling is [1, 2].map(|n| n.to_text()).join(","). The separator is required, so join("") says at the call site that nothing goes between.

to_text() on a Vec[Char] is the inverse of walking a Text, and it is how a Grid row is drawn back as the line it was read from:

for y in 0..g.height() { out(g.row(y).to_text()) }

Text is equatable, which is what makes it a Map key and a Set element, and separately orderable, which is what makes it a sort key — Bool and tuples are keys without being orderable, so the two properties are worth keeping apart. Comparison is lexicographic over UTF-8 bytes, which for UTF-8 is code-point order, and it is the order a Set[Text] walks in as well as the order sorted() gives.

What a Text costs

A Text has two representations and the language never says which one you have. A literal, a concatenation and the whole of the program’s input are owned payloads. Every capture the input parser hands back is a slice — a view into the buffer it was parsed from, one level deep, with no copy. Parsing a hundred thousand fields therefore allocates a hundred thousand views and copies nothing.

What that buys, and what it does not, is visible only as complexity. An owned text counts its own scalars once, lazily, and caches the count; a slice inherits that answer from its owner. When every scalar in the owner is one byte — which is every ASCII input, and so nearly every input — indexing is a byte offset:

Rows two and four are the honest residual, and neither the for nor the subscript escapes it: there is no random access into a variable-width encoding without a wider representation, and Praxis does not build one. A text with one non-ASCII character in it costs O(n) per character to walk, whichever spelling you use.

Concatenation always allocates a fresh owned payload, because a new Text has no single owner to point into. Building a long string with += in a loop is therefore quadratic, and there is no builder type that avoids it — but there is join, which walks the sequence once and allocates once, so a line assembled from parts does not have to pay for it.

Where to go next

• Scalars — literals, escapes, and why there is no 'a'.
• The read expression — how text turns into structure.
• Pipelines — the combinators a Text accepts.

Control flow

Praxis has if, while, for, loop, break, continue and return, plus match, which has a chapter of its own. Blocks are expressions and so are all of these, so the thing that decides a value and the thing that produces it are usually one piece of syntax.

Two rules carry most of the weight. An if produces a value, which is why there is no ternary operator. A loop is the only loop that produces one, and it produces whatever its breaks carry.

if is an expression

fn grade(score: Int) -> Text {
    if score >= 90 {
        "A"
    } else if score >= 80 {
        "B"
    } else {
        "C"
    }
}

var n = 7
var parity = if n % 2 == 0 { "even" } else { "odd" }

out(parity)
out(grade(95))
out(grade(83))
out(grade(12))

odd
A
B
C

The condition is an ordinary expression, needs no parentheses, and must be Bool — if 1 { … } is Y001: expected Bool, found Int, not a truthiness rule. It is parsed with record literals suppressed, so if flag { … } reads the braces as the branch rather than as flag’s field list; a record literal in a condition has to be parenthesized, as in if (P { x: 1 }).x == 1 { … }.

Both branches must agree on a type, and an if with no else has an implicit empty one, so its type is Unit. That is fine as a statement and an error the moment you ask it for something:

var n = 7
var label = if n > 0 { "positive" }
out(label)

error[Y001]: expected Text, found Unit

  if-without-else.px:2:22
  2 | var label = if n > 0 { "positive" }
    |                      ^^^^^^^^^^^^^^ expected Text, found Unit

help: this value is `Unit`; an `if` with no `else` expected `Text` — make the last expression produce a value, or change the declared type to `Unit`

praxis: 1 error(s)

while

var i = 0
var sum = 0
while i < 10 {
    i = i + 1
    if i % 3 != 0 { continue }
    sum = sum + i
}
out(sum)

18

continue jumps to the next test. A while is always Unit: it has an exit path — the condition failing — with no value on it, so there is nothing for it to produce. loop, below, is the one that does.

for over anything iterable

for binding in iterable { … } walks the ten collections and Text. The binding is a pattern, so a Map’s (key, value) pair can be taken apart in place:

for x in [3, 1, 2] { out(x) }
for i in 0..3 { out(i) }
for c in "hi" { out(c) }

var counts = Map()
counts["a"] = 1
counts["b"] = 2
for (word, n) in counts {
    out(word)
    out(n)
}

var heap = MinHeap()
heap.push(3)
heap.push(1)
heap.push(2)
for x in heap { out(x) }

3
1
2
0
1
2
h
i
a
1
b
2
1
2
3

Each iterable’s order is the one its own accessors already promise, and every one is deterministic — a hash-backed collection is walked in ascending order of its members, not in hash order, so two runs of the same program agree. A MinHeap is walked in pop order, which is why 3, 1, 2 came back as 1, 2, 3.

“Ascending” is the type’s own order, the same one sorted() uses: numeric for Int, Byte and Float, code-point for Char and Text, and element-wise left to right for a tuple, a record or an enum. So a Set[Int] holding 2 and 10 is walked 2, 10, and out(s) prints that same sequence.

A for is Unit. It runs its body; it does not collect anything. To build a value out of a sequence, use a pipeline.

The loop variable is an ordinary binding and may be assigned inside the body. Each step rebinds it, so the assignment does not survive into the next one.

What happens if you mutate what you are iterating

The seven collections that cannot index themselves — Set, Map, Counter, BitSet, MinHeap, MaxHeap, Grid — are walked through a snapshot taken once, before the loop starts. Mutating one inside its own for is well defined and terminates; the walk does not see the change.

A Vec, a Deque, a Range and a Text index themselves, so no snapshot is taken and the loop re-reads the length on every step. A push during the walk is seen:

var seen = Set()
seen.insert(1)
seen.insert(2)
for x in seen {
    out(x)
    seen.insert(x + 10)
}
out(seen)

var xs = [1, 2, 3]
for x in xs {
    out(x)
    if x == 1 { xs.push(99) }
}
out(xs)

1
2
{1, 2, 11, 12}
1
2
3
99
[1, 2, 3, 99]

The Set loop ran twice, over the two members the set had when it began, and both inserts landed anyway. The Vec loop ran four times. If that asymmetry matters to your program, iterate a copy.

A snapshot is the only protocol a collection that cannot index itself can offer. A hash set and a hash map have no nth member, so answering one is a linear scan and every loop over a hashed collection would be quadratic; a heap’s array is ordered at its root and nowhere else, so reading it by index answers in insertion order rather than in heap order. One call that hands back the members costs one Vec per loop and gets every collection right.

loop is the value its breaks carry

loop { … } repeats until something leaves it. It is the only loop that is an expression with a value, and that value is the join of every break in it:

fn collatz_steps(start: Int) -> Int {
    var n = start
    var steps = 0
    loop {
        if n == 1 { break steps }
        if n % 2 == 0 { n = n / 2 } else { n = 3 * n + 1 }
        steps = steps + 1
    }
}

out(collatz_steps(27))
out(collatz_steps(1))

111
0

The loop is the last expression in collatz_steps, so its value is the function’s result. Nothing is written twice, and there is no sentinel to initialize.

The edges all follow from “the join of its breaks”:

• loop { break 42 } is Int.
• loop { break } is Unit — a bare break leaves with nothing, so mixing break and break 1 in one loop is a Y001 rather than a coincidence that happens to work.
• loop { } is Never: it produces no value at all, so it absorbs into whatever sits beside it. if n > 0 { n } else { loop { } } is an Int.

A break carrying a value out of a while or a for is rejected. Those loops have an exit path — the condition failing, the sequence running out — that no break is on, and there is no value to invent for it:

var n = 0
var first = while n < 10 {
    if n * n > 20 { break n }
    n = n + 1
}
out(first)

error[Y017]: a `break` carrying a value needs a `loop`; a `while` produces `Unit`

  break-with-value-in-while.px:3:27
  3 |     if n * n > 20 { break n }
    |                           ^ a `break` carrying a value needs a `loop`; a `while` produces `Unit`

praxis: 1 error(s)

Rewrite it as a loop with the test inside, or read the var the while left behind. Those two loops have an exit the compiler cannot fill: nothing in while c { break 1 } says what the loop produces when c is false, and there is no value to invent.

break and continue apply to the innermost enclosing loop; there are no labels. Where there is no loop, both are Y012 — `break` outside a loop, `continue` outside a loop. A closure body is outside every loop around it, so loop { var f = || break } is Y012 too: a break inside a closure has no loop of its own to leave.

Ranges

a..b is the integers from a up to but not including b; a..=b includes b. Both bounds are required — there is no a.., ..b or .. — and both are Int.

.. binds looser than arithmetic, so 0..n - 1 means 0..(n - 1), which is what a range with a computed bound almost always wants.

A range is a value, not just a loop header. It binds to a name, goes in a Vec, is a Map key, and is a type a parameter can declare:

var window = 2..6
out(window)
out(1..=3)

var windows = [0..2, 3..5]
out(windows)

var names = Map()
names[0..2] = "low"
names[2..4] = "high"
out(names[0..2])

fn width(r: Range) -> Int {
    var n = 0
    for i in r { n = n + 1 }
    n
}
out(width(window))
out(width(3..=7))

2..6
1..4
[0..2, 3..5]
low
4
5

1..=3 printed as 1..4. A range is normalized to its half-open form when it is built, so 1..=3 and 1..4 are one value — they compare equal and hash to the same key — and the inclusive spelling is the one thing about a range that is not recoverable from it afterwards. Being a key is safe because a range has no mutator at all: its two bounds are as fixed as a tuple’s elements.

Range is a collection type with no methods of its own, so r.len() is Y110. The pipeline methods do work on it: (1..5).count() is 4 and (1..5).sum() is 10.

A descending range is empty

5..0 does not count down. It is empty, and the emptiness is established when the range is built rather than checked by every reader:

var down = 5..0
out(down)

var ran = 0
for i in 5..0 { ran = ran + 1 }
out(ran)

for i in 0..0 { ran = ran + 1 }
out(ran)

// Counting down is a reversed range, which is a Vec and not a Range.
for i in (0..3).reversed() { out(i) }

5..5
0
0
2
1
0

5..0 printed as 5..5, because the constructor clamps an end below start up to start. No range with a negative length exists, so a for reading a range’s length can never get a bound that runs the loop backwards. The case that decides it is 0..n with n == 0: that has to run zero times, not n times in reverse.

The countdown is (0..n).reversed(), a pipeline barrier that answers a Vec[Int]. It does not make a descending Range — there is no such value, and the clamp above is why. Writing 5..0 still earns no diagnostic: it is a legal empty collection, and the language has no warnings to give it.

The bounds are Int and nothing else. A Float range would need a step to yield anything at all — 0.0..1.0 has no elements without one — and a range that cannot say what it yields is not a collection.

return

return leaves the enclosing function, with a value or without one. It is not needed for the common case — the last expression of a function body is its result — but it is the way out of the middle of a loop:

fn first_even(xs) {
    for x in xs {
        if x % 2 == 0 { return x }
    }
    0 - 1
}

A return inside a loop leaves the function, not the loop, which is why a loop exited only by return produces no value and is Never.

The fallback there is written 0 - 1 and not -1 on purpose. A block is an expression and the expression parser does not stop at a line break, so a } followed by a line beginning with - reads as one subtraction spanning both. Parenthesize, or write the negation so it cannot start a line.

Functions and closures

Praxis has two callable forms and one deliberate difference between them. A fn is a top-level declaration and is a function of its parameters and nothing else. A closure, |x| …, is an expression, and it captures the bindings around it.

That is the line to keep in mind, because it is the one the compiler enforces: naming an outer binding inside a fn is an error with its own code, and the error tells you which of the two forms you wanted.

fn

struct Point { x: Int, y: Int }

fn manhattan(a, b) {
    abs(a.x - b.x) + abs(a.y - b.y)
}

fn factorial(n: Int) -> Int {
    if n <= 1 { 1 } else { n * factorial(n - 1) }
}

fn first_even(xs) {
    for x in xs {
        if x % 2 == 0 { return x }
    }
    0 - 1
}

out(manhattan(Point { x: 1, y: 2 }, Point { x: 4, y: 6 }))
out(factorial(5))
out(first_even([1, 3, 6, 7]))
out(first_even([1, 3, 7]))

7
120
6
-1

The last expression of the body is the result; return leaves early. Parameter and return annotations are optional and inference derives both from use, which is how manhattan knows its arguments have x and y fields and answers Int. Write them where they document something, or where the error message you get without them points at the wrong place.

A parameter is a plain name — there is no destructuring in a fn parameter list, unlike a closure’s. It is also an ordinary binding, so a function may assign to its own parameter:

fn clamp_low(n) {
    if n < 0 { n = 0 }
    n
}

Functions may be declared in any order and may call each other, including mutually and recursively. They may not be nested: a fn inside a fn is N005.

A name has exactly one signature. There is no overloading on arity or type, no optional or default parameters, and no named arguments. A call with the wrong count is Y024: this function takes 2 argument(s), but 1 were given. Where another language would overload, Praxis uses a second name — the method catalog does, with min/min_by, max/max_by and find/position. The prelude’s own min and max are the two-argument free functions, and there is no min_by beside them.

A fn does not capture

A fn body may name other declarations — functions, structs, enums, variant constructors, the prelude — because those are reachable from anywhere. It may not name a var outside itself. That is a report, not a silent read:

var offset = 10

fn shift(n: Int) -> Int {
    n + offset
}

out(shift(1))

error[N007]: `shift` cannot use `offset`: a function does not capture the bindings around it (pass `offset` as a parameter, or use a closure)

  fn-does-not-capture.px:4:9
  4 |     n + offset
    |         ^^^^^^ `shift` cannot use `offset`: a function does not capture the bindings around it (pass `offset` as a parameter, or use a closure)

praxis: 1 error(s)

The message names both ways out, and both are ordinary:

var offset = 10

fn shift(n: Int, by: Int) -> Int {
    n + by
}

var shift_by_offset = |n| n + offset

out(shift(1, offset))
out(shift_by_offset(1))

11
11

The boundary is a fn body, not a closure body. A closure opens no boundary of its own, so the question is always about the nearest enclosing fn, and the three cases are the three you would expect:

• A closure at the top level using a top-level binding is fine — top-level statements are the program’s own body, and the binding is in it.
• A closure inside a fn, using that fn’s own local, is fine. It captures something the function has.
• A closure inside a fn, using a binding declared outside that fn, is N007. The closure is inside g; the binding is not.

A recursive fn is offered only the parameter

The message above names two ways out. A recursive function has one, because a closure cannot name itself: var f = |n| … f(n - 1) … resolves f in the environment before the declaration, so the call inside is N001. Rather than suggest something it would then refuse, the compiler drops that half and says which rule took it away:

var step = 2

fn countdown(n: Int) -> Int {
    if n <= 0 { 0 } else { 1 + countdown(n - step) }
}

out(countdown(10))

error[N007]: `countdown` cannot use `step`: a function does not capture the bindings around it (pass `step` as a parameter)

  fn-recursive-cannot-capture.px:4:46
  4 |     if n <= 0 { 0 } else { 1 + countdown(n - step) }
    |                                              ^^^^ `countdown` cannot use `step`: a function does not capture the bindings around it (pass `step` as a parameter)

help: `countdown` calls itself, so a closure is not the way out: a closure cannot name itself (`N001`)

praxis: 1 error(s)

Mutual recursion counts too, and there the help: names the other function in the cycle. A fn that merely calls a recursive one is not itself recursive and keeps both ways out.

A binding declared after the function is N001 rather than N007: only fn, struct and enum are pre-registered for forward reference, so the name is genuinely not in scope and nothing has crossed a boundary.

The alternative is a fn that captures, and it is a worse language: fn and closure would then differ only in syntax, and every function would acquire a hidden environment it did not declare. A fn is a function of its parameters and nothing else, a closure is the thing that captures, and N007 is where the line is drawn.

Closures

A closure is |params| body. The body is one expression, which may be a block. Parameters are patterns, so a pair can be taken apart in the parameter list, and || — one token — is the empty list:

var offset = 10
out([1, 2, 3].map(|x| x + offset))

fn shifted(values, by) {
    values.map(|x| x + by)
}
out(shifted([1, 2, 3], 100))

fn adder(n: Int) -> (Int) -> Int { |x| x + n }
var add5 = adder(5)
out(add5(2))

var seven = || 7
out(seven())

out([(1, 2), (3, 4)].map(|(a, b)| a + b))

[11, 12, 13]
[101, 102, 103]
7
7
[3, 7]

A function type is written (Int) -> Int, and that is what a parameter or a return annotation says when it holds a closure. A closure parameter may be annotated too: |x: Int| x + 1.

A closure’s environment outlives the frame that made it — adder returns one that still has n — because the environment is on the garbage-collected heap. There are no move closures, no borrow captures and no lifetime rules.

Two things a closure cannot do. It cannot name itself — a body that calls f inside var f = |n| … gets N001, because f is not in scope until its own declaration finishes, so recursion needs a fn. And it has no readable form: out on a closure prints <closure:N>, where N is how many bindings it captured — <closure:0> for one that captures nothing.

Captured by value, or through a cell

Whether a capture is a copy or a shared cell is not something you write. The compiler asks one question about the captured binding: does anything, anywhere, assign to it? A binding nothing assigns to is copied into the closure’s environment. A binding something assigns to gets a garbage-collected cell that the declaring frame and every capturing closure share, so a write on either side is seen by both.

var offset = 10
var add_offset = |x| x + offset
out(add_offset(1))
offset = 100
out(add_offset(1))

var base = 10
var add_base = |x| x + base
out(add_base(1))
var base = 100
out(add_base(1))

11
101
11
11

offset is assigned on line 4, so the closure holds a cell and sees 100. base is never assigned — the second var base is a new binding that shadows the first, with its own symbol and its own type — so add_base holds a copy of 10 and keeps answering 11.

That is the whole rule, and it is why shadowing and reassignment, which look alike, behave differently here. See bindings and shadowing for the difference. Nothing in the source declares which of the two you get: the compiler reads whether anything writes the binding, and a keyword for it would be a second statement about the program that has to agree with the first.

A for variable is a fresh binding on every step, so closures made on different steps hold different bindings rather than sharing one — they do not all end up at the last step’s value. Inside a step the rule above still applies: a loop variable the body assigns to is a reassigned binding, so that step’s closure holds that step’s cell and sees the write.

var fs = Vec()
for x in [1, 2, 3] {
    fs.push(|| x)
    x = x + 100
}
for f in fs { out(f()) }

101
102
103

A closure that returns a closure captures for it

A closure whose body is another closure captures whatever the returned one names from outside them both — not just what its own body mentions directly. It has to: the returned closure’s environment is filled from the returning closure’s frame at the moment its literal is evaluated, so the returning closure must be holding the value in order to hand it over.

var base = 10
var mk = |a| |b| a * 100 + b * 10 + base
out(mk)
out(mk(1)(2))

var deep = |a| |b| |c| a + b + c + base
out(deep(1)(2)(3))

var n = 0
var bump = |a| |b| { n = n + a + b; n }
out(bump(1)(2))
out(bump(10)(20))
out(n)

<closure:1>
130
16
3
33
33

mk prints <closure:1>: it captures one binding, base, even though nothing in |a| … names base except the closure it returns. Nesting is not a limit — deep threads the same capture down three levels — and a reassigned binding is still a single shared cell however many environments it passes through, which is why bump accumulates into one n that the outer scope reads back.

What is not captured is anything either closure declares. |a| |b| b + a captures nothing: a is the outer closure’s own parameter, and b is the inner’s. Only a name declared outside both becomes an environment slot.

A fn name in value position is a closure

Writing a function’s name without calling it produces a closure over it, with an empty environment. It can be bound, passed, stored and called like any other:

fn double(n: Int) -> Int { n * 2 }

fn apply(f, x) { f(x) }

var f = double
out(f(3))
out(apply(double, 20))
out([1, 2, 3].map(double))

6
40
[2, 4, 6]

A direct call — double(3) — is still a direct call and allocates nothing. It is only the name in value position that builds a closure, and it builds one per evaluation: var f = double inside a loop allocates on every iteration, the same as |n| double(n) would. Hoist it if that matters.

A generic function has no function value, because there is nothing at a value to specialize it against:

fn identity(x) { x }

var f = identity
out(f(3))

error[Y018]: `identity` is generic, so it has no single function value; write `|x| identity(x)` to fix its type arguments at the call

  generic-fn-as-a-value.px:3:9
  3 | var f = identity
    |         ^^^^^^^^ `identity` is generic, so it has no single function value; write `|x| identity(x)` to fix its type arguments at the call

praxis: 1 error(s)

The remedy in the message works because a closure body is a call site, and a call site is what fixes the type arguments.

How a parameter generalizes

A parameter whose type the body never pins is quantified, and the function may then be called at several types in one program:

fn identity(x) { x }

out(identity(1))
out(identity("s"))
out(identity(true))

1
s
true

Calling a method on a parameter pins it. There is one lowered body per source function, and a method call site carries exactly one catalog entry and one receiver type, so a quantified receiver would be several receiver types at one call site with no way to compile any of them. Two call sites that disagree are therefore a disagreement about the function’s signature, reported as one:

fn head(xs) { xs[0] }

out(head([1, 2, 3]))
out(head(["a", "b"]))

error[Y001]: expected (Vec[Int]) -> ?T, found (Vec[Text]) -> ?T

  parameter-pinned-by-a-method.px:4:5
  4 | out(head(["a", "b"]))
    |     ^^^^^^^^^^^^^^^^ expected (Vec[Int]) -> ?T, found (Vec[Text]) -> ?T

praxis: 1 error(s)

Annotate the parameter, or write a second function.

for over a parameter is the exception

Iterating a parameter splits the two facts. The iterable stays quantified, so one source body serves a Vec, a Range and a Set; the element is pinned, so it is one type for the whole program, even in a body that never touches it:

fn total(items) {
    var t = 0
    for i in items { t = t + i }
    t
}

var seen = Set()
seen.insert(4)
seen.insert(9)

out(total([1, 2, 3]))
out(total(0..5))
out(total(seen))

6
10
13

total is “any iterable, of Int”. The asymmetry is not a preference: a Vec and a Range are walked through different runtime accessors, so a single compiled body could not serve both — one of them would read a length out of the wrong word. One clone per iterable kind is the only way the accessors can be right. The element, in contrast, has to be one type for the loop variable’s slot to have one.

Disagreeing about the element is reported at the call site, with the operation that requires it as a note:

fn total(items) {
    var t = 0
    for i in items { t = t + i }
    t
}

out(total([1, 2, 3]))
out(total(["a", "b"]))

error[Y001]: expected Int, found Text

  iterated-parameter-mismatch.px:8:5
  8 | out(total(["a", "b"]))
    |     ^^^^^^^^^^^^^^^^^ expected Int, found Text

note: this is the operation that requires it

  iterated-parameter-mismatch.px:3:14
  3 |     for i in items { t = t + i }
    |              ^^^^^

praxis: 1 error(s)

Y001 and not “cannot be iterated”: Vec[Text] iterates perfectly well, and the body is correct for every other instantiation of total. What is wrong is t + i, at this one call. Generalization is the wider picture.

Records

A record is a fixed set of named fields. You declare one with struct, build one with a brace literal, and read a field with a dot. There is no impl block and no method syntax: a record is data, and the operations on it are the functions you write.

struct Point {
    x: Int
    y: Int
}

var p = Point { x: 3, y: 4 }
out(p)
out(p.x)

// A field is an assignable place, in every spelling an assignment has.
p.x = 5
p.y += 1
out(p)

// Field punning: `x` and `y` are already the names the fields want.
var x = 10
var y = 20
out(Point { x, y })

{ x: 3, y: 4 }
3
{ x: 5, y: 5 }
{ x: 10, y: 20 }

Fields are separated by a comma or a line break, so struct Point { x: Int, y: Int } on one line and the four-line form above are the same declaration. A trailing comma closes the list.

Note what out prints: { x: 3, y: 4 }, with no Point in front of it. A record formats as its fields.

Fields are places, and a record is an object

p.x = 5 writes the field. The binding is not what is written — the object is — so the receiver need not be a name you reassign, and every other reference to that record sees the write.

struct Point { x: Int, y: Int }

// A record value is an object. A binding names it; it does not own it, so a
// write through one name is visible through every other.
var nodes = [Point { x: 0, y: 0 }]
nodes[0].x += 1
out(nodes)

var alias = nodes[0]
alias.y = 9
out(nodes[0])

[{ x: 1, y: 0 }]
{ x: 1, y: 9 }

nodes[0].x += 1 evaluates nodes[0] once, reads the field and writes it back. min= and max= are not among the spellings a field accepts: those are map updates, and what they mean — “an absent entry accepts the first value” — is about an entry that might not be there. A field always is.

Equality, hashing and nesting come for free

Two records of the same type are equal when their fields are equal, and they hash consistently with that, so a record is a map key or a set element with no declaration on your part. Records nest.

struct Point { x: Int, y: Int }
struct Segment { label: Text, from: Point, to: Point }

// Two records of the same type with equal fields are equal, and hash alike.
var a = Point { x: 1, y: 2 }
var b = Point { x: 1, y: 2 }
out(a == b)

var seen = Set()
seen.insert(a)
seen.insert(b)
out(seen.len())

var owner = Map()
owner[a] = "north"
out(owner[b])

// Records nest, and a nested field is read through the outer one.
var s = Segment { label: "edge", from: a, to: Point { x: 4, y: 6 } }
out(s)
out(s.to.y)

true
1
north
{ label: edge, from: { x: 1, y: 2 }, to: { x: 4, y: 6 } }
6

A struct is nominal: it is the same type as itself and nothing else, so two declarations with identical fields are two types. Point { x: 1, y: 2 } == Vector { x: 1, y: 2 } does not compare unequal — it is Y001, expected Point, found Vector.

You cannot derive or implement any of this, and there is nothing to opt out of: equality, hashing and formatting are decided by the compiler from the field types.

Records are not ordered. Nothing says which field decides, so < and sorted() refuse them:

struct Point { x: Int, y: Int }

// Records are equatable and hashable. They are not ordered: nothing says which
// field decides, so `<` and `sorted()` refuse them. Sort by a key instead.
var ps = [Point { x: 2, y: 0 }, Point { x: 1, y: 9 }]
out(ps.sorted())

$ praxis check docs/book/examples/records-enums/record-cannot-be-ordered.px
error[Y006]: values of type `Point` cannot be ordered

  record-cannot-be-ordered.px:6:8
  6 | out(ps.sorted())
    |        ^^^^^^ values of type `Point` cannot be ordered

praxis: 1 error(s)

Name the field that decides and it sorts:

struct Point { x: Int, y: Int }

var ps = [Point { x: 2, y: 0 }, Point { x: 1, y: 9 }]
out(ps.sorted_by_key(|p: Point| p.x))

[{ x: 1, y: 9 }, { x: 2, y: 0 }]

A record literal must not be mistaken for a block

if p { … } is genuinely ambiguous: p { … } is a well-formed record literal, and p followed by a block is a well-formed if. The rule is that four keyword heads — if and while’s conditions, for’s iterator, match’s scrutinee — claim the brace as their block, and everywhere else a literal is legal.

struct Point { x: Int, y: Int }

var p = Point { x: 1, y: 2 }

// `if`, `while`, `for` and `match` claim the brace that follows their head, so
// a record literal there needs parentheses to say it is not the block.
if (Point { x: 1, y: 2 } == p) {
    out("same")
}

// Inside a bracket the grammar knows what closes it, so a literal is legal at
// any depth: an argument list, a match arm body, a block, a closure.
out(match p {
    Point { x: 1, y } => Point { x: 9, y: y }
    _ => p
})
out([Point { x: 0, y: 0 }].map(|q: Point| Point { x: q.y, y: q.x }))

same
{ x: 9, y: 2 }
[{ x: 0, y: 0 }]

Suppression follows the head’s operands and stops at brackets: a parenthesized expression, an argument list, a block, a record body and a match arm all re-enter with literals allowed. Writing if p == Point { x: 1, y: 2 } { … } without the parentheses is not a tidy error — the { becomes the if’s block, the field list becomes statements, and one line yields a dozen diagnostics. The fix is the parentheses.

The anonymous literal has no such ambiguity to suppress, and none of this applies to it. p { … } is ambiguous because the name could be the whole head; a { where an operand is still required cannot be a keyword’s block, because that block comes after a complete head. So if { hit: true }.hit { … } needs no parentheses. What that form has instead is its own tie with the block — { x: 1 } versus { x } — which Records without names covers.

Anonymous records

A record literal with no name in front of it — { x: 1, y: 2 } — builds a record whose type is its field set, and a named-capture template derives the same kind with no declaration anywhere. Between them this is where most records in a puzzle-shaped program come from.

// A named-capture template derives a record type with no declaration anywhere.
var points = read lines(`{x:int},{y:int}`)
out(points)
out(points[0].x)

// The derived record is an ordinary value: its fields are read by name, and a
// function that takes one need not name the type.
fn area(r) -> Int { r.x * r.y }
for r in points {
    out(area(r))
}

Given this input:

3,4
10,20

[{ x: 3, y: 4 }, { x: 10, y: 20 }]
3
12
200

An anonymous record is a type of its own. It prints as { x: Int, y: Int }, but that is a spelling diagnostics use and not one you can write as an annotation: the type grammar has no record form, so var p: { x: Int, y: Int } does not parse and an anonymous record only ever gets its type from inference — including from a { x: 1, y: 2 } literal, which is the value form and does parse. Two anonymous records are the same type when their field names match and their field types unify. A struct is not one of them, however alike the two look.

struct Point { x: Int, y: Int }

// An anonymous record is a type of its own. It is the same type as another
// anonymous record with the same field names and types, and it is never the
// same type as a `struct` that happens to look like it.
var rows = read lines(`{x:int},{y:int}`)
var p: Point = rows[0]
out(p)

$ praxis check docs/book/examples/records-enums/record-anonymous-is-not-nominal.px
error[Y001]: expected Point, found { x: Int, y: Int }

  record-anonymous-is-not-nominal.px:7:16
  7 | var p: Point = rows[0]
    |                ^^^^^^^ expected Point, found { x: Int, y: Int }

praxis: 1 error(s)

To cross the line, build the struct from the fields: Point { x: rows[0].x, y: rows[0].y }. Most programs never need to — the anonymous record already has the fields, and a function that takes one need not name its type. The type system’s side of it is Records without names.

A bare .name is a field; a zero-argument accessor is a call

p.x reads a field: it lowers to a slot index taken from the record’s definition. v.len() calls a method: it looks the name up in the catalog. The two are different syntax on purpose, and there is no property form of a method.

struct Row { len: Int }

var r = Row { len: 4 }
out(r.len)

var v = [1, 2, 3]
out(v.len())
out(v.len)

$ praxis check docs/book/examples/records-enums/record-field-is-not-a-call.px
error[Y112]: no field `len` on type `Vec[Int]`

  record-field-is-not-a-call.px:8:7
  8 | out(v.len)
    |       ^^^ no field `len` on type `Vec[Int]`

praxis: 1 error(s)

A record field may be called len and is unaffected: r.len reads it, r.len() looks for a method. v.len(), grid.width() and grid.height() all take their parentheses, and a bare one of those is Y112 naming the type it was asked of. The rule exists because a receiver whose type inference has not pinned yet cannot tell a field read from a nullary call, and picking by “whichever the receiver happens to have” would mean adding a field could silently change what an existing expression does.

What the compiler reports

A literal must supply every field, exactly once, and only fields the record has.

struct Point { x: Int, y: Int }

var missing = Point { x: 1 }
var extra = Point { x: 1, y: 2, z: 3 }
var twice = Point { x: 1, x: 2, y: 3 }
out(missing.z)

$ praxis check docs/book/examples/records-enums/record-literal-fields.px
error[Y113]: `Point` literal is missing a field: y

  record-literal-fields.px:3:15
  3 | var missing = Point { x: 1 }
    |               ^^^^^^^^^^^^^^ `Point` literal is missing a field: y

error[Y114]: `Point` has no field `z`

  record-literal-fields.px:4:33
  4 | var extra = Point { x: 1, y: 2, z: 3 }
    |                                 ^ `Point` has no field `z`

error[Y115]: field `x` is initialized more than once

  record-literal-fields.px:5:27
  5 | var twice = Point { x: 1, x: 2, y: 3 }
    |                           ^ field `x` is initialized more than once

error[Y112]: no field `z` on type `Point`

  record-literal-fields.px:6:13
  6 | out(missing.z)
    |             ^ no field `z` on type `Point`

praxis: 4 error(s)

A type cannot refer to itself

There are no recursive types. A declaration that reaches itself through its own annotations is N006, and a mutual pair is named through the member that closes the cycle.

struct Node {
    next: Node
    value: Int
}

struct A { b: B }
struct B { a: A }

out(1)

$ praxis check docs/book/examples/records-enums/record-self-referring.px
error[N006]: `Node` refers to itself, and a self-referring type is not supported

  record-self-referring.px:1:8
  1 | struct Node {
    |        ^^^^ `Node` refers to itself, and a self-referring type is not supported

error[N006]: `A` refers to itself through `B`, and a self-referring type is not supported

  record-self-referring.px:6:8
  6 | struct A { b: B }
    |        ^ `A` refers to itself through `B`, and a self-referring type is not supported

error[N006]: `B` refers to itself through `A`, and a self-referring type is not supported

  record-self-referring.px:7:8
  7 | struct B { a: A }
    |        ^ `B` refers to itself through `A`, and a self-referring type is not supported

praxis: 3 error(s)

Indirection does not help: struct Node { children: Vec[Node] } is the same N006, reported at Node. The message says the feature is missing rather than that the values are impossible, and that wording is deliberate — every field holds a reference, so a tree is a perfectly ordinary runtime shape. What is absent is recursive types in the type system. Model the tree with node ids instead: a Map[Int, Vec[Int]] of children.

One report is emitted per cycle member, and a declaration that merely sits behind a cycle is not the mistake and is not reported — in struct C { a: A } above struct A { b: B } and struct B { a: A }, only A and B are named.

What is not here

There is no generic struct: struct Box[T] { … } does not parse, and Option[T] is the one generic definition in the language — an enum, built in. There are no defaulted fields, no positional construction, no visibility modifiers, and no traits or interfaces to implement.

Taking a record apart in a pattern — including without naming its type — is pattern matching.

Enums and Option

An enum is a closed set of named variants, each optionally carrying a payload. A value is one of them and knows which. You take one apart with match, and the checker knows when you have missed a case.

enum Tile {
    Empty
    Wall
    Number(Int)
    Portal(Text)
}

// A variant is constructed by naming it. One with a payload is called.
out(Empty)
out(Number(7))
out(Portal("ab"))

var tiles = [Empty, Wall, Number(3), Portal("z")]
for t in tiles {
    out(match t {
        Empty => 1
        Wall => 0
        Number(n) => n
        Portal(_) => 100
    })
}

Empty
Number(7)
Portal(ab)
1
0
3
100

Variants are separated by a comma or a line break, so enum Tile { Empty, Wall } and the multi-line form are the same declaration. A constructor is used bare, not qualified: Empty, not Tile::Empty — there is no path syntax.

Payloads

A payload is a parenthesized list of types. There may be more than one, and the pattern names them by position.

enum Move {
    Step(Int, Int)
    Stay
}

// A payload may hold more than one value, and the pattern names them by
// position.
var m = Step(1, 2)
out(m)
out(match m { Step(dx, dy) => dx * 10 + dy, Stay => 0 })

// A wildcard stands in for a payload slot the arm does not need, and `Step(_,
// _)` is how you say "any payload". A bare `Step` is not: a variant that
// carries a payload has to say so in the pattern.
out(match m { Step(_, _) => 1, Stay => 0 })

var at = (0, 0)
for step in [Step(1, 0), Step(0, 2), Stay, Step(3, 4)] {
    at = match step {
        Step(dx, dy) => match at { (x, y) => (x + dx, y + dy) }
        Stay => at
    }
}
out(at)

Step(1, 2)
12
1
(4, 6)

Inside the parentheses you may name fewer sub-patterns than the payload has: the rest are wildcards, so Step(dx) binds the first slot and ignores the second.

Two things are Y124. Naming more than the payload has:

enum Wrapped { Wrap(Int) }

// Naming *more* sub-patterns than the payload has is `Y124`, from analysis —
// so `praxis check`, `praxis run` and the editor all report it.
fn value(w: Wrapped) -> Int {
    match w { Wrap(a, b) => a + b }
}

out(value(Wrap(1)))

$ praxis check docs/book/examples/records-enums/match-too-many-sub-patterns.px
error[Y124]: `Wrap` in `Wrapped` holds 1 value(s), but this pattern names 2

  match-too-many-sub-patterns.px:6:15
  6 |     match w { Wrap(a, b) => a + b }
    |               ^^^^ `Wrap` in `Wrapped` holds 1 value(s), but this pattern names 2

praxis: 1 error(s)

…and naming a payload-carrying variant with no parentheses at all. Stay is a pattern because Stay carries nothing; a bare Step is not:

error[Y124]: `Step` in `Move` holds 2 value(s), but this pattern names 0

help: name the payload, or `_` for each slot you do not need
      Step(_, _)

The parentheses are where you said what you were doing. A bare name says nothing about the value the variant holds, and reads exactly like the payload-less Stay beside it — which is the whole reason it is refused.

An enum declaration is not generic — a variant’s payload types are concrete — and a declaration that reaches itself through a payload type is the same N006 a self-referring record gets.

An enum value records its type

Equality is same type, same variant, equal payloads, and hashing agrees with it, so an enum value is a map key or a set element like any other.

enum Tile { Empty, Wall, Number(Int) }

// Equality is same variant and equal payloads; hashing follows it, so an enum
// value is a map key or a set element like any other.
out(Number(7) == Number(7))
out(Number(7) == Number(8))
out(Empty == Wall)

var seen = Set()
seen.insert(Number(1))
seen.insert(Number(1))
seen.insert(Empty)
out(seen.len())

true
false
false
2

“Same type” is real, not a tag comparison: a value carries a schema naming the enum it belongs to and the shape of each variant, so two enums whose variants line up are still two types. That is what makes Some(3) print as Some(3) rather than as a bare tag, what keeps an Option[Int] the runtime built from an Option[Int] the compiler built, and what lets the debugger say what it is looking at.

Statically the type checker usually gets there first. Two enums may declare the same variant name; in expression position the name resolves like any other name, so a later declaration shadows an earlier one:

enum Colour { Red, Green }
enum Light { Red, Amber }

// An enum value records which enum type it is, so a `Colour` and a `Light` are
// never the same value — and here they are not even the same type. In
// *expression* position `Red` is an ordinary name, and the later declaration
// shadows the earlier one, so this `Red` is `Light`'s.
var c: Colour = Red
out(c)

$ praxis check docs/book/examples/records-enums/enum-value-knows-its-type.px
error[Y001]: expected Colour, found Light

  enum-value-knows-its-type.px:8:17
  8 | var c: Colour = Red
    |                 ^^^ expected Colour, found Light

praxis: 1 error(s)

In pattern position there is no such problem: a variant pattern’s enum is the scrutinee’s, so match c { Red => … } and match l { Red => … } each read their own. That is in the pattern chapter.

Enums are not ordered, for the same reason records are not — nothing says which variant or which payload decides:

enum Tile { Empty, Number(Int) }

// Like records, enums are equatable and hashable but not ordered.
out([Number(1), Empty].sorted())

$ praxis check docs/book/examples/records-enums/enum-cannot-be-ordered.px
error[Y006]: values of type `Tile` cannot be ordered

  enum-cannot-be-ordered.px:4:24
  4 | out([Number(1), Empty].sorted())
    |                        ^^^^^^ values of type `Tile` cannot be ordered

praxis: 1 error(s)

Option

Option[T] is the one generic definition in the language and it is an enum: Some(T) and None. It is what the standard library answers when a value may legitimately be absent. It is not an error channel — a program that runs out of budget or indexes past the end faults; a lookup that finds nothing answers None.

// `Option[T]` is an ordinary enum with two variants, `Some(T)` and `None`. It
// is what a library answers when a value may legitimately be absent.
var counts = Map()
counts["a"] = 1

out(counts.get("a"))
out(counts.get("z"))
out(match counts.get("z") { Some(n) => n, None => 0 })

var words = ["alpha", "beta"]
out(words.find(|w| w == "beta"))
out(words.find(|w| w == "gamma"))
out(words.position(|w| w == "beta"))

out(9000000000000000000.checked_add(9000000000000000000))
out(2.checked_add(3))

// A closure may build one: `filter_map` keeps the `Some`s and drops the `None`s.
out([1, 2, 3].filter_map(|n| if n % 2 == 1 { Some(n * 10) } else { None }))

// And a function may declare one.
fn first_big(v: Vec[Int]) -> Option[Int] {
    v.find(|n| n > 1)
}
out(first_big([1, 2, 3]))

Some(1)
None
0
Some(beta)
None
Some(1)
None
Some(5)
[10, 30]
Some(2)

Some and None are ordinary constructors: you build them, annotate with Option[T], store them in collections, and match them. There are no methods on an Option — no unwrap, no is_some, no ? operator. A match is how you get the value out, and it is two tokens more than an unwrap would be.

What answers an Option

filter_map’s closure returns Option[U], which is how it drops elements.

Three near neighbours deliberately answer something else. Counter[T].get answers a plain count, because a counter’s absent value is zero rather than absent. v.min() and v.max() on an empty sequence fault: an empty minimum is a mistake in the program, not domain-level absence, and making it an Option would force an unwrap at every call site for a case the caller has already ruled out. Grid.find_all answers a Vec, which already encodes “nothing matched” as emptiness.

An Option is not the value

.get answers an Option[V], so it does not do arithmetic, index or compare as a V. This is the most common first surprise:

var counts = Map()
counts["a"] = 1

// `.get` answers an `Option`, so it is not an `Int` until a `match` takes it
// apart. Where the key is known to be present, index instead: `counts["a"]`.
out(counts.get("a") + 1)

$ praxis check docs/book/examples/records-enums/option-is-not-the-value.px
error[Y001]: expected Int, found Option[Int]

  option-is-not-the-value.px:6:5
  6 | out(counts.get("a") + 1)
    |     ^^^^^^^^^^^^^^^ expected Int, found Option[Int]

praxis: 1 error(s)

There are two spellings and you pick between them: counts.get(k) is explicit absence, and counts[k] is assertion-like access that faults on a miss. Where the key was just inserted three lines up, index. Where it might not be there, match.

Anonymous enums

The input parser’s choice constructor derives an enum with no declaration, one variant per case, each carrying the case’s own payload. It renders as its variants — { Mul({ a: Int, b: Int }) | Do(Unit) | Dont(Unit) } — and it behaves like a declared enum in every way except that it has no name to write in an annotation. Matching one is in the pattern chapter.

Pattern matching

match takes a value apart and picks the first arm whose pattern fits. Arms are separated by a comma or a line break, an arm body is any expression, and the whole match is an expression — so it is either the value of a binding or a statement, depending on where you put it.

The checker requires that the arms cover the type, and that no arm is dead. Both are the same question asked twice, and both are answered by praxis check.

struct Point { x: Int, y: Int }
enum Tile { Empty, Number(Int) }

// A literal pattern tests the value; `_` matches anything and binds nothing.
fn word(n: Int) -> Text {
    match n {
        0 => "zero"
        1 => "one"
        _ => "many"
    }
}
out(word(0))
out(word(9))

// A variant pattern tests the tag and takes the payload apart. A bare name that
// is a variant of the scrutinee's enum is that variant, not a binding.
fn cost(t: Tile) -> Int {
    match t {
        Empty => 1
        Number(n) => n
    }
}
out(cost(Empty))
out(cost(Number(6)))

// A record pattern names fields in any order, and a field it does not name is
// left alone. A punned field binds under its own name.
fn quadrant(p: Point) -> Int {
    match p {
        Point { x: 0, y: 0 } => 0
        Point { x: 0, y } => y
        Point { y: 0, x } => x * 10
        Point { x, y } => x * 100 + y
    }
}
out(quadrant(Point { x: 0, y: 0 }))
out(quadrant(Point { x: 0, y: 7 }))
out(quadrant(Point { x: 7, y: 0 }))
out(quadrant(Point { x: 1, y: 2 }))

// A tuple pattern binds by position, and patterns nest inside one another.
out(match (1, 2, 3) { (a, _, c) => a + c })
out(match Some((4, 5)) { Some((a, b)) => a * b, None => 0 })

// `true` and `false` are literal patterns, and they are the whole of `Bool`.
out(match 3 > 2 { true => "yes", false => "no" })

zero
many
1
6
0
7
70
102
4
20
yes

The pattern forms

pattern := "_"                                            // wildcard
         | literal                                        // Int, Text, Char, true, false
         | Ident                                          // binding, or payload-less variant
         | Ident "(" [pattern ("," pattern)*] ")"         // enum variant
         | Ident "{" [pattern_field ("," pattern_field)*] "}"  // record
         |       "{"  pattern_field ("," pattern_field)*  "}"  // headless record
         | "(" pattern ("," pattern)* ")"                 // tuple
pattern_field := Ident [":" pattern]

That is the whole grammar. Some notes on the edges:

• Literals are integers, text, characters, true and false. There is no float pattern, and no negative literal — -1 in pattern position is a parse error, because - is an operator and a pattern has no operators.
• _ binds nothing. It is not an identifier named _: it declares no symbol, so two _ arms are not a duplicate declaration (the second is merely unreachable), and _ has no expression form — reading one is P001: expected an expression.
• A record pattern may name fewer fields than the record has. The rest are wildcards. Naming a field the record does not have is Y114; naming one twice is Y115, field x is matched more than once, because the second binding would silently replace the first.
• P {} is a record pattern, not a binding. Bare P binds the whole value under the name P; P {} names the record and matches on it, naming none of its fields — and since a record has one constructor, that covers the type, so an arm after it is Y121.
• A headless {} is a parse error. It would bind nothing and test nothing, which is what _ is for; a second spelling of “matches everything” is how a half-written pattern becomes an irrefutable arm by accident.
• Parentheses in pattern position are always a tuple. There is no grouping form, because a pattern has no precedence to override, so (p) is a one-element tuple pattern and Y123 reports it: a tuple pattern names two elements or more. () gets the same Y123, and a parse error after it.

There are no guards. A if n > 3 => … does not parse. Put the condition in the arm body, or match on the condition.

Matching on a character

A Char pattern is a character literal, written '#' (scalars). This is the shape a grid puzzle is made of, and it is the reason the literal exists: before it, a Char had no pattern form at all — "#" in a pattern is a Text, and the scrutinee is a Char, so the arm was Y001 and there was no third thing to write.

fn cell(c: Char) -> Text {
    match c {
        '#' => "wall"
        '.' => "open"
        'S' => "start"
        _ => "unknown"
    }
}

var row = "#.S?"
for c in row {
    out(cell(c))
}

out('#' == row[0])

wall
open
start
unknown
true

Char is an open type, like Int and Text, so the _ is required — there are more characters than a match can enumerate. The last line is the equivalence that makes this a change of spelling rather than a new type: '#' and "#"[0] are the same value, and subscripting a text is still how you get a character out of one you did not write down.

Patterns are not only for match

The pattern grammar is one production, so a for header and a closure parameter take the same shapes an arm does. Neither has a second arm to fall through to, so both must be given a shape that always fits.

struct Point { x: Int, y: Int }

// The pattern grammar is one production, so a `for` header and a closure
// parameter take the same shapes a match arm does.
var points = [Point { x: 1, y: 2 }, Point { x: 3, y: 4 }]
for { x, y } in points {
    out(x * y)
}

var pairs = [(1, 10), (2, 20)]
var sum = 0
for (weight, value) in pairs {
    sum = sum + weight * value
}
out(sum)

// A closure parameter is a pattern too. This one is headless, so it needs the
// annotation to say which record it takes apart.
out(points.map(|{ x, y }: Point| x + y))

2
12
50
[3, 7]

A shape that can fail is Y125, and the message says which of the two positions it is in. Lowering is where it is caught, not analysis, so praxis check passes the file and praxis run is what reports it:

var xs = [Some(1), None]

// A `for` binding has no second arm for an item that does not fit, so a pattern
// that can fail is `Y125`. This one is lowering's too: `praxis check` is silent
// and `praxis run` reports it.
for Some(n) in xs {
    out(n)
}

$ praxis check docs/book/examples/records-enums/match-refutable-binding.px
$ praxis run docs/book/examples/records-enums/match-refutable-binding.px
error[Y125]: a `for` binding must match every item, and a variant pattern does not

  match-refutable-binding.px:6:5
  6 | for Some(n) in xs {
    |     ^^^^^^^ a `for` binding must match every item, and a variant pattern does not

praxis: 1 error(s)

A closure parameter gets the same code and a message that says a closure parameter must match every argument. A literal is refutable too, so for 1 in [1, 2, 3] is Y125 as well.

The scrutinee decides which enum a variant pattern names

A variant pattern’s enum is the scrutinee’s, not whatever the constructor name happens to resolve to elsewhere in the file. Two enums may share a variant name and each match still reads its own.

enum Colour { Red, Green }
enum Light { Red, Amber }

// A variant pattern's enum is the *scrutinee's*. Both enums have a `Red`, and
// each `match` reads its own — no annotation on the pattern, and no ambiguity.
fn colour_code(c: Colour) -> Int {
    match c { Red => 1, Green => 2 }
}

fn light_code(l: Light) -> Int {
    match l { Red => 10, Amber => 20 }
}

out(colour_code(Green))
var stop: Light = Amber
out(light_code(stop))

2
20

That is what makes the next diagnostic possible: once the enum comes from the scrutinee, a name the enum has not is a mistake with nothing else it could mean.

enum Tile { Empty, Wall, Number(Int) }

// A misspelling with a payload has nothing else it could be, so it is reported.
fn cost(t: Tile) -> Int {
    match t { Empty => 1, Wall => 2, Numbr(n) => n }
}

out(cost(Empty))

$ praxis check docs/book/examples/records-enums/match-unknown-variant.px
error[Y122]: `Tile` has no variant `Numbr`

  match-unknown-variant.px:5:38
  5 |     match t { Empty => 1, Wall => 2, Numbr(n) => n }
    |                                      ^^^^^ `Tile` has no variant `Numbr`

praxis: 1 error(s)

The one that bites: a bare name is a binding

A bare Ident is a variant only if the scrutinee’s enum has one by that name. Otherwise it is a binding — and a binding matches everything.

enum Tile { Empty, Wall, Number(Int) }

// `Wal` is not a variant of `Tile`, so it is not a variant pattern — it is a
// binding, and a binding matches everything. The match is exhaustive, nothing
// is reported, and every tile that is not `Empty` takes the second arm.
fn cost(t: Tile) -> Int {
    match t {
        Empty => 1
        Wal => 2
    }
}

out(cost(Empty))
out(cost(Wall))
out(cost(Number(9)))

1
2
2

Nothing is reported, because nothing is wrong: Wal is a legal catch-all binding. If a match you expect to be exhaustive compiles without the arm you thought you needed, look for a misspelt payload-less variant. Writing Wal(_) instead would have been Y122.

A record pattern needs no head

The head of a record pattern is optional. A headless { a, b } pins its record from the scrutinee the way a tuple pattern always has, which is the only spelling available when the record is anonymous — a choice template’s payloads have no name a head could write.

// A `choice` template derives an anonymous enum whose payloads are anonymous
// records. Neither has a name, so a pattern that wants the fields cannot write
// a head — a headless `{ a, b }` pins its record from the scrutinee instead.
var instructions = read scan(choice(
    Mul: `mul({a:int},{b:int})`,
    Do: `do()`,
    Dont: `don't()`,
))

var on = true
var total = 0
for m in instructions {
    match m {
        Mul({a, b}) => { if on { total = total + a * b } }
        Do(_) => { on = true }
        Dont(_) => { on = false }
    }
}
out(total)

// The same walk, binding the whole payload and reading its fields instead.
var sum = 0
for m in instructions {
    match m {
        Mul(p) => { sum = sum + p.a * p.b }
        Do(_) => {}
        Dont(_) => {}
    }
}
out(sum)

Given this input:

xmul(2,3)don't()mul(4,5)do()mul(6,7)

48
68

A headless pattern needs a record it can see. Field names alone do not determine a record type — the language has no row variables — so a scrutinee nothing has pinned is reported rather than silently guessed at:

// A headless record pattern needs a record it can see. Field names alone do not
// determine a record type, so a scrutinee nothing has pinned is reported.
fn total(p) -> Int {
    match p { {x, y} => x + y }
}
out(total(1))

$ praxis check docs/book/examples/records-enums/match-headless-needs-a-record.px
error[Y123]: `{ … }` cannot tell which record it matches here; name the record (`P { … }`) or annotate the value

  match-headless-needs-a-record.px:4:15
  4 |     match p { {x, y} => x + y }
    |               ^^^^^^ `{ … }` cannot tell which record it matches here; name the record (`P { … }`) or annotate the value

praxis: 1 error(s)

The message names the two ways out and both work when the record has a name: write the head (match p { Point { x, y } => … }) or annotate the value (fn total(p: Point)). Neither is available for an anonymous record. It has no name for a head, and the type grammar has no record form to annotate with — { x: Int, y: Int } is a spelling diagnostics print, not one you can write. That is why the payload of a choice is matched at the scrutinee that already knows, as above.

Exhaustiveness and reachability

A match must cover every value its scrutinee can take, and every arm must match something the arms above it do not. These are one question — is this pattern useful against the ones before it? — and it is asked at every position a value has, not only at the top level.

A type has a closed signature when its values can be enumerated: an enum’s variants, Bool’s true/false, and the single constructor a record or a tuple each have. Everything else — Int, Float, Text, Char, Unit, functions, and a type inference could not pin — is open and needs a _.

A missing case is Y120, and the message names the shapes that are missing, up to three of them, with the arms to add:

enum Tile {
    Empty
    Wall
    Number(Int)
    Portal(Text)
}

fn cost(t: Tile) -> Int {
    match t {
        Empty => 1
        Number(n) => n
    }
}

out(cost(Empty))

$ praxis check docs/book/examples/records-enums/match-non-exhaustive.px
error[Y120]: non-exhaustive match: missing `Wall`, `Portal(_)`

  match-non-exhaustive.px:9:5
  9 |     match t {
     |     ^^^^^^^^^ non-exhaustive match: missing `Wall`, `Portal(_)`...
  10 |         Empty => 1
     | ^^^^^^^^^^^^^^^^^^...
  11 |         Number(n) => n
     | ^^^^^^^^^^^^^^^^^^^^^^...
  12 |     }
     | ^^^^^

help: add the missing match arms
              Wall => panic("todo")
              Portal(_) => panic("todo")

praxis: 1 error(s)

The help: text is a machine-applicable suggestion: an editor offers it as a quick fix, and the arms it writes compile, because panic fits whatever type the other arms produced. When the scrutinee has no signature to enumerate the message says missing a _ catch-all arm instead, because there is no shape to name.

Coverage goes through constructors, not just up to them. A one-variant enum does not make every match on it exhaustive:

enum Flag { On, Off }
enum Wrapped { Wrap(Flag) }

// Coverage is asked at every position a value has, not only at the top level:
// `Wrap` is named, and the `Off` inside it is not.
fn on(w: Wrapped) -> Int {
    match w { Wrap(On) => 1 }
}

out(on(Wrap(On)))

$ praxis check docs/book/examples/records-enums/match-non-exhaustive-payload.px
error[Y120]: non-exhaustive match: missing `Wrap(Off)`

  match-non-exhaustive-payload.px:7:5
  7 |     match w { Wrap(On) => 1 }
    |     ^^^^^^^^^^^^^^^^^^^^^^^^^ non-exhaustive match: missing `Wrap(Off)`

help: add the missing match arms
          Wrap(Off) => panic("todo")

praxis: 1 error(s)

An arm that can never run is Y121. The obvious case is an arm after a catch-all:

enum Tile { Empty, Wall, Number(Int) }

fn cost(t: Tile) -> Int {
    match t {
        Empty => 1
        _ => 0
        Number(n) => n
    }
}

out(cost(Empty))

$ praxis check docs/book/examples/records-enums/match-unreachable.px
error[Y121]: unreachable match arm

  match-unreachable.px:7:9
  7 |         Number(n) => n
    |         ^^^^^^^^^^^^^^ unreachable match arm

praxis: 1 error(s)

The less obvious ones are a repeated constructor (A => 1, A => 2) and a nested pattern an earlier arm already subsumed (Some(n) followed by Some(_)) — the same walk finds all three.

The two halves meet at a record: a record has exactly one constructor, so naming it covers the type, and a _ after it is dead.

struct Point { x: Int, y: Int }

// A record has one constructor, so naming it covers the type: the `_` below can
// never run, and an arm that can never run is an error.
fn sum(p: Point) -> Int {
    match p {
        Point { x, y } => x + y
        _ => 0
    }
}

out(sum(Point { x: 1, y: 2 }))

$ praxis check docs/book/examples/records-enums/match-record-needs-no-catch-all.px
error[Y121]: unreachable match arm

  match-record-needs-no-catch-all.px:8:9
  8 |         _ => 0
    |         ^^^^^^ unreachable match arm

praxis: 1 error(s)

match p { Point { x: 0, y } => y } is the other half of the same fact: the constructor is covered, the 0 inside it is not, and the witness names the shape — missing `Point { x: _, y: _ }`.

An unreachable arm still covers what it names, whether or not it can run, so { _ => 1, A => 2 } does not then report a missing B on account of the arm it has just rejected.

Where the check runs

Y120 and Y121 come from analysis, which means praxis check, praxis run and the language server all see them at the same place with the same message. The editor underlines the match and offers the arms.

The check runs after inference rather than inside it, because a scrutinee’s type is not final while inference is still on the stack: a match on an unannotated parameter can be pinned by a call further down the file, and a coverage answer given against a type variable would be a Y120 demanding a _ the program does not need.

So does every other pattern mistake: a payload the pattern does not fit (Y124), and a pattern that can fail in a for header or a closure parameter (Y125). Every diagnostic a well-formed program can earn is analysis’s, so the editor underlines all of them as you type.

Collections

Praxis ships ten collections and no way to define an eleventh. They are built into the compiler: each one is a fixed set of rows in the method catalog, with a runtime representation the collector knows how to trace. There are no traits, no generic containers you write yourself, and no imports — every name below is already in scope.

Grid[T] is covered in grids and graphs, because everything interesting about it is two-dimensional. Text is a scalar rather than a collection, but it subscripts and iterates like one; see Text and Char.

Tuples are not in the table — they are a structural type rather than a collection — but they are what makes Map[(Int, Int), T] work, so they are described below.

Constructing a collection

Every collection but Range is built by calling its name:

var v = Vec()
var q = Deque()
var m = Map()
var s = Set()
var counts = Counter()
var lo = MinHeap()
var hi = MaxHeap()
var bits = BitSet()

The element types come from what the program later puts in. When that is not enough — or when you would rather say it than derive it — write the type arguments in brackets before the parentheses:

var counts = Counter[(Int, Int)]()
var ages = Map[Text, Int]()

Those brackets are type arguments, not a subscript, because the name in front is a compiler-owned type constructor. That is the whole rule, and its price is stated rather than hidden: a var binding that shadows one of the ten constructor names cannot be subscripted. The arguments unify with the call’s own variables, so a disagreement is reported at the use that disagrees:

var c = Counter[Text]()
c.inc(1)

$ praxis check type-arg-mismatch.px --color never
error[Y001]: expected Text, found Int

  type-arg-mismatch.px:2:7
  2 | c.inc(1)
    |       ^ expected Text, found Int

praxis: 1 error(s)

Substituting the annotation instead of unifying would have made it win silently; inferring first and then comparing would have reported at the constructor, which is not where the mistake is. The wrong number of arguments is Y007:

error[Y007]: `BitSet` takes 0 type argument(s), but 1 were given

Building one at a size

Vec and Grid also take a size and a fill, which is how you get the working collection an algorithm allocates for itself — an occupancy board, a visited mask, a distance table, a DP row:

// `Vec(n, fill)` and `Grid(w, h, fill)`: the collection an algorithm allocates
// for itself, rather than one it reads or grows a push at a time.
var row = Vec(5, 0)
var board = Grid(3, 2, '.')
board[1, 1] = '#'

out(row)
out(board)
out(board.width())
out(board.height())

[0, 0, 0, 0, 0]
[., ., ., ., #, .]
3
2

The element type comes from the fill, so Vec(3, false) is a Vec[Bool] with nothing written down, and the bracket form composes with it when you would rather say it: Vec[Bool](3, false).

Only those two have a sized form. The other seven take no arguments at all, and Set(3, 0) is an error saying so. Praxis has no arity overloading anywhere else — one name, one signature — and these two are a deliberate, closed exception. Vec and Grid are the collections whose contents are addressed by position, which is what makes “n of them” mean something: a sized Set would be n copies of one element in a set, which is one element. The exception costs the general rule nothing: the shape is chosen by counting the arguments, a syntactic fact known before any argument is typed, and never by looking at what they are.

The fill is one value stored n times, not n copies of it. For a scalar that is unobservable, but a collection fill gives you n names for the same collection:

// The fill is one value stored in every slot, not one copy per slot — the same
// reference semantics `var b = a` has. A push into any cell is visible from all
// four, because they are the same `Vec`.
var cells = Grid(2, 2, Vec())
cells[0, 0].push(1)
out(cells[1, 1])

[1]

That is the same reference semantics a collection already has everywhere else: a binding names an object rather than owning it, so var b = a does not copy and neither does this. If you want n distinct collections, build them: (0..n).map(|_| Vec()).

A negative size — or one so large the runtime cannot allocate it — is not something praxis check can refuse, because the size is an ordinary Int computed at run time. It is a fault instead, and the expression that asked for it is named in the report:

// A size is an ordinary `Int` computed at run time, so a negative one is not
// something `praxis check` can refuse. It is a fault.
var n = 0 - 1
var v = Vec(n, 0)
out(v)

error: program faulted: size or extent out of range

Backtrace:
#0   <entry>

  locals:
    n: Int = -1
    v: Vec[Int] = <uninit>
  temps:
    <tmp#1: Int> @ "0" = 0
    <tmp#2: Int> @ "1" = 1
    <tmp#3: Int> @ "0 - 1" = -1
    <tmp#5: Int> @ "0" = 0
    <tmp#6: Vec[Int]> @ "Vec(n, 0)" = <uninit>

The ceiling is 2²⁸ items, which is two gigabytes of references before a single element object exists — a judgement about what a program plausibly asks for rather than what a usize happens to hold.

The list literal

Vec is the one collection with a literal. [a, b, c] is Vec() followed by one push per element, in source order — same type, same methods, same mutability. There is no separate immutable array.

// A list literal is a Vec: an allocation followed by one push per element.
var v = [3, 1, 2]
v.push(4)
v[0] = 30

out(v)
out(v.len())
out(v[1])
out(v.get(3))
out(v.is_empty())

// An empty literal has no element to read a type from, so the use decides —
// here, an annotation.
var names: Vec[Text] = []
names.push("ada")
out(names)

[30, 1, 2, 4]
4
1
4
false
[ada]

Inference mints one fresh element variable and unifies each element with it in turn, so [] is the ordinary case rather than an exception, and a mixed literal reports at the element that disagrees: [1, "a"] is error[Y001]: expected Int, found Text under the "a".

A [ that begins an expression opens a literal; a [ that continues one subscripts. Position is the whole tie-break, which means a subscript has to be written on one line with its receiver — a v at the end of one line and a [i] at the start of the next is two statements, a value and a list literal that goes nowhere, and nothing reports it.

Subscripting

A subscript is a method-catalog row dispatched on the receiver’s shape and its arity, under names no program can spell. Six types read; five of those six also store.

Set, the heaps, BitSet and Range have no subscript at all, and there is no slicing anywhere — an index is a single Int, so v[0..2] is a type error (expected Int, found Range) rather than a slice. s[0] on a Set[Int] is:

error[Y020]: values of type `Set[Int]` cannot be indexed with 1 index(es)

Because it goes through the same dispatch a method call does, a subscript is exactly as generic as a method call, and no more: a function that indexes an unannotated parameter infers, and the first call site decides what the parameter was. Passing a second receiver kind through the same function is a disagreement about that function’s signature rather than a second instantiation — given fn first(c, k) { c[k] }, calling it on both a Map[Text, Int] and a Vec[Int] reports:

error[Y001]: expected (Map[Text, Int], Text) -> ?T, found (Vec[Int], Int) -> ?T

A missing Map key faults

m[k] is the assertion-like read and m.get(k) is the one that answers with absence. They are two different catalog rows pointing at two different runtime wrappers, so the choice is the program’s.

// A subscript is dispatched exactly like a method call, so `m` and `k` need no
// annotation: the call site below is what says they are a `Map[Text, Int]` and
// a `Text`.
fn lookup(m, k) {
    m[k]
}

var ages = Map[Text, Int]()
ages["ada"] = 36
out(lookup(ages, "grace"))

error: program faulted: index out of bounds

Backtrace:
#0   lookup
#1   <entry>

  locals:
    m: Map[Text, Int] = {"ada": 36}
    k: Text = "grace"
  temps:
    <tmp#3: Int> @ "m[k]" = <uninit>

The fault kind is IndexOutOfBounds — an index the collection does not hold. A dedicated MissingKey would read better and does not exist. Run without --debug never and that snapshot becomes an interactive session; see the fault model.

A Counter read never faults, which is the whole point of the type: an absent key reads as zero, and that is what makes counts[k] += 1 work on a key never seen before.

Stores replace, and compound stores evaluate the place once

A Vec or Deque store replaces the element at that index and never appends. v[v.len()] = x is a fault, not a push:

fn store(v, i, x) {
    v[i] = x
}

var v = [1, 2, 3]
store(v, v.len(), 4)
out(v)

That program faults with index out of bounds. push is the spelling that grows a sequence.

m[k] += v is not desugared into m[k] = m[k] + v. The receiver and every index are lowered once into locals that both the read and the write use, so m[f()] += 1 calls f exactly once.

min= and max=

Map has two updating stores, and they exist because a read-modify-write cannot express them: an absent entry accepts the first value, where a plain subscript read of an absent key would fault.

var distance = Map[Text, Int]()

// An absent entry accepts the first value, so no key has to be seeded.
distance["b"] min= 7
distance["b"] min= 4
distance["b"] min= 9
out(distance["b"])

var best = Map[Text, Int]()
best["b"] max= 7
best["b"] max= 4
best["b"] max= 9
out(best["b"])

4
9

Three constraints on the form. The value type must be Int — the wrappers compare through the integer payload, so m["a"] min= "y" is error[Y001]: expected Int, found Text. Map is the only receiver, and a Counter gets its own message rather than the plain-store one:

error[Y020]: values of type `Counter[?T]` cannot be updated with `min=` through 1 index(es)

And the operator is contextual and adjacent: min and max are still ordinary prelude functions, so it is the = touching the identifier that makes the pair an operator. d[k] min = 3, with a space, is two statements run together, and reports as such.

Vec

get(i) and v[i] are two spellings of one row and behave identically — neither answers an Option, and both fault out of range. There is no contains, pop, insert, remove, first or last; the pipeline stages (any, find, position, sorted, …) are where those questions get asked. Reversing is one of them: v.reversed() answers a new Vec and leaves the receiver alone, and there is no in-place reverse. The example under the list literal exercises every row above.

to_text() is the odd one out on this table, because it is the only row here that is not about a Vec of anything — a Vec[Char] becomes the line it spells, which is how a Grid row is drawn back.

Deque

var queue = Deque()
queue.push_back("b")
queue.push_back("c")
queue.push_front("a")

out(queue)
out(queue.len())
out(queue[0])

queue[1] = "B"
out(queue.pop_front())
out(queue.pop_back())
out(queue)

[a, b, c]
3
a
a
c
[B]

Map

var ages = Map[Text, Int]()
ages["ada"] = 36
ages["alan"] = 41
ages["ada"] += 1

out(ages)
out(ages["ada"])
out(ages.len())
out(ages.contains("alan"))
out(ages.keys())
out(ages.values())

match ages.get("grace") {
    Some(n) => out(n)
    None => out("no entry for grace")
}

ages.remove("alan")
out(ages)

{ada: 37, alan: 41}
37
2
true
[ada, alan]
[37, 41]
no entry for grace
{ada: 37}

keys() and values() share one ordering, so they are index-aligned. To get both halves joined, iterate the map or call to_vec(), which answers the (K, V) pairs.

Set

var seen = Set()
seen.insert(3)
seen.insert(1)
seen.insert(3)

out(seen)
out(seen.len())
out(seen.contains(1))
out(seen.contains(2))

seen.remove(1)
out(seen)
out(seen.is_empty())

{1, 3}
2
true
false
{3}
false

There are no set operations — no union, intersection or difference. A filter over one and to_set() on the result is the spelling.

Counter

A Counter[T] is a map from T to Int whose absent values read as zero.

var counts = Counter[Text]()
for word in ["the", "cat", "the", "sat"] {
    counts[word] += 1
}
counts.inc("cat")

out(counts)
out(counts["the"])
out(counts.len())
out(counts.keys())
out(counts.values())

// An absent key reads as zero, does not fault, and creates nothing.
out(counts["dog"])
out(counts.len())

// A store is not zero-defaulting: it sets the count outright, and a stored
// zero is an entry like any other.
counts["dog"] = 0
out(counts.len())
out(counts)

{cat: 2, sat: 1, the: 2}
2
3
[cat, sat, the]
[2, 1, 2]
0
3
4
{cat: 2, dog: 0, sat: 1, the: 2}

Reading an absent key does not create it — len() is 3 before and after counts["dog"]. Storing one does, even a zero. If you want a counter built from a sequence in one call, frequencies() is it; see pipelines.

MinHeap and MaxHeap

var lo = MinHeap()
for n in [5, 1, 3] {
    lo.push(n)
}
out(lo.peek())
out(lo.pop())
out(lo.pop())
out(lo.len())

var hi = MaxHeap[Int]()
for n in [5, 1, 3] {
    hi.push(n)
}
out(hi.peek())

// Walking a heap does not drain it: the loop reads a snapshot in pop order.
for n in hi {
    out(n)
}
out(hi.len())
out(hi.is_empty())

1
1
3
1
5
5
3
1
3
false

A heap’s element type must be orderable, and no composite is. Only Int, Float, Char and Text are ordered, so the Dijkstra habit of pushing a (cost, node) pair does not compile:

var frontier = MinHeap()
frontier.push((3, "b"))

$ praxis check heap-of-pairs.px --color never
error[Y006]: values of type `(Int, Text)` cannot be ordered

  heap-of-pairs.px:2:10
  2 | frontier.push((3, "b"))
    |          ^^^^ values of type `(Int, Text)` cannot be ordered

praxis: 1 error(s)

The requirement rides on the receiver’s type, not on push, so it is enforced wherever the heap’s element type gets pinned. For weighted shortest paths, reach for the dijkstra helper in grids and graphs instead of building the frontier by hand.

BitSet

A compact set of non-negative Ints. Members are bit positions, not objects, so there is no element type and BitSet[Int]() is an arity error.

var bits = BitSet()
bits.insert(64)
bits.insert(1)
bits.insert(300)
bits.insert(1)

out(bits)
out(bits.len())
out(bits.contains(64))
out(bits.contains(65))

// Members come out in ascending numeric order.
for n in bits {
    out(n)
}

bits.remove(64)
out(bits)
out(bits.is_empty())

{1, 64, 300}
3
true
false
1
64
300
{1, 300}
false

A member outside 0..=4294967295 faults with size or extent out of range.

Range

a..b is the integers from a up to but not including b; a..=b includes b. Both build the same value — the inclusive form is normalized into its half-open equivalent, which is why 1..=4 prints as 1..5.

A Range has no methods at all, and no subscript:

error[Y110]: no method `len` on type `Range` taking 0 argument(s)

What it has is iteration, and therefore every pipeline stage — which is where count() and sum() below come from.

out(1..4)
out(1..=4)

for i in 1..4 {
    out(i)
}

out((1..4).count())
out((1..4).sum())

// A descending range is empty, not a countdown. The countdown is a barrier.
out((5..0).count())
out((0..5).reversed())

// A Range has no mutator, so it is usable as a Map key.
var spans = Map()
spans[1..4] = "first three"
out(spans[1..4])

1..4
1..5
1
2
3
3
6
0
[4, 3, 2, 1, 0]
first three

A descending range is empty rather than reversed, matching Python and Rust. There is no step or stride form, and 5..0 earns no diagnostic — it is a legal empty collection, and the constructor clamps rather than the literal being refused.

The countdown is written (0..5).reversed(), which answers a Vec[Int] because a pipeline’s currency is Vec — not a descending Range, since no such value exists. See barriers for why reversal needs the whole sequence.

Tuples

A tuple is an anonymous positional product: (a, b), elements read as .0, .1, and so on. Its identity is structural — the element type sequence alone — so two (Int, Int)s built anywhere in the program compare and hash as the same shape.

var point = (3, 4)
out(point)
out(point.0)
out(point.1)

// A tuple's identity is structural: same elements, same value.
out((3, 4) == point)
out((4, 3) == point)

// Mixed element types are fine, and the arity is part of the shape.
var row = ("ada", 36, true)
out(row.1)

// Tuples key a Map, which is what makes (x, y) coordinates work.
var grid = Map()
grid[(0, 0)] = "start"
grid[(3, 4)] = "goal"
out(grid[point])
out(grid.len())

(3, 4)
3
4
true
false
36
goal
2

A tuple element is not an assignable place: t.0 = 1 is error[Y021]: the left side of an assignment must be a name, a field, or an index. And no tuple is orderable, so a Vec of pairs has no sorted() — sorted_by_key(|p| p.1) is the spelling, and pattern matching is how a pair gets destructured into names.

Iteration and its order

Every collection is iterable, and so is a Text. The order is fixed and seed-independent — a program’s answer never depends on a hash table’s per-process seed.

“Ascending” is the value’s order, not the printed text’s: numeric for Int and Float, code-point for Char and Text, false before true, and element-wise left to right for a tuple, a record or an enum. It is the same order sorted() uses, so out(s) and out(s.to_vec().sorted()) print the same sequence, and a Map[(Int, Int), V] over a grid comes out in reading order.

Every key type has such an order, including the ones you cannot write < on: a tuple orders inside a container and (1, 2) < (1, 3) is still refused at check time. Ordering a container is a question about determinism; < is a question about the language.

// A hashed collection walks its members in the *value's* order, not in the
// order they print: 2 before 10, and the same sequence on every run.
var seen = Set()
for n in [1, 2, 10, 20, 3] {
    seen.insert(n)
}
out(seen)
for n in seen {
    out(n)
}

// keys() and values() share that one order, so they are index-aligned.
var m = Map()
m[1] = "one"
m[10] = "ten"
m[2] = "two"
out(m.keys())
out(m.values())

// A `for` over a keyed collection yields the (key, value) pair itself.
for kv in m {
    out(kv.1)
}

// A keyed collection prints in the order it iterates: one order, not two.
var names = Map()
names["a"] = 1
names["a1"] = 2
out(names)
out(names.keys())

// A tuple key orders element-wise, left to right — which is what makes a
// Map[(Int, Int), V] over a grid come out in reading order.
var grid = Map()
grid[(1, 10)] = "b"
grid[(1, 9)] = "a"
grid[(0, 100)] = "z"
out(grid)

{1, 2, 3, 10, 20}
1
2
3
10
20
[1, 2, 10]
[one, two, ten]
one
two
ten
{a: 1, a1: 2}
[a, a1]
{(0, 100): z, (1, 9): a, (1, 10): b}

A keyed collection prints in the order it iterates. One Map has one order: out(m), keys(), values() and a for all walk it by the key’s own value, so a comes before a1 in every one of them. A collection that sorted its printed entries instead would put a1: 2 before a: 1, because 1 sorts before :, and a program that printed a map would disagree with a program that walked it.

The last column of the table is not decoration. A collection walked in place re-reads its length each step, so a push from inside the loop body is visited; a snapshotted one is materialized once before the first step and cannot be affected by the body at all.

// A Vec indexes itself, so a `for` over it re-reads the length each step and
// sees an element pushed by the body.
var v = [1, 2, 3]
for x in v {
    if x == 1 {
        v.push(99)
    }
    out(x)
}

// A Set does not: the loop walks a snapshot taken once, before the first step.
var s = Set()
s.insert(1)
for x in s {
    s.insert(2)
    out(x)
}
out(s)

1
2
3
99
1
{1, 2}

What may be a Map key or a Set element

A key must be hashable and immutable. The rule is mutability, not container-ness:

• In: every scalar, Text, Range, and — structurally — tuples, records and enums, each a key exactly when all of its components are.
• Out: Vec, Deque, Map, Set, Counter, MinHeap, MaxHeap, BitSet, Grid, and any function.

struct Point { x: Int, y: Int }

enum Dir { North, South }

// A key type is fixed by the first use, so each of these is its own Map.
var by_int = Map()
by_int[7] = "an Int"

var by_text = Map()
by_text["k"] = "a Text"

var by_tuple = Map()
by_tuple[(1, 2)] = "a tuple of Ints"

var by_record = Map()
by_record[Point { x: 1, y: 2 }] = "a record of Ints"

var by_enum = Map()
by_enum[North] = "an enum with no payload"

var by_range = Map()
by_range[1..4] = "a Range"

out(by_int[7])
out(by_text["k"])
out(by_tuple[(1, 2)])
out(by_record[Point { x: 1, y: 2 }])
out(by_enum[North])
out(by_range[1..4])

an Int
a Text
a tuple of Ints
a record of Ints
an enum with no payload
a Range

A mutable one is refused at check time, at the operation that stores it, in concrete terms:

var seen = Set()
seen.insert([1, 2])

$ praxis check mutable-key.px --color never
error[Y014]: a value of type `Vec[Int]` can change after it is stored, so it cannot be used as a key

  mutable-key.px:2:6
  2 | seen.insert([1, 2])
    |      ^^^^^^ a value of type `Vec[Int]` can change after it is stored, so it cannot be used as a key

help: use a value that cannot change — a number, `Text`, or a tuple of those

praxis: 1 error(s)

The requirement is on the collection’s key type rather than on insert, so it reaches through an unannotated parameter too. Given fn store(m, k) { m.insert(k, 1) }, a call store(m, [1, 2]) reports the same Y014 at the insert inside store, naming the Vec[Int] the call site put in k’s place.

The one hole in the rule

A record is accepted as a key, and a record field is assignable. Mutating a field of a key already stored moves the entry’s bucket without moving the entry:

struct Point { x: Int, y: Int }

var p = Point { x: 1, y: 2 }
var seen = Set()
seen.insert(p)
out(seen.contains(p))

// A field store changes the value the set hashed. The entry is still there —
// it is just no longer reachable by its own key.
p.x = 99
out(seen.contains(p))
out(seen.len())
out(seen)

true
false
1
{{ x: 99, y: 2 }}

The entry is still in the set and still prints, and nothing will ever find it again. Build a fresh record instead of storing into one you have used as a key. This is the exact hazard the mutable-container rule exists to prevent; the compiler does not catch it for records.

Conversions, and what is not here

Every collection converts to eight of the ten, by naming what it becomes: to_vec, to_set, to_map, to_counter, to_deque, to_min_heap, to_max_heap, to_bitset. These are pipeline sinks and are documented in pipelines, along with the stages that get you there. Two notes belong here:

• The two missing ones are Grid and Range. There is no to_grid() — a grid needs a width and an item sequence does not carry one — and no to_range(), because a Range is written a..b rather than built from members.
• The conversion has to typecheck: to_map needs an item that is a (K, V) pair and to_counter a (T, Int) pair, so [1, 2, 2].to_counter() reports expected (?T, Int), found Int. frequencies() is the call that counts.
• Two conversions leave the collections entirely and answer a Text: seq.join(sep) on a sequence of Text, and chars.to_text() on a Vec[Char]. They are two rows rather than one because a generic join and a Char-specific one cannot both exist under one name.

Also absent, and a reader coming from Python or Rust will look for them: Vec.contains / pop / insert / remove, in-place reverse and sort (reversed() and sorted() answer new Vecs instead), set algebra, Deque.rotate, and a Range with a step. Each is a Y110 naming the receiver and the arity, so the compiler says which method on which type it could not find rather than guessing:

error[Y110]: no method `contains` on type `Vec[Int]` taking 1 argument(s)

Pipelines

A pipeline is a chain of method calls that walks a sequence of values: a source, some stages that transform the elements one at a time, and a sink that answers with a single value. The compiler knows every one of these methods by name and compiles a chain of them into a single loop over the source.

Two things distinguish it from the iterator chains you may be used to. It is eager — it runs where it is written, not where its result is consumed. And it materializes on its own — a chain that stops without a sink is already a Vec, so there is no collect.

A chain, from source to sink

// The shape of every pipeline: a source, some stages, and a sink.
var readings = [3, -1, 4, 1, -5, 9, 2, 6]

// A sink ends the chain and answers a scalar.
out(readings.filter(|x| x > 0).map(|x| x * x).sum())

// The same chain, one stage per line. A leading `.` continues the
// expression across the newline that would otherwise end the statement.
var answer = readings
    .filter(|x| x > 0)
    .map(|x| x * x)
    .sum()
out(answer)

// No sink: the chain still ends, and what it ends as is a Vec.
out(readings.filter(|x| x > 0).map(|x| x * x))

// `count` has two arities: every element, or the matching ones.
out(readings.count())
out(readings.count(|x| x < 0))

147
147
[9, 16, 1, 81, 4, 36]
8
2

The arguments are ordinary closures. Nothing about a closure changes because it is written inside a chain, and a closure bound to a variable works as well as one written in place.

A pipeline’s source is the for loop’s

The receiver of a pipeline is what a for loop walks, and it yields exactly what the loop’s variable would bind. There are ten of them, one short of the for loop’s own list:

// A pipeline's item is the `for` loop's variable. The same source, twice.
var m = Map()
m["a"] = 1
m["b"] = 2

var loop_total = 0
for kv in m {
    loop_total = loop_total + kv.1
}
out(loop_total)
out(m.map(|kv| kv.1).sum())

// Same order, too. Both walks read the same deterministic snapshot.
for kv in m {
    out(kv.0)
}
out(m.map(|kv| kv.0))

3
3
a
b
[a, b]

Iteration order is deterministic and seed-independent for every receiver — a Set walked twice in one run, or in two runs, yields the same order — so a pipeline’s answer is a function of its input alone.

Here is one chain over each of the ten:

// One chain over each of the ten things a pipeline can start from.
// Vec[T] and Deque[T] yield T.
out([3, 1, 2].map(|x| x * 10).sum())

var d = Deque()
d.push_back(10)
d.push_front(20)
out(d.to_vec())

// Set[T], MinHeap[T] and MaxHeap[T] yield T, from a snapshot in a
// deterministic order.
var s = Set()
s.insert(3)
s.insert(1)
s.insert(2)
out(s.filter(|x| x > 1).sorted())

var lo = MinHeap()
lo.push(5)
lo.push(2)
out(lo.sum())

var hi = MaxHeap()
hi.push(5)
hi.push(2)
out(hi.max())

// Range and BitSet yield Int.
out((1..6).map(|n| n * n).sum())

var bits = BitSet()
bits.insert(2)
bits.insert(5)
out(bits.to_vec())

// Text yields Char — the same value `t[i]` answers.
out("mississippi".count(|c| c == 's'))
out("hello".filter(|c| c != 'l').to_vec())

// Map[K, V] yields (K, V), and Counter[T] yields (T, Int).
var m = Map()
m["a"] = 1
m["b"] = 2
out(m.map(|kv| kv.1).sum())
out(m.to_vec())

var tally = ["the", "cat", "the", "dog", "the"].frequencies()
out(tally.filter(|(word, n)| n > 1).map(|(word, n)| word))

60
[20, 10]
[2, 3]
7
5
55
[2, 5]
4
[h, e, o]
3
[(a, 1), (b, 2)]
[the]

Grid[T] is the one iterable that is not a pipeline receiver. A grid’s shape is part of its value, so grid.map(fn) does not resolve at all rather than quietly answering a flat sequence. A grid enters a pipeline through grid.cells() or grid.positions(), which already answer Vecs — see grids and graphs.

The catalog

Everything below is a row in the method catalog, keyed by receiver, name and arity — one row per combinator, shared by all ten receivers. T is the item type; U, K, V and Acc are fresh.

Streaming stages. Each transforms one element at a time and answers a Vec.

Sinks. Each ends the chain with one value.

Conversions. Also sinks, so they fuse into the same loop.

Barriers. These need the whole sequence before they can answer their first element, so they are not fused: a chain ends at one and begins again from its result.

reversed is the barrier with an empty requirement column, and that is its own claim rather than an omission: sorted reads the element’s compare callback and unique reads its hash and equals, while reversal reads nothing at all — so a Vec of closures reverses where it cannot be sorted. It is also what a countdown is written with: for i in (0..n).reversed(), since n..0 is an empty range rather than a descending one.

join is the one barrier that answers a scalar rather than a sequence. Its separator is a required argument, because the catalog has no optional ones — join("") is the no-separator spelling and says so where it is written — and it renders nothing: [1, 2].join(",") is expected Text, found Int, and the spelling is [1, 2].map(|n| n.to_text()).join(","). A sequence of Char uses to_text() instead, which is a Vec[Char] row rather than a pipeline one.

chunks and windows are the two that answer a sequence of sequences, and what separates them is what happens to a group that does not fill. A chunking partitions: every element appears once, in order, and a length the size does not divide leaves a short last chunk. A window slides by one and keeps only the runs that fit, so a sequence shorter than the size answers [].

// The two barriers that answer a sequence of sequences.
var v = [1, 2, 3, 4, 5]

// A chunking partitions: every element once, and a short last chunk.
out(v.chunks(2))
// A window slides by one and keeps only the runs that fit.
out(v.windows(2))
// Larger than the sequence: one short chunk, and no windows at all.
out(v.chunks(9))
out(v.windows(9))

// What they are for: "compare each element with its neighbour".
out(v.windows(2).count(|p| p[1] > p[0]))

// A group is a sequence in its own right, so the chain continues on it.
out(v.windows(2).map(|p| p.sum()))
out(v.chunks(2).map(|c| c.count()))

[[1, 2], [3, 4], [5]]
[[1, 2], [2, 3], [3, 4], [4, 5]]
[[1, 2, 3, 4, 5]]
[]
4
[3, 5, 7, 9]
[2, 2, 1]

Both names are plural because both answer many things, which is what every other such row in the catalog is called: frequencies, positions, cells, keys, items.

Groups share their elements rather than copying them. The 2 in v.windows(2)’s first group and the 2 in its second are one object, which is the same aliasing var b = a already has.

Both fault on a size of zero or less, and that is the only thing either refuses. A run of zero elements is not a short run — chunking a non-empty sequence into them has no finite answer — and a negative one names nothing. A size larger than the sequence is not that fault, as the example above shows: chunks answers one short chunk and windows answers none.

// A run of zero elements is not a short run, so there is no sequence of them.
var v = [1, 2, 3]
out(v.chunks(0))

error: program faulted: size or extent out of range

Backtrace:
#0   <entry>

  locals:
    v: Vec[Int] = [1, 2, 3]
  temps:
    <tmp#1: Vec[Int]> @ "[1, 2, 3]" = [1, 2, 3]
    <tmp#2: Int> @ "1" = 1
    <tmp#3: Unit> = Unit
    <tmp#4: Int> @ "2" = 2
    <tmp#5: Unit> = Unit
    <tmp#6: Int> @ "3" = 3
    <tmp#7: Unit> = Unit
    <tmp#9: Int> @ "0" = 0
    <tmp#10: Vec[Vec[Int]]> @ "v.chunks(0)" = <uninit>
    <tmp#11: Unit> @ "out(v.chunks(0))" = <uninit>

The Vec[Vec[Int]] in that report is the answer’s real type: a group is a sequence, not a flattened run of elements, and <uninit> is the slot the fault left unwritten.

sum, product, min and max are Int operations, not generically numeric. [1.5, 2.5].sum() is error[Y001]: expected Int, found Float. For anything else, min_by and max_by take a “less-than” comparator and work at any element type.

Each stage counts its own input

A stage cannot see the source. It sees what the stage before it handed it, and that is what take, skip, enumerate, zip and position count.

// Every stage that asks "which element is this?" counts its own input, not
// the source's.
var v = [1, 2, 3, 4, 5, 6, 7, 8]
var evens = |x| x % 2 == 0

// The first two survivors, not the survivors among the first two.
out(v.filter(evens).take(2))
out(v.filter(evens).skip(1))

// 0, 1, 2, 3 — the numbering the filter handed on.
out(v.filter(evens).enumerate())

// Paired with the argument's 0th, 1st, 2nd element.
out(v.filter(evens).zip(["a", "b", "c"]))

// The index among the evens: 6 is the third one.
out(v.filter(evens).position(|x| x == 6))

// A splice flattens, and the count keeps running across it.
out(v.take(3).flat_map(|x| [x, x * 10]).enumerate())

[2, 4]
[4, 6, 8]
[(0, 2), (1, 4), (2, 6), (3, 8)]
[(2, a), (4, b), (6, c)]
Some(2)
[(0, 1), (1, 10), (2, 2), (3, 20), (4, 3), (5, 30)]

The bound take and skip take is an ordinary Int expression, evaluated once before the loop. Degenerate bounds mean what they read as: take(0) and take(-1) are empty, skip(-1) drops nothing.

zip’s argument and flat_map’s closure result are Vecs specifically, not the ten receivers. The fused loop indexes both directly, so v.zip(s) on a Set is a type error at the argument and the spelling is v.zip(s.to_vec()).

fold carries an accumulator

fold is the sink for anything the fixed ones do not cover. The accumulator can be any type, including a record or a collection.

// `fold` threads an accumulator of any type through the chain.
struct Run {
    best: Int
    total: Int
    count: Int
}

var xs = [3, 9, 4, 1, 12, 7]

// A record accumulator: three answers from one pass.
var r = xs.fold(Run { best: 0, total: 0, count: 0 }, |acc, x| Run {
    best: max(acc.best, x),
    total: acc.total + x,
    count: acc.count + 1,
})
out(r.best)
out(r.total)
out(r.count)

// A Vec accumulator: a running total, one entry per element. A collection
// is a reference, so the closure hands the same one back each step.
var running = xs.fold([0], |acc, x| {
    acc.push(acc[acc.len() - 1] + x)
    acc
})
out(running)

// `reduce` is `fold` seeded with the first element, so it has no answer
// for an empty sequence and faults instead of inventing one.
out(xs.reduce(|a, b| max(a, b)))

12
36
6
[0, 3, 12, 16, 17, 29, 36]
12

reduce is fold without the seed: its accumulator is the element type, and the first element starts it.

Searching answers an Option

find answers the matching element, position answers its index, and a miss is None in both cases. The result is the ordinary Option enum, so a match is how you read it.

// `find` answers the element, `position` answers the index, and a miss is None.
var words = ["alpha", "beta", "gamma"]

match words.find(|w| w.len() == 4) {
    Some(w) => out("found " + w)
    None => out("nothing that long")
}

match words.position(|w| w.len() == 4) {
    Some(i) => out(i)
    None => out(-1)
}

// The sentinel problem an Option removes: -1 is a perfectly ordinary
// element and a perfectly ordinary index.
var v = [10, -1, 30]
out(v.find(|x| x < 0))
out(v.find(|x| x > 100))

// `any` and `all` stop as soon as the answer is decided.
out(v.any(|x| x < 0))
out(v.all(|x| x < 0))

found beta
1
Some(-1)
None
true
false

The Option is what retires a sentinel that used to be in band. -1 is a legal element of a Vec[Int] and a legal index of nothing, so a find that answered -1 on a miss could not tell [10, -1, 30]’s first negative from no match at all.

An empty sequence

Most sinks have a right answer for an empty source, and give it:

// The sinks that have a right answer for an empty sequence.
var scores: Vec[Int] = []
out(scores.sum())
out(scores.product())
out(scores.count())
out(scores.any(|x| x > 0))
out(scores.all(|x| x > 0))
out(scores.find(|x| x > 0))
out(scores.position(|x| x > 0))
out(scores.fold(100, |acc, x| acc + x))
out(scores.map(|x| x * 2))

0
1
0
false
true
None
None
100
[]

Five do not: min, max, min_by, max_by and reduce all derive their answer from an element, and an empty sequence has none. They fault, and they deliberately do not answer None: an empty min is a mistake in the program, where a find that matches nothing is ordinary domain absence. A 0 would be worse than either — it is below every element of [3, 4] and above every element of [-3, -4], and nothing at the call site could tell it from a real minimum.

// An empty `min` has no answer, and the fault says so.
var scores: Vec[Int] = []
out(scores.min())

error: program faulted: empty collection

Backtrace:
#0   <entry>

  locals:
    scores: Vec[Int] = []
  temps:
    <tmp#1: Vec[Int]> @ "[]" = []
    <tmp#3: Int> = 0
    <tmp#4: Int> = 0
    <tmp#8: Unit> @ "out(scores.min())" = <uninit>

That is what praxis run --debug never prints. With a terminal and the default --debug auto, the same fault opens the crash debugger at the failing frame instead.

A pipeline’s currency is Vec

Every streaming stage answers a Vec, whatever the source was. set.filter(p) is a Vec[T], not a Set[T]. A program that wants a collection back says which one:

// A pipeline's currency is Vec. To get a collection back, name it.
var s = Set()
s.insert(3)
s.insert(1)
s.insert(2)

out(s.filter(|x| x > 1))
out(s.filter(|x| x > 1).to_set().len())

// to_vec is the route out of a keyed collection: keys() and values()
// answer two aligned halves and nothing joins them.
var m = Map()
m["a"] = 1
m["b"] = 2
out(m.to_vec())

// ...and to_map is the route back in.
var scaled = m.map(|kv| (kv.0, kv.1 * 10)).to_map()
out(scaled["b"])

// The rest of the set, one per collection that has a constructor.
out([1, 2, 3].map(|x| x % 2).to_set().len())
out([3, 1, 2].to_deque().pop_front())
out([3, 1, 2].to_min_heap().pop())
out([3, 1, 2].to_max_heap().pop())
out([1, 4].to_bitset().contains(4))
out(["a", "b", "a"].frequencies().to_vec().to_counter()["a"])

// On a Vec receiver, to_vec is the identity — the same reference, not a
// copy.
var v = [1]
var same = v.to_vec()
same.push(2)
out(v.len())

[2, 3]
2
[(a, 1), (b, 2)]
20
2
3
1
3
true
2
2

One rule instead of a rule per collection, and it is answerable without knowing which receiver you are on. The alternative was filter returning the receiver’s own type where a row happened to exist and a Vec otherwise, which nobody can hold in their head.

to_map and to_counter say “a pair” in their receiver, so a mismatch is a type error at the method name rather than a fault later: [1, 2].to_map() is error[Y001]: expected (?T, ?U), found Int. to_bitset says Int the same way, and still faults on a negative or oversized member, which is a value question no type can answer.

There is no to_grid(): a grid needs a width, and a flat item sequence does not carry one.

Barriers

// Six of the eight combinators that need the whole sequence before they
// answer. `chunks` and `windows` are above, with the groups they build.
var v = [3, 1, 4, 1, 5, 9, 2, 6, 5]

out(v.sorted())
out(v.unique())
out(v.reversed())
out(v.frequencies())
out(["a", "b", "c"].join(", "))

// A countdown is a reversed range: `5..0` is empty, not descending.
out((0..5).reversed())

// A chain ends at a barrier and begins again from its result.
out(v.filter(|x| x > 2).sorted().take(3))

// A pair is not orderable, so a Counter orders by an extracted key.
var tally = ["the", "cat", "the", "dog", "the", "cat"].frequencies()
out(tally.to_vec().sorted_by_key(|p| 0 - p.1))

// A barrier takes any source, not only a Vec.
var names = Set()
names.insert("bb")
names.insert("a")
names.insert("ccc")
out(names.sorted())
out(names.sorted_by_key(|t| t.len()))

[1, 1, 2, 3, 4, 5, 5, 6, 9]
[3, 1, 4, 5, 9, 2, 6]
[5, 6, 2, 9, 5, 1, 4, 1, 3]
{1: 2, 2: 1, 3: 1, 4: 1, 5: 2, 6: 1, 9: 1}
a, b, c
[4, 3, 2, 1, 0]
[3, 4, 5]
[(the, 3), (cat, 2), (dog, 1)]
[a, bb, ccc]
[a, bb, ccc]

sorted_by_key exists because a keyed collection cannot order its own items. No composite type is orderable, so the moment a pipeline’s item is a pair — the moment its source is a Map or a Counter — sorted is unavailable:

// A pipeline whose item is a pair has no `sorted`.
var m = Map()
m["a"] = 1
out(m.to_vec().sorted())

error[Y006]: values of type `(Text, Int)` cannot be ordered

  pair-not-orderable.px:4:16
  4 | out(m.to_vec().sorted())
    |                ^^^^^^ values of type `(Text, Int)` cannot be ordered

praxis: 1 error(s)

The closure extracts an orderable key from an item that is not one, so the ordering requirement moves off the element and onto the key. There is still no reverse flag on sorted, but there are now two ways to write a descending sort: 0 - p.1 as the key, or sorted().reversed(). The first is one pass and the second is two, which is the whole difference.

unique() and to_set() answer different questions: unique keeps first-occurrence order in a Vec, and a Set has no order to preserve. frequencies() and to_counter() are the two directions of the same type change — frequencies counts occurrences of each element, to_counter assigns the count each pair already carries.

What to unlearn, coming from Rust

There is no laziness. A pipeline runs at the point it is written. There is no adaptor object, no impl Iterator, nothing to hold and consume later.

// A pipeline runs where it is written. Nothing waits for a consumer.
fn seen(x) {
    out(x)
    x * 2
}

var v = [1, 2, 3]
var mapped = v.map(|x| seen(x))
out("--- the map is already finished ---")
out(mapped)

1
2
3
--- the map is already finished ---
[2, 4, 6]

There is no collect. A chain that ends on a streaming stage materializes anyway, so the word would name a step the compiler takes whether or not you write it. The method does not exist:

// `collect` is not a method. A chain materializes without being told to.
var v = [1, 2, 3]
out(v.map(|x| x * 2).collect())

error[Y110]: no method `collect` on type `Vec[Int]` taking 0 argument(s)

  no-collect.px:3:22
  3 | out(v.map(|x| x * 2).collect())
    |                      ^^^^^^^ no method `collect` on type `Vec[Int]` taking 0 argument(s)

praxis: 1 error(s)

to_vec() is not collect under another name. On a Vec it is the identity, and it answers the same reference rather than a copy; on the other nine receivers it is a real conversion, because nothing a Set or a Map holds is a Vec until something asks for one.

The chain is still one loop. Eager does not mean a Vec per stage: v.map(f).filter(p).sum() compiles to a single loop with no intermediate allocation. A stage or sink that stops the stream therefore stops the whole loop, which is observable when a stage has a side effect:

// The whole chain is one loop over the source, so a stage or sink that stops
// the stream stops the loop.
fn seen(x) {
    out(x)
    x
}

var v = [1, 2, 3, 4, 5]

// `any` answers as soon as it can, and the map behind it stops with it.
out(v.map(|x| seen(x)).any(|x| x > 1))
out("---")

// `take` stops when it meets the element after the last one it keeps, so
// the stage in front of it runs once more than it keeps.
out(v.map(|x| seen(x)).take(2))

1
2
true
---
1
2
3
[1, 2]

A source that indexes itself — Vec, Deque, Range, Text — is walked in place. The rest are snapshotted once before the loop, which is what a for over them already does.

A pipeline is not an expression type. There is no Seq[T] you can annotate, pass to a function or store in a record: var xs: Seq[Int] = [] is reported as N002, an unknown type. The value between two stages does not exist at run time, and the value at the end of a chain is an ordinary one — a Vec, the collection a conversion named, or a scalar.

A Grid is not one of the ten. g.map(|c| c) is a Y110, and g.cells() or g.positions() is the way into a chain: a grid’s shape is part of its value, and a stage that flattened it would be answering about something else.

Grids and graphs

Two things live in this chapter. Grid[T] is the rectangular two-dimensional collection: fixed width and height, one T per cell, indexed grid[x, y]. And the prelude has twelve graph helpers — the bfs, dfs, dijkstra and A* families, plus flood_fill — which take a start state and a closure that answers “what is next to here?”. They are related because most puzzle graphs are a grid, but neither needs the other: a walk never sees a grid, and a grid knows nothing about search.

Coordinates

(x, y), with x increasing rightward and y increasing downward. x is the column and y is the row, so grid[0, 2] is the leftmost cell of the third line of input. Every position a grid method hands back is an (Int, Int) tuple in that order.

Where a grid comes from

From the input parser, in practice. grid(P) reads one cell per character of each line; matrix(P) reads one cell per whitespace-separated token. Both are covered in structural parsers.

And from the program itself. Grid() is the empty 0×0 grid; Grid(w, h, fill) is the working grid an algorithm allocates for itself — an occupancy board, a visited mask, a distance table — with every cell starting as fill. That is the difference between using Grid[T] and reimplementing it: a hand-rolled Vec[Bool] indexed y * w + x has no contains, no neighbors4, and no bounds behaviour at all. There is still no to_vec-style to_grid on any sequence, so a grid is either read or allocated.

When fill is itself a collection, every cell is the same collection — Grid(2, 2, Vec()) is four names for one Vec — because a binding names an object rather than owning it. And a negative extent, or one whose w × h is past 2^28 cells, is a size or extent out of range fault rather than a check-time refusal: the extents are ordinary Ints computed at run time.

// `read grid(char)` makes every character of every line a cell.
var map = read grid(char)
var rock = '#'

out(map.width())
out(map.height())

// `map[x, y]` is column `x` of row `y`: x rightward, y downward.
// `map.get(x, y)` is the same read spelled as a method.
out(map[0, 0])
out(map.get(3, 1))

// Whether a position is inside is a question, not a fault.
out(map.contains(3, 1))
out(map.contains(9, 0))

// A row, a column, and the whole thing flattened in row-major order.
out(map.row(1))
out(map.column(0))
out(map.cells())

// A `for` walks the cells in that same order.
var rocks = 0
for cell in map {
    if cell == rock { rocks = rocks + 1 }
}
out(rocks)

// A grid is mutable in place; `map.set(x, y, v)` is the same store.
map[0, 0] = rock
map.set(0, 2, rock)
out(map.row(0))
out(map.row(2))

// A row prints as a Vec; `to_text()` draws it back as the line it was read as.
for y in 0..map.height() {
    out(map.row(y).to_text())
}

On the input

..#.
#...
.#.#

that prints

4
3
.
.
true
false
[#, ., ., .]
[., #, .]
[., ., #, ., #, ., ., ., ., #, ., #]
4
[#, ., #, .]
[#, #, ., #]
#.#.
#...
##.#

The wall is written '#', a character literal — the spelling for a character the program chose. "#"[0], a one-character Text subscripted at 0, is the same Char and is what a program reaches for when the character came out of text it did not write down. See Text and Char.

Note what a grid does not have. There is no len(): “how many” would have to choose between cells and rows, and the catalog picks neither, so map.len() is a Y110 — no such method on Grid[Char]. A grid is also not one of the ten pipeline receivers, so map.map(f) and map.filter(p) do not resolve either — map.cells() is the bridge, and map.cells().filter(p).count() is one fused loop over a Vec[T]. A bare for over the grid itself works and yields cells in row-major order, which is the case that mattered.

The working grid

The allocated grid above, in use: a visited mask over a maze, sized from the maze’s own extents and marked as the walk goes.

// `Grid(w, h, fill)` is the working grid — the one an algorithm allocates for
// itself rather than reads. Here it is a visited mask over a maze, filled with
// `false` and marked as the walk goes.
var maze = read grid(char)

var seen = Grid(maze.width(), maze.height(), false)
var frontier = Vec()
frontier.push((0, 0))
seen[0, 0] = true

var reached = 0
var at = 0
while at < frontier.len() {
    var cur = frontier[at]
    at = at + 1
    reached = reached + 1
    for n in maze.neighbors4(cur) {
        if maze[n.0, n.1] != '#' && !seen[n.0, n.1] {
            seen[n.0, n.1] = true
            frontier.push(n)
        }
    }
}

out(seen.width())
out(seen.height())
out(reached)
out(seen[0, 0])
out(seen.contains(0, 0))
out(seen.contains(seen.width(), 0))

On the input

....#
.##.#
....#

that prints

5
3
10
true
true
false

The mask is a Grid[Bool] and the maze a Grid[Char]: the two have the same extents and nothing ties them together, which is the usual arrangement. Written out by hand this is bfs — and the whole of the graph helpers below is the case where you would rather not.

Positions and neighbours

var g = read grid(char)
var blank = '.'

// Every position, row-major, as `(x, y)` tuples.
out(g.positions())

// Where a value is: the first one as `Option[(Int, Int)]`, or all of them.
out(g.find(blank))
out(g.find_all(blank))
out(g.find('z'))

// The in-bounds neighbours of a point. Both take one `(Int, Int)` and
// answer a `Vec[(Int, Int)]`, already clipped to the grid.
out(g.neighbors4((0, 0)))
out(g.neighbors8((0, 0)))
out(g.neighbors4((1, 1)))

// A pattern opens a tuple by binding both elements at once.
for (x, y) in g.neighbors4((1, 1)) {
    out(g[x, y])
}

// `p.0` and `p.1` select one element by position.
var p = g.neighbors4((1, 1))[0]
out(p.0)
out(p.1)

On the input

ab.
cde
.fg

that prints

[(0, 0), (1, 0), (2, 0), (0, 1), (1, 1), (2, 1), (0, 2), (1, 2), (2, 2)]
Some((2, 0))
[(2, 0), (0, 2)]
None
[(0, 1), (1, 0)]
[(1, 0), (0, 1), (1, 1)]
[(1, 0), (1, 2), (0, 1), (2, 1)]
b
f
c
e
1
0

The neighbour lists are already clipped, so a corner gets two entries and not four — no bounds test of your own. neighbors4 runs up, down, left, right; neighbors8 runs the 3×3 block row-major with the centre skipped. Which entry was which direction is not in the list; that is what around4 and around8, below, are for. find answers Option[(Int, Int)], so a value that is not there is None rather than a position nobody wrote; find_all needs no Option because an empty Vec already says it.

There are two ways to take a (Int, Int) apart. p.0 and p.1 select an element by position, and an index past the end is a Y019 at check time rather than a run-time surprise. A pattern takes the whole tuple at once — in a for binding as above, or in a match. If you want names, use a record as your position instead; both work everywhere a tuple does.

Naming the directions, and counting them

A clipped Vec drops two facts on the floor: which direction each neighbour was, and — at the edge — that there was a direction at all. around4 and around8 keep both. They answer a record, one field per direction, and every field is an Option[(Int, Int)]: None is the direction that leaves the grid.

The field order is the order the record prints in. around4 is the plus read off the page with the centre skipped — up, left, right, down. around8 is the whole 3×3 block in reading order, again with the centre skipped — up_left, up, up_right, left, right, down_left, down, down_right.

The four counts are the other half. count4(p, v) and count8(p, v) count the neighbouring cells that hold v; count4_where(p, f) and count8_where(p, f) count the ones whose cell a closure accepts. A neighbour off the grid has no cell, so it is not counted, and f is never called for it — there is no cell to hand it, and inventing one would mean choosing a value the cell type may not have.

// `#` is a wall. Which way is which, and how boxed in is a square?
var g = read grid(char)
var wall = '#'

// `around4` answers a record with one field per direction, named: `up`,
// `left`, `right`, `down`, in that order.
var corner = g.around4((0, 0))
out(corner)
out(corner.up)
out(corner.right)

// Every field is an `Option`, because a direction can leave the grid — the one
// thing a clipped `Vec` of neighbours cannot say.
match corner.down {
    Some(p) => out(g[p.0, p.1]),
    None => out("off the grid"),
}
match corner.up {
    Some(p) => out(g[p.0, p.1]),
    None => out("off the grid"),
}

// `around8` names all eight, in reading order with the centre skipped.
out(g.around8((1, 1)))

// The counts answer a number without building a collection first.
out(g.count4((1, 1), wall))
out(g.count8((1, 1), wall))
out(g.count4_where((1, 1), |c| c != wall))
out(g.count8_where((1, 1), |c| c != wall))

// A neighbour off the grid has no cell, so it is not counted and the closure
// is never called for it: the corner has two neighbours, not four.
out(g.count4_where((0, 0), |c| true))

On the input

..#
#..
.#.

that prints

{ up: None, left: None, right: Some((1, 0)), down: Some((0, 1)) }
None
Some((1, 0))
#
off the grid
{ up_left: Some((0, 0)), up: Some((1, 0)), up_right: Some((2, 0)), left: Some((0, 1)), right: Some((2, 1)), down_left: Some((0, 2)), down: Some((1, 2)), down_right: Some((2, 2)) }
2
3
2
5
2

The record’s type is called Around4 — a type error prints that name — but it is not a name you can write: var a: Around4 = ... is an N002. Bind it with a plain var and read its fields.

neighbors4 and neighbors8 are still here, and still answer a Vec. That is not a leftover. The graph helpers below type their neighbour argument as (T) -> Vec[T], so bfs(start, |p| g.neighbors4(p)) is the spelling a walk needs, and a record of four Options is not a Vec of anything. Use neighbors4 to walk and around4 to look; use a count when the answer was going to be a number and the loop only existed to add it up.

Turning a grid

var g = read grid(char)

fn show(name: Text, g: Grid[Char]) -> Unit {
    out(name)
    for y in 0..g.height() {
        out(g.row(y))
    }
}

show("original", g)
show("transpose", g.transpose())
show("rotate_right", g.rotate_right())
show("rotate_left", g.rotate_left())

// Each answers a new grid; the receiver is untouched.
show("still original", g)

On abc / def:

original
[a, b, c]
[d, e, f]
transpose
[a, d]
[b, e]
[c, f]
rotate_right
[d, a]
[e, b]
[f, c]
rotate_left
[c, f]
[b, e]
[a, d]
still original
[a, b, c]
[d, e, f]

out(grid) prints the cells flat, in row-major order, with no row structure — printing grid.row(y) in a loop, as show does, is how you look at the shape.

matrix(P) is a Grid[T]

There is no separate Matrix type. grid and matrix differ only in how each cuts a row into cells, and both answer Grid[T].

// The only difference between the two constructors is how a row is cut up.
// `grid` takes one cell per character; `matrix` takes one per whitespace-
// separated token. Both answer a `Grid[T]`.
var heights = parse("123\n456\n", grid(digit))
var readings = parse("12 3\n45 6\n", matrix(int))

out(heights.width())
out(heights.cells())

out(readings.width())
out(readings.cells())

// Same type, so the same methods.
out(heights.row(1))
out(readings.row(1))

3
[1, 2, 3, 4, 5, 6]
2
[12, 3, 45, 6]
[4, 5, 6]
[45, 6]

Both constructors require every row to have the same cell count; a short row is a parse fault unless you ask for grid(P, ragged, fill: "X"). That is the input parser’s business, not the grid’s.

When an index is off the grid

grid[x, y], get, set, row and column fault when the position is not there. contains is the way to ask first.

var g = read grid(char)
out(g[4, 0])

error: program faulted: index out of bounds

Backtrace:
#0   <entry>

  locals:
    g: Grid[Char] = [a, b, c, d]
  temps:
    <tmp#1> = "abcd\n"
    <tmp#2: Int> = 1
    <tmp#3: Grid[Char]> = [a, b, c, d]
    <tmp#5: Int> @ "4" = 4
    <tmp#6: Int> @ "0" = 0
    <tmp#7: Char> @ "g[4, 0]" = <uninit>
    <tmp#8: Unit> @ "out(g[4, 0])" = <uninit>

The Grid[T] method surface

That is all of it — twenty-four rows, including the two subscript forms.

There is no grid.map(fn): g.map(f) is a Y110. Map over grid.cells() instead, and index back with grid.positions() if you need to know where each cell was.

Drawing the grid back is how a grid puzzle is debugged, and out(grid.row(y)) is not it — that prints [., ., |]. A Vec[Char] has a to_text(), so the line the grid was read from comes back one call later:

for y in 0..grid.height() { out(grid.row(y).to_text()) }

It is a Vec[Char] row and not a Grid one, so a whole grid still prints as its cells; a picture is a sequence of lines, and the loop is where the reader chooses that.

The graph helpers

There is no graph object, no adjacency type and no node type. Every helper takes a start state and then only functions of it: the graph is the closure. A state is any value you can put in a Set, so an Int node id, a Text, an (Int, Int) grid position and a record all work, and the walk never learns where they came from.

There are twelve of them, and the names are a rule rather than a list. The bare name is the whole walk, _distance is the number, and _path is the route. One search, three questions. Learn the rule on one family and you can write the other three from the name: the arguments are the same in the same order, and the only one the bare form does not take is the goal predicate — which it has no use for, because it is not looking for anything.

The argument order is always start, neighbours, then weight, heuristic and goal where they apply. The goal is a predicate, not a value: |p| p == exit for a specific square, |s| s.depth == 26 for a property. A*’s five arguments are the honest count — a start, a graph, a cost, an estimate and a goal, none of which has a default worth guessing.

Two families are short a row, and both gaps say something. A* has no bare a_star: the heuristic estimates the remaining cost to a goal, so a whole-graph A* would be a search steering at nothing — dijkstra is that walk, and it is why the two share a weight function. flood_fill has no _distance and no _path: it is bfs’s unordered twin, and a Set has thrown away the order a route would be made of. Ask bfs_path for that.

What the three forms answer:

• The bare name walks everything reachable. bfs and dfs answer a Vec[T] in the order they reached it, flood_fill a Set[T], dijkstra a Map[T, Int] of least costs. None of them needs an Option, because all of them contain the state you started from.
• _distance answers Option[Int] — the cost of the route the search reaches a goal by, or None when no goal is reachable. For bfs_distance and dfs_distance the cost is the step count, one per edge.
• _path answers Option[Vec[T]] — that same route, start to goal inclusive, so a route holds exactly one more state than the matching _distance counts steps. The Option is the same Option: a found route always holds at least its own start, so an empty Vec could not stand for “no route”.

One honest caveat, and it is the whole of the difference between the two unweighted families: dfs_path answers a route, not the shortest one, and dfs_distance is that route’s length rather than the fewest steps. Depth-first search commits to the first neighbour a state reports and backtracks only when it must, so it finds a goal by wandering to it. bfs_path is the shortest route; dfs_path is a route that exists. Reach for dfs_* when the graph is a tree, when any route will do, or when you want the one depth-first happens to take — never when you meant “shortest”.

A maze

A grid on stdin, a shortest path, an answer.

// A maze on stdin: `#` is a wall, `S` the start, `E` the exit.
// How few steps is the exit?
var maze = read grid(char)
var wall = '#'

// The graph is this function. `bfs_distance` never sees the grid: it only
// ever asks "what is next to here?" and "is this the exit?".
fn open_neighbours(maze: Grid[Char], wall: Char, p: (Int, Int)) -> Vec[(Int, Int)] {
    var open = Vec()
    for (x, y) in maze.neighbors4(p) {
        if maze[x, y] != wall {
            open.push((x, y))
        }
    }
    open
}

fn square(maze: Grid[Char], mark: Char) -> (Int, Int) {
    match maze.find(mark) {
        Some(p) => p,
        None => panic("the maze is missing a marker"),
    }
}

var start = square(maze, 'S')
var exit = square(maze, 'E')

var steps = bfs_distance(
    start,
    |p| open_neighbours(maze, wall, p),
    |p| p == exit,
)

match steps {
    Some(n) => out(n),
    None => out("walled in"),
}

The input is nine columns by five rows, with a sealed pocket on the right edge:

S..#....#
.#.#.#..#
.#...#.#.
.#.#.#..#
...#...E#

11

bfs_distance counts steps, one per edge, and stops at the first state its predicate accepts — which is a shortest one, because breadth-first reaches every state by its shortest path. is_goal is asked about the start first, so a search that begins at its goal answers Some(0). A goal nothing satisfies is None, not -1 and not a fault; see Option.

The same maze, drawn

Change the suffix and the same search hands back the route instead of its length. Nothing else about the call moves — same start, same neighbours, same goal predicate, same three arguments in the same order — which is the whole point of the naming rule.

// The same maze, and the same graph — but the route rather than the number.
var maze = read grid(char)
var wall = '#'

fn square(maze: Grid[Char], mark: Char) -> (Int, Int) {
    match maze.find(mark) {
        Some(p) => p,
        None => panic("the maze is missing a marker"),
    }
}

var start = square(maze, 'S')
var exit = square(maze, 'E')
var step = |p| maze.neighbors4(p).filter(|q| match q { (x, y) => maze[x, y] != wall })
var arrived = |p| p == exit

// The number, then the route: same start, same graph, same goal.
out(bfs_distance(start, step, arrived))

// `dfs_path` answers *a* route, not a shortest one — depth-first commits to
// the first neighbour a state reports and backtracks only when it must.
match dfs_path(start, step, arrived) {
    Some(route) => out(route.len()),
    None => out("walled in"),
}

// A route runs start to goal inclusive, so it holds one more state than the
// matching `_distance` counts steps.
match bfs_path(start, step, arrived) {
    Some(route) => {
        out(route.len())
        for (x, y) in route {
            if maze[x, y] == '.' { maze[x, y] = 'o' }
        }
        for y in 0..maze.height() {
            out(maze.row(y).to_text())
        }
    },
    None => out("walled in"),
}

On the same input, that prints

Some(11)
20
12
Soo#....#
.#o#.#..#
.#ooo#.#.
.#.#o#..#
...#oooE#

Eleven steps and twelve squares: the route is inclusive of both ends. The depth-first route through the same maze is twenty of them — a route that exists, and not the shortest one. The two calls differ by three letters and answer routes of different lengths, which is the caveat above measured on the maze this chapter is built around.

Marking the route back onto the grid is a good part of why _path exists at all. bfs_distance can tell you a puzzle has an answer; only the route can tell you the answer went the way you thought it did.

Traversals

bfs, dfs and flood_fill do not look for anything. They answer everything reachable — the first two in the order they reached it, the third as a Set. All three contain the state you started from, which is why none of them needs an Option.

var maze = read grid(char)
var wall = '#'

// The same graph as the maze, written as one closure: the in-bounds
// neighbours, minus the walls.
var step = |p| maze.neighbors4(p).filter(|q| match q { (x, y) => maze[x, y] != wall })

// `bfs` and `dfs` answer every reachable state, in the order they reached it.
// Both start with the state you gave them.
var breadth = bfs((0, 0), step)
out(breadth.len())
out(breadth[0])
out(breadth[1])
out(breadth[2])

var depth = dfs((0, 0), step)
out(depth[1])
out(depth[2])

// `flood_fill` asks the same reachability question and drops the order.
var filled = flood_fill((0, 0), step)
out(filled.len())

// The pocket at (8, 2) is open but walled off, so no walk reaches it.
out(maze[8, 2] != wall)
out(filled.contains((8, 2)))

On the same maze:

29
(0, 0)
(0, 1)
(1, 0)
(0, 1)
(0, 2)
29
true
false

Thirty squares are open and twenty-nine are reachable; the pocket at (8, 2) is on the right edge with a wall on each of its three neighbours, so it appears in nothing. dfs descends into the first neighbour a state reports, so its second and third states are (0, 1) and (0, 2) — straight down the left edge — while bfs takes (0, 1) then (1, 0).

A closure stored in a variable, as step is here, is an ordinary value and can be handed to as many helpers as you like. So can a top-level fn by name: bfs(0, steps) and bfs(0, |n| steps(n)) are the same walk. The neighbour result is an ordinary Vec, so a pipeline is a fine way to build it, as step does here.

Costs: dijkstra and A*

The weighted families are the same three questions over a cost instead of a step count. dijkstra answers a whole Map[T, Int] — the least cost from the start to every state it reaches; dijkstra_distance and dijkstra_path answer the number and the route for one goal. A* is the same pair with one extra argument, an estimate of the remaining cost to steer with, and no whole-walk form to be the third.

// A cost field: entering a square costs the number written on it.
var cost = read matrix(int)
var goal = (cost.width() - 1, cost.height() - 1)

var step = |p| cost.neighbors4(p)
var price = |a, b| match b { (x, y) => cost[x, y] }

// `dijkstra` answers a table: the least cost from the start to every state it
// reaches. The start is in it at 0, and a state it cannot reach is absent
// rather than infinite — which is why this one needs no `Option`.
var table = dijkstra((0, 0), step, price)
out(table.len())
out(table[(0, 0)])
out(table[(2, 0)])
out(table[goal])
out(table.contains((99, 99)))

// The goal-directed pair over the same weights: `dijkstra_distance` is the
// number the table already holds for one state, `dijkstra_path` the route to
// it, start to goal inclusive.
out(dijkstra_distance((0, 0), step, price, |p| p == goal))
out(dijkstra_path((0, 0), step, price, |p| p == goal))

fn manhattan(a: (Int, Int), b: (Int, Int)) -> Int {
    match a {
        (ax, ay) => match b {
            (bx, by) => abs(ax - bx) + abs(ay - by),
        },
    }
}

// A* takes one more argument than Dijkstra — an estimate that never
// overshoots. Every step here costs at least 1, so Manhattan distance is
// admissible. There is no bare `a_star`: an estimate is an estimate *of the
// remaining cost to a goal*, so a whole-graph A* would be a walk with nothing
// to steer towards.
out(a_star_distance((0, 0), step, price, |p| manhattan(p, goal), |p| p == goal))
out(a_star_path((0, 0), step, price, |p| manhattan(p, goal), |p| p == goal))

// A zero estimate is admissible too; it turns A* back into Dijkstra.
out(a_star_distance((0, 0), step, price, |p| 0, |p| p == goal))

// A goal nothing satisfies is `None`, not a fault and not a sentinel — and a
// `_path` says it the same way, because an empty route would be a route that
// does not even hold its own start.
out(a_star_distance((0, 0), step, price, |p| 0, |p| p == (99, 99)))
out(a_star_path((0, 0), step, price, |p| 0, |p| p == (99, 99)))

On

1 1 9 1
1 9 1 1
1 1 1 9
9 1 1 1

it prints

16
0
10
6
false
Some(6)
Some([(0, 0), (0, 1), (0, 2), (1, 2), (1, 3), (2, 3), (3, 3)])
Some(6)
Some([(0, 0), (0, 1), (0, 2), (1, 2), (1, 3), (2, 3), (3, 3)])
Some(6)
None
None

The weight function is (T, T) -> Int — the two endpoints of the edge, in that order. Here only the destination matters, because the cost is a property of the square you enter; a graph whose edges carry their own cost would use both.

A*’s contract is that the estimate never exceeds the true remaining cost. |p| 0 always satisfies it, and turns the search into Dijkstra with one goal.

dijkstra_distance and a_star_distance agree here, and so do their _path forms, because both routes cost six: the estimate steers which states get looked at, not which answer comes out. A cost of six over seven squares is the route-is-inclusive rule again — six edges, seven states.

What a state has to be

Every walk keeps the states it has seen in a set, and the weighted ones key a cost table on them, so the state type has to be one that cannot change after it is stored — the same HashStable rule a Map key follows (capabilities).

// Every walk keeps the states it has seen in a set, and the weighted ones key
// a cost table on them. So a state has to be a value that cannot change after
// it is stored — and a `Vec` can.
fn steps(v: Vec[Int]) -> Vec[Vec[Int]] {
    Vec()
}

out(bfs(Vec(), steps).len())

$ praxis check unstable-state.px
error[Y014]: a value of type `Vec[Int]` can change after it is stored, so it cannot be used as a key

  unstable-state.px:8:5
  8 | out(bfs(Vec(), steps).len())
    |     ^^^^^^^^^^^^^^^^^ a value of type `Vec[Int]` can change after it is stored, so it cannot be used as a key

help: use a value that cannot change — a number, `Text`, or a tuple of those

praxis: 1 error(s)

The requirement is reported at the call, not inside the helper. If the state type is still a variable — fn walk(start, step) { bfs(start, step) } — it is deferred onto walk’s own signature and answered at each call to walk.

The neighbour function’s result shape is written into the helper’s signature, so handing it the wrong container is a type error and not a run-time surprise:

// The neighbour function's shape is written into the helper's own signature,
// so a `Set` of neighbours is reported at the call rather than at run time.
fn steps(n: Int) -> Set[Int] {
    Set()
}

out(bfs(0, steps).len())

$ praxis check neighbours-must-be-a-vec.px
error[Y001]: expected (Int, (Int) -> Vec[Int]) -> Vec[Int], found (Int, (Int) -> Set[Int]) -> ?T

  neighbours-must-be-a-vec.px:7:5
  7 | out(bfs(0, steps).len())
    |     ^^^^^^^^^^^^^ expected (Int, (Int) -> Vec[Int]) -> Vec[Int], found (Int, (Int) -> Set[Int]) -> ?T

praxis: 1 error(s)

What stops a walk

An answer the walk cannot compute is a fault, not a wrong number. A negative edge weight is the one to know about: Dijkstra and A* settle a state the first time they pop it and never reconsider, so a negative edge makes the answer quietly too large. It stops instead.

fn steps(n: Int) -> Vec[Int] {
    var v = Vec()
    if n < 3 { v.push(n + 1) }
    v
}

out(dijkstra(0, steps, |a, b| -1).len())

error: program faulted: an argument this algorithm has no answer for

Backtrace:
#0   <entry>

  temps:
    <tmp#1: Int> @ "0" = 0
    <tmp#2: (Int) -> Vec[Int]> @ "steps" = <closure:0>
    <tmp#3: (Int, Int) -> Int> @ "|a, b| -1" = <closure:0>
    <tmp#4: Map[Int, Int]> @ "dijkstra(0, steps, |a, b| -1)" = <uninit>
    <tmp#5: Int> @ "dijkstra(0, steps, |a, b| -1).len()" = <uninit>
    <tmp#6: Unit> @ "out(dijkstra(0, steps, |a, b| -1).len())" = <uninit>

The full list of stops:

The list is per family, not per name: the weight rules bind all five weighted helpers, and a _path form stops where its _distance form does. It is one algorithm answering a different question, not a different algorithm.

The last row is worth stating plainly: a walk calls back into your code, and a division by zero inside a neighbour function stops the walk rather than letting it continue over garbage. See the fault model.

An estimate that merely overshoots is not on that list, and that is the one place in this family where you are on your own: A* cannot detect it without computing the answer first, so an inadmissible heuristic is a wrong number rather than a stop.

The prelude

Thirty-seven names are bound in every Praxis file before the first line runs. There is no import, no use, and no way to get more: a program is one file, and the prelude is the whole free-function surface of the language. Everything else is a method, and those are in the method catalog.

The list lives in crates/praxis-stdlib/src/prelude.rs, which is the same table the type checker and the editor read. It falls into five groups.

Output and control

out, dbg and panic take any type and render it through the value’s own formatter, so panic(candidate) says what the candidate was:

out(42)
out("a line")
out([1, 2, 3])
out((1, "x"))
out(Some(3))

var squares = Map()
squares.insert(2, 4)
squares.insert(3, 9)
out(squares)

42
a line
[1, 2, 3]
(1, x)
Some(3)
{2: 4, 3: 9}

dbg is the identity on types, which is what lets it wrap any subexpression without changing what the program computes — including one whose value you then panic on. Both halves of this go to stderr:

var doubled = dbg(21) * 2
panic(doubled)

21
error: program faulted: panic: 42

Backtrace:
#0   <entry>

  locals:
    doubled: Int = 42
  temps:
    <tmp#1: Int> @ "21" = 21
    <tmp#2: Int> @ "dbg(21)" = 21
    <tmp#3: Int> @ "2" = 2
    <tmp#4: Int> @ "dbg(21) * 2" = 42
    <tmp#6> @ "panic(doubled)" = <uninit>

panic’s result type is Never, so a function can end on one and still satisfy a declared result type: fn pick(v: Vec[Int]) -> Int { if v.is_empty() { panic("no candidates") }; v[0] } type-checks, and so does fn boom() -> Int { panic("x") }.

assert is the one name here that is monomorphic. It takes a Bool and nothing else, so assert(1) is a type error rather than a call that silently accepts anything, and it takes exactly one argument — a message parameter has no spelling, because a name in Praxis has exactly one signature.

assert(1 + 1 == 3)

error: program faulted: assertion failed

Backtrace:
#0   <entry>

  temps:
    <tmp#1: Int> @ "1" = 1
    <tmp#2: Int> @ "1" = 1
    <tmp#3: Int> @ "1 + 1" = 2
    <tmp#4: Int> @ "3" = 3
    <tmp#5: Bool> @ "1 + 1 == 3" = false
    <tmp#6: Unit> @ "assert(1 + 1 == 3)" = <uninit>

Both panic and assert raise ordinary faults, which is why the output above carries a backtrace and the locals. Under the default --debug auto — stdin and stdout both a terminal — they drop you into the crash debugger instead of printing. That is the reason they are faults rather than a write to stderr followed by an exit: a panic that bypassed the fault path is a panic you cannot debug.

Numeric helpers

Seven functions on Int, and two nullary Float functions.

pi and e are nullary functions, not bare constants: pi(), not pi.

out(abs(-7))
out(sign(-7))
out(min(3, 9))
out(max(3, 9))
out(clamp(12, 0, 10))
out(gcd(12, 18))
out(lcm(4, 6))
out(pi())
out(e())

7
-1
3
9
10
6
12
3.141592653589793
2.718281828459045

All seven are Int functions and none of them is generic. Float carries its own abs, sign, min and max as methods — x.abs(), x.min(y) — so the free function never has to choose a lowering per instantiation. clamp, gcd and lcm have no Float counterpart at all; (2.5).clamp(0.0, 1.0) is a Y110. Handing a Float to one of the free functions is an ordinary type error:

$ praxis check prelude-min-is-int.px
error[Y001]: expected (Int, Int) -> Int, found (Float, Float) -> ?T

  prelude-min-is-int.px:1:5
  1 | out(min(1.0, 2.0))
    |     ^^^^^^^^^^^^^ expected (Int, Int) -> Int, found (Float, Float) -> ?T

praxis: 1 error(s)

Collection constructors

Nine names. Called with no arguments, each builds an empty collection and the element type comes from what you then put in. Two of them — Vec and Grid — also take a size and a fill, and the argument count is what chooses between the two shapes.

Only those two are sized, and the rest of the language has no arity overloading at all — Set(3, 0) is an error that says the function takes zero arguments. The two exceptions are the collections whose contents are addressed by position, which is what makes “n of them” mean something: a sized Set is n copies of one element in a set, which is one element, and a sized Map has no answer at all for what its keys would be. This narrows “a name has one signature” without reopening it — the shape is chosen by counting arguments, a syntactic fact available before any argument is typed, and never by looking at their types.

var v = Vec()
v.push(1)

var d = Deque()
d.push_front("front")

var m = Map()
m.insert("k", 1)

var s = Set()
s.insert(3)

var c = Counter()
c.inc("x")

var lo = MinHeap()
lo.push(5)

var hi = MaxHeap()
hi.push(5)

var g = Grid()

var sized = Vec(3, 0)
var board = Grid(3, 2, '.')

var b = BitSet()
b.insert(3)

out(v)
out(d)
out(m)
out(s)
out(c)
out(lo.peek())
out(hi.peek())
out(g.width())
out(b)
out(sized)
out(board)
out(board.width())

[1]
[front]
{k: 1}
{3}
{x: 1}
5
5
0
{3}
[0, 0, 0]
[., ., ., ., ., .]
3

[1, 2, 3] is a Vec literal, so Vec() is only needed when you want an empty one. The tenth collection, Range, has no constructor: a range is written 0..n or 0..=n, and Range is a type name rather than a value — Range() is N001: 'Range' is not defined.

A Map key, a Set element and a Counter key have to be usable as keys, and a heap element has to be orderable — but the constructor is not where that is asked. The requirement is checked at the first method call on the collection, because that is where a program actually puts a value into one, so the construction below is accepted and the len() on the next line is what is refused:

var seen: Set[Vec[Int]] = Set()
out(seen.len())

$ praxis check prelude-key-bound.px
error[Y014]: a value of type `Vec[Int]` can change after it is stored, so it cannot be used as a key

  prelude-key-bound.px:2:10
  2 | out(seen.len())
    |          ^^^ a value of type `Vec[Int]` can change after it is stored, so it cannot be used as a key

help: use a value that cannot change — a number, `Text`, or a tuple of those

praxis: 1 error(s)

See capabilities.

Optionality

Option[T] is domain-level absence and not an error channel. It is what Map.get, Grid.find, the sequence find/position, the checked_* arithmetic methods and the goal-directed graph walks answer with.

var seen = Map()
seen.insert("a", 1)

var found: Option[Int] = seen.get("a")
var missing = seen.get("z")

out(found)
out(missing)

match missing {
  Some(n) => out(n)
  None => out("nothing there")
}

Some(1)
None
nothing there

Some and None are the only enum variants the prelude declares; everything else about them is what enums says about any variant.

Graph helpers

Twelve closure-driven walks. None of them takes a graph object — there is no graph type — so a program describes its graph by giving a start state and a function from a state to its neighbours.

The name says which of three questions a helper answers. The bare name is the whole walk, _distance is what the route to a goal came to, and _path is that route. So knowing one family is knowing all of them, and a family with no whole-walk meaning has no bare name — which is why A* is only a_star_distance and a_star_path. Which route depends on the search, and each row says which; only depth-first declines to promise a cheapest one.

The first parameter is always the start state and every other parameter is a function of it. The weight function takes two adjacent states, the heuristic takes one state and estimates the remaining cost, and the goal is a predicate rather than a value, so a search can stop on a property.

Only the goal-directed helpers answer with an Option, and that pairing is the rule: a walk that always reaches at least its own start cannot fail, and dijkstra needs no Option because “unreachable” is absence from its table. An Option[Vec[T]] is for the same reason an Option[Int] is, and an empty Vec could not stand in for it: a route that was found always holds at least its own start, so “no route” and “a route of nothing” would be the same value.

flood_fill is the unordered twin of bfs and takes no goal at all, so it has neither a _distance nor a _path form — a Set has no route.

fn steps(n: Int) -> Vec[Int] {
  var next = Vec()
  if n * 2 <= 20 { next.push(n * 2) }
  if n + 1 <= 20 { next.push(n + 1) }
  next
}

out(bfs(1, |n| steps(n)).len())
out(dfs(1, |n| steps(n)).len())
out(flood_fill(1, |n| steps(n)).len())
out(dijkstra(1, |n| steps(n), |a, b| b - a).len())

out(bfs_distance(1, |n| steps(n), |n| n == 20))
out(bfs_path(1, |n| steps(n), |n| n == 20))
out(dfs_distance(1, |n| steps(n), |n| n == 20))
out(dfs_path(1, |n| steps(n), |n| n == 20))
out(dijkstra_distance(1, |n| steps(n), |a, b| b - a, |n| n == 20))
out(dijkstra_path(1, |n| steps(n), |a, b| b - a, |n| n == 20))
out(a_star_distance(1, |n| steps(n), |a, b| b - a, |n| 20 - n, |n| n == 20))
out(a_star_path(1, |n| steps(n), |a, b| b - a, |n| 20 - n, |n| n == 20))

out(bfs_distance(1, |n| steps(n), |n| n == 21))
out(bfs_path(1, |n| steps(n), |n| n == 21))

20
20
20
20
Some(5)
Some([1, 2, 4, 5, 10, 20])
Some(8)
Some([1, 2, 4, 8, 16, 17, 18, 19, 20])
Some(19)
Some([1, 2, 4, 5, 10, 20])
Some(19)
Some([1, 2, 4, 5, 10, 20])
None
None

All twenty states are reachable, so the four whole-walk answers all hold twenty entries and differ only in shape — a Vec in visit order twice, a Set, and a Map of costs. The goal-directed pairs are where the names earn themselves: bfs_distance says five steps and bfs_path names the six states they pass through, while dfs_distance says eight, because depth-first reaches 20 by the branch it happened to descend rather than by a shortest route. dijkstra and A* agree with each other on both the cost and the route, since an admissible heuristic changes how much of the graph gets opened and not what is found. The last two calls ask for a goal the graph does not contain, and both forms answer None rather than a sentinel.

Every walk remembers where it has been, so the state type has to be usable as a key: a number, a Text, a Char, a tuple of those, or a record or enum of those. A Vec state is refused at the call site, with the reason rather than the rule:

$ praxis check prelude-graph-state.px
error[Y014]: a value of type `Vec[Int]` can change after it is stored, so it cannot be used as a key

  prelude-graph-state.px:7:5
  7 | out(bfs([1], |s| step(s)).len())
    |     ^^^^^^^^^^^^^^^^^^^^^ a value of type `Vec[Int]` can change after it is stored, so it cannot be used as a key

help: use a value that cannot change — a number, `Text`, or a tuple of those

praxis: 1 error(s)

Which of these can fault

Most prelude names cannot fail. The ones that can:

out, dbg, sign, min, max, pi, e and Some cannot fault, and neither can any collection constructor called with no arguments — there is nothing you gave it for it to refuse. The two sized forms are the exception, and the size is the reason: it is an ordinary Int computed at run time, so a negative or absurd one cannot be caught at praxis check and is a fault instead. See the fault model for what happens after a fault.

They are ordinary bindings

A prelude name is a normal binding in the file’s root scope, so a var of the same name shadows it for the rest of the file, exactly as any other shadow works:

var max = 10
out(max + 1)

11

Worth knowing mostly so that “max is not a function” stops being mysterious once you have used the name for something else.

What is not here

The type names Int, Text, Bool, Char, Float, Unit and Never are also in scope, as annotations, and they are the whole list: any other name in type position is N002: unknown type.

There is nothing else. No I/O beyond out and dbg, no clock, no randomness, no file access, and no import that would add one — a program’s input arrives through read, and its answer leaves through out.

The method catalog

Every method in Praxis is a row in one table. There are 149 of them, they live in crates/praxis-stdlib/src/builtins.rs, and there is no way to add a 150th from a program: the language has no impl, no traits, no extension methods, and a record carries fields but no methods. This chapter is that table.

The closedness is load-bearing rather than a limitation the compiler tolerates. Because the catalog is the complete method universe, a name it does not carry at that arity can never resolve against any receiver — so fn f(x) { x.nope() } is refused at check time, before anything has said what x is.

How to read these tables

Method is the row’s name and the type pattern of each parameter; Result is its result pattern. Both are rendered the way the compiler prints a type: T, U, K, V and Acc are type variables, two occurrences of one name in a row are the same type, (Int, Int) is a tuple, and (T) -> Bool is a closure parameter. A nullary collection prints bare, so it is BitSet and not BitSet[].

Mutates is the row’s purity flag. The impure rows are exactly the ones that change the receiver, and the flag is visible from a program: the crash debugger’s p expression evaluator refuses a call to an impure method, because a debugger that mutates a faulted state cannot resume it.

var v = [1, 2, 3]
out(v[9])

That faults, and the debugger it drops into will evaluate one of these two calls and not the other:

error: program faulted: index out of bounds

Backtrace:
#0   <entry>

  locals:
    v: Vec[Int] = [1, 2, 3]
  temps:
    <tmp#1: Vec[Int]> @ "[1, 2, 3]" = [1, 2, 3]
    <tmp#2: Int> @ "1" = 1
    <tmp#3: Unit> = Unit
    <tmp#4: Int> @ "2" = 2
    <tmp#5: Unit> = Unit
    <tmp#6: Int> @ "3" = 3
    <tmp#7: Unit> = Unit
    <tmp#9: Int> @ "9" = 9
    <tmp#10: Int> @ "v[9]" = <uninit>
    <tmp#11: Unit> @ "out(v[9])" = <uninit>
Entered crash debugger. 1 frame(s). Type `help` for commands.
Praxis crash> p v.len()
3
Praxis crash> p v.push(4)
error: method `push` is impure (may mutate state) — `p` rejects mutating expressions
Praxis crash> quit

Faults is whether the call can raise a runtime fault. For a row backed by a runtime wrapper this is the wrapper’s own declaration in the ABI manifest, which is what puts a fault check after the call — so “yes” means the check is emitted, not that you are likely to trigger it. Vec.push says yes for a type-mismatch case a well-typed program cannot reach; Vec.get says yes because indexing off the end is the everyday one.

Allocates is whether the call may allocate, and therefore whether its call site is a garbage-collection safepoint. It is derived from the same manifest row, which is why len() says yes on every collection: the count comes back as a freshly boxed Int.

Neither flag is restated per method — both are read off the wrapper the row lowers to, so a row cannot disagree with the code it calls. Thirty-one of the thirty-five pipeline rows have no wrapper to read: the compiler fuses them into the loop, so their tables below carry no Allocates column and their Faults column is what the fused code does rather than a manifest row.

Sequence collections

Vec[T]

var v = [10, 20, 30]

out(v.len())
out(v.is_empty())
out(v.get(1))

v.push(40)
out(v)

3
false
20
[10, 20, 30, 40]

push is the only way a vector grows. v[v.len()] = x is an IndexOutOfBounds fault and not an append.

Deque[T]

var d = Deque()
d.push_back(2)
d.push_back(3)
d.push_front(1)

out(d)
out(d.len())
out(d.get(0))
out(d.pop_front())
out(d.pop_back())
out(d.is_empty())

[1, 2, 3]
3
1
1
3
false

Index 0 is the front, whichever end you have been pushing to.

Keyed collections

Map[K, V]

var m = Map()
m.insert("a", 1)
m.insert("b", 2)

out(m.len())
out(m.contains("a"))
out(m.get("a"))
out(m.get("z"))
out(m.keys())
out(m.values())

m.remove("a")
out(m)
out(m.is_empty())

2
true
Some(1)
None
[a, b]
[1, 2]
{b: 2}
false

get answers an Option; m[key] faults on a missing key. Those are the two halves of one question and the spelling picks which you meant.

keys() and values() answer Vecs in a fixed, deterministic order — by the key’s own order, the same one sorted() uses, so an Int key comes out numeric — and the two are index-aligned, so keys()[i] and values()[i] belong together. To get both at once, walk the map: for kv in m and the pipeline rows below both yield (K, V) pairs, and m.to_vec() is the Vec[(K, V)].

Set[T]

var s = Set()
s.insert(1)
s.insert(1)
s.insert(2)

out(s.len())
out(s.contains(2))

s.remove(2)
out(s)
out(s.is_empty())

2
true
{1}
false

Counter[T]

var c = Counter()
c.inc("x")
c.inc("x")
c.inc("y")

out(c.get("x"))
out(c.get("never seen"))
out(c.len())
out(c.keys())
out(c.values())
out(c.is_empty())

2
0
2
[x, y]
[2, 1]
false

A Counter is the collection whose absent values read as zero, so get and c[key] never fault and len() counts the keys that were actually touched.

Priority queues and bit sets

MinHeap[T]

MaxHeap[T]

var lo = MinHeap()
lo.push(5)
lo.push(1)
lo.push(3)

out(lo.len())
out(lo.peek())
out(lo.pop())
out(lo.is_empty())

var hi = MaxHeap()
hi.push(5)
hi.push(1)

out(hi.peek())
out(hi.pop())

3
1
1
false
5
5

peek is pure and pop is not, which is the only difference between them in this table and the whole difference at the call site.

BitSet

var b = BitSet()
b.insert(3)
b.insert(70)

out(b.contains(3))
out(b.contains(4))
out(b.len())

b.remove(3)
out(b)
out(b.is_empty())

true
false
2
{70}
false

insert faults on a negative or oversized member; remove does not, because clearing a bit that was never in range is not a question the set has to answer. contains is the one row in the catalog that lowers to a dedicated scalar-producing instruction rather than a call, which is why it is not a safepoint.

Grid[T]

A grid is indexed (x, y) with x the column and y the row, and positions(), cells() and find_all() walk it in row-major order.

Around4 and Around8 are the catalog’s only named result types, and they are records, not collections: read the field with a dot, a.up, and every one of them is an Option[(Int, Int)]. Around4 is the plus with the centre skipped; Around8 is the whole 3×3 block in reading order, again without the centre. Neither has a constructor — a grid is the only thing that makes one — and the order the rows above list the fields in is the order the runtime lays the value out in, which is why it is written that way and not alphabetically.

var g = read grid(one_of(".#"))
var wall = '#'

out(g.width())
out(g.height())
out(g.get(1, 0))
out(g.contains(3, 0))
out(g.row(0))
out(g.column(1))
out(g.cells())
out(g.positions().len())
out(g.neighbors4((1, 1)))
out(g.neighbors8((0, 0)))
out(g.around4((1, 1)))
out(g.around8((0, 0)))
out(g.around4((1, 1)).right)
out(g.count4((1, 1), wall))
out(g.count8((1, 1), wall))
out(g.count4_where((1, 1), |c| c != wall))
out(g.count8_where((1, 1), |c| c != wall))
out(g.find(wall))
out(g.find_all(wall))
out(g.transpose().row(0))
out(g.rotate_left().row(0))
out(g.rotate_right().row(0))

g.set(0, 0, wall)
out(g.row(0))

with input

.#.
..#

3
2
#
false
[., #, .]
[#, .]
[., #, ., ., ., #]
6
[(1, 0), (0, 1), (2, 1)]
[(1, 0), (0, 1), (1, 1)]
{ up: Some((1, 0)), left: Some((0, 1)), right: Some((2, 1)), down: None }
{ up_left: None, up: None, up_right: None, left: None, right: Some((1, 0)), down_left: None, down: Some((0, 1)), down_right: Some((1, 1)) }
Some((2, 1))
2
2
1
3
Some((1, 0))
[(1, 0), (2, 1)]
[., .]
[., #]
[., .]
[#, #, .]

neighbors4 and neighbors8 return only the in-bounds neighbours, so they are already the neighbour function a graph walk wants: bfs(start, |p| g.neighbors4(p)) type-checks because the walk’s neighbours closure is (T) -> Vec[T].

around4 and around8 are not those rows spelled differently. A clipped Vec cannot say which direction each neighbour was, and at the edge of the grid it cannot say there was a direction at all — (1, 1) above has three orthogonal neighbours and the Vec has three entries, with nothing to mark the missing down. Every field of an Around4 is an Option, so both survive, at the cost of no longer being a Vec a walk can consume. Take the Vec for a search and the record when the direction is the answer.

count4 and count8 compare each in-bounds neighbouring cell to a value, where neighbors4 and neighbors8 answer positions; count4_where and count8_where take a predicate on the cell instead. A neighbour off the grid has no cell, so it is never counted and the closure never sees one — which is why the _where pair is the only Grid row besides column, get, row and set that can fault, and it faults for the predicate’s reasons rather than for any of its own.

transpose, rotate_left and rotate_right answer copies and leave the receiver alone.

A Grid is deliberately not a pipeline receiver. for cell in g walks it in row-major order, but g.map(f) is a Y110: a grid enters a pipeline through cells() or positions(), which already answer Vecs. A grid’s shape is part of its value, and a stage that flattened it would be answering about something else.

The pipeline

Thirty-five rows — thirty-four names, because count has two arities — sit on one generic receiver that stands for ten different receivers: Vec, Deque, Set, MinHeap, MaxHeap, Range, BitSet, Map, Counter and Text. That is the for loop’s list minus Grid, and what a receiver yields here is exactly what the for loop’s variable would bind — a Char from a Text, a (K, V) pair from a Map or a Counter, an element from everything else.

var s = Set()
s.insert(2)
s.insert(1)
out(s.sorted())

var m = Map()
m.insert("a", 1)
m.insert("b", 2)
out(m.map(|pair| pair.0))
out(m.to_vec())

var c = Counter()
c.inc("x")
out(c.to_vec())

var d = Deque()
d.push_back(7)
out(d.sum())

var lo = MinHeap()
lo.push(2)
lo.push(1)
out(lo.to_vec())

var b = BitSet()
b.insert(4)
b.insert(9)
out(b.sum())

out((0..5).sum())
out((0..=5).sum())
out("abc".map(|ch| ch.to_int()))

[1, 2]
[a, b]
[(a, 1), (b, 2)]
[(x, 1)]
7
[1, 2]
13
10
15
[97, 98, 99]

A pipeline’s currency is Vec. Every stage answers one whatever the receiver was, which is what makes “what does filter return” answerable without knowing what you started from. A program that wants a different collection back says which one, with a to_* row.

The Requires column below is the row’s own constraint on the item type. Its wording is the compiler’s: an unorderable element gets Y006 values of type ... cannot be ordered, and one that cannot be a key gets Y014 a value of type ... can change after it is stored.

Stages

sorted, sorted_by_key, unique, reversed, frequencies and join are barriers: each needs the whole sequence before it can answer anything, so each is a call into the runtime rather than a stage the compiler folds into the loop. reversed is the clearest case of the definition — it cannot answer its first element until it has seen the last. Being a barrier is invisible from a program except in what it costs — the other stages are fused into a single pass over the source, which is also what the “Faults” column is measuring here: a fused stage has no wrapper of its own to fault, while sorted and sorted_by_key do — and sorted_by_key‘s also propagates whatever the key closure raised. reversed is the barrier that does not fault, and the two facts are the same fact: it reads no descriptor callback, which is also why its Requires column is empty where its neighbours’ are not.

join is in the sinks table below rather than here, because it answers a Text rather than a sequence.

Sinks

count is the one name in the catalog that carries two arities on a single receiver — count() is the element count, count(pred) the matching-element count — which the table’s (receiver, name, arity) key has always allowed. (get, contains and [] also appear at two arities, but split across receivers: one argument on a Vec, two on a Grid.)

min/max are Int sinks and min_by/max_by take a “less-than” comparator and work on anything. find answers the element, position the index, and both answer an Option.

The seven faulting sinks fault for two reasons and no others. min, max, min_by, max_by and reduce raise empty collection on an empty sequence: each has to answer with an element and there is none. sum and product raise integer overflow, because the running total is checked arithmetic like every other + and *. fold is the sink that does not fault on an empty sequence — it answers its seed — which is the reason to reach for it over reduce.

var v: Vec[Int] = Vec()
out(v.min())

error: program faulted: empty collection

Backtrace:
#0   <entry>

  locals:
    v: Vec[Int] = []
  temps:
    <tmp#1: Vec[Int]> = []
    <tmp#3: Int> = 0
    <tmp#4: Int> = 0
    <tmp#8: Unit> @ "out(v.min())" = <uninit>

Conversions

There is a conversion for every collection that has a constructor, and exactly one that has none: to_grid does not exist, because a grid needs a width and a flat item sequence does not carry one.

to_map and to_counter say “my item is a pair” in the receiver pattern rather than in prose, so [1, 2].to_map() fails at the method name with expected (?T, ?U), found Int instead of resolving and then faulting.

The whole pipeline, run

var v = [3, 1, 4, 1, 5]

out(v.map(|n| n * 2))
out(v.filter(|n| n > 2))
out(v.filter_map(|n| if n > 3 { Some(n) } else { None }))
out(v.flat_map(|n| [n, n]))
out(v.take(2))
out(v.skip(3))
out(v.take_while(|n| n < 4))
out(v.enumerate())
out(v.zip(["a", "b"]))

out(v.fold(0, |acc, n| acc + n))
out(v.reduce(|acc, n| acc + n))
out(v.sum())
out(v.product())
out(v.count())
out(v.count(|n| n == 1))
out(v.min())
out(v.max())
out(v.min_by(|a, b| a < b))
out(v.max_by(|a, b| a < b))
out(v.any(|n| n == 4))
out(v.all(|n| n > 0))
out(v.find(|n| n > 3))
out(v.position(|n| n > 3))

out(v.sorted())
out(v.sorted_by_key(|n| 0 - n))
out(v.unique())
out(v.reversed())
out(v.frequencies())
out(["a", "b", "c"].join(", "))

out(v.to_vec())
out(v.to_set())
out(v.to_deque())
out(v.to_min_heap().peek())
out(v.to_max_heap().peek())
out(v.to_bitset())
out([(1, "a"), (2, "b")].to_map())
out([("x", 3)].to_counter())

[6, 2, 8, 2, 10]
[3, 4, 5]
[4, 5]
[3, 3, 1, 1, 4, 4, 1, 1, 5, 5]
[3, 1]
[1, 5]
[3, 1]
[(0, 3), (1, 1), (2, 4), (3, 1), (4, 5)]
[(3, a), (1, b)]
14
14
14
60
5
2
1
5
1
5
true
true
Some(4)
Some(2)
[1, 1, 3, 4, 5]
[5, 4, 3, 1, 1]
[3, 1, 4, 5]
[5, 1, 4, 1, 3]
{1: 2, 3: 1, 4: 1, 5: 1}
a, b, c
[3, 1, 4, 1, 5]
{1, 3, 4, 5}
[3, 1, 4, 1, 5]
1
5
{1, 3, 4, 5}
{1: a, 2: b}
{x: 3}

What the Requires column refuses

A tuple can be a key but cannot be ordered — no composite in this language can, because ordering goes through one scalar comparison. That is a statement about < and sorted(), not about a container: a Map[(Int, Int), V] still walks and prints its keys element-wise, because it has to walk them in some reproducible order. A record behaves exactly the same way: a fine key, not orderable. A Vec is neither one nor the other: not orderable, for the same composite reason, and not a key, because it can change after it has been stored. Below, the tuple fails the first column and the Vec fails the second.

var pairs = [(2, "b"), (1, "a")]
out(pairs.sorted())

var groups = [[1], [2]]
out(groups.to_set())

$ praxis check catalog-bounds.px
error[Y006]: values of type `(Int, Text)` cannot be ordered

  catalog-bounds.px:2:11
  2 | out(pairs.sorted())
    |           ^^^^^^ values of type `(Int, Text)` cannot be ordered

error[Y014]: a value of type `Vec[Int]` can change after it is stored, so it cannot be used as a key

  catalog-bounds.px:5:12
  5 | out(groups.to_set())
    |            ^^^^^^ a value of type `Vec[Int]` can change after it is stored, so it cannot be used as a key

help: use a value that cannot change — a number, `Text`, or a tuple of those

praxis: 2 error(s)

sorted_by_key is the answer to the first half: the ordering requirement moves to the key the closure extracts, so the elements themselves need not be orderable.

var pairs = [(2, "b"), (1, "a")]
out(pairs.sorted_by_key(|pair| pair.0))

[(1, a), (2, b)]

Scalars

Text is the one scalar with members, and Int, Float and Char have the conversions and the explicit-overflow family.

Text

var line = "héllo"

out(line.len())
out(line.is_empty())
out(line.get(1))
out(line.get(1).to_int())
out((233).to_char())
out(" 42 ".int())
out("héllo".int())
out("1.5".float())
out("inf".float())

5
false
é
233
é
Some(42)
None
Some(1.5)
None

len() counts Unicode scalar values and get/t[i] index by them, not by bytes — which is why "héllo".len() is 5 and line.get(1) is é. Char.to_int and Int.to_char are the round trip out of and back into a character, and they are Int and Char rows rather than Text ones.

int() and float() trim the text and then read exactly what the input parser’s int and float atomics read, over the whole of what is left. They share the parser’s own scanner, so t.int() and parse(t, int) cannot disagree about what a number is. Anything the run does not cover is None — "1 2", "12abc", "1." — because a text that is not a number is absence rather than a fault.

Two answers surprise people, and both follow from that rule:

• "+5".int() is None. The int atomic takes a leading - and not a +. "+5.0".float() is a value, because the float atomic does take one.
• "inf".float() and "nan".float() are None. Float has those values — 1.0 / 0.0 is one, and to_text() prints them — but no text spells one.

A value past Int’s range is None too. The input parser is the other way to get a number out of text, and the one to reach for when the text came from input in the first place: it reports where the parse broke instead of answering None.

There is no split, no chars and no to_upper: all three are Y110. for ch in text is how a Text is walked, and the pipeline rows above apply to it directly.

Int

Float

Char

All three receivers at once:

var x = -2.5

out(x.abs())
out(x.sign())
out(x.floor())
out(x.ceil())
out(x.round())
out(x.to_int())
out(x.to_text())
out(x.min(1.0))
out(x.max(1.0))
out((2.0).sqrt())
out((0.0 / 0.0).is_nan())
out((1.0 / 0.0).is_infinite())

out((7).to_float())
out((9223372036854775807).wrapping_add(1))
out((9223372036854775807).saturating_add(1))
out((9223372036854775807).checked_add(1))
out((5).checked_sub(1))
out((3).wrapping_mul(4))
out((1660).to_text())
out('A'.to_text())

2.5
-1.0
-3.0
-2.0
-3.0
-2
-2.5
-2.5
1.0
1.4142135623730951
true
true
7.0
-9223372036854775808
9223372036854775807
None
Some(4)
12
1660
A

Integer arithmetic is checked by default, and the nine wrapping_/saturating_ /checked_ rows are how a program opts out of the fault for one operation.

The to_text family is Int, Float and Char, and it is closed at three: Bool has no row and there is no universal T.to_text(). Each of the three answers exactly the characters out writes — the method and the printer share one renderer per scalar, so they cannot drift apart. A labelled line does not need any of them: "n = {n}" renders a value of any type through the same printer.

Subscripts

m[key], v[i] = x and grid[x, y] are catalog rows too, dispatched on the receiver’s shape and the index count exactly as a method call is. Their names — [], []=, []min=, []max= — are not identifiers, so no program can call them by name; the subscript grammar is their only caller.

Six receivers read. Five of the six also store: every one but Text, which is immutable.