Decision D024 · accepted in part; designs proposed
The standard modules std.term, std.cli, and std.random
A record of the language's design, as it stood on 2026-11-18: written for the people who build Diaspar, and kept as it was written. Its code is a sketch, not a program of the site, and an older record may show syntax that a later one changed. It names files of the language's source, which is not public yet.
Status: accepted (2026-11-15) for the choices below; the rest of the designs in docs/design/ (std-term, std-cli, std-random) are proposed
term
- Implements D019: styled text is data rendered once per stream; it is written as Rich markup inside an f-string (
term.print, values escaped automatically) or built with the style builder ofstd.term.style; meaning lives in per-component theme records, not in global roles (D019). - Terminal I/O goes through effects (capabilities and prompts), so tests replace them and a prompt without a terminal raises
NotInteractiveinstead of hanging. - A line editor for the REPL is part of the standard library: the REPL written in Diaspar needs it.
- Styles have the extended underlines (curly, dotted, dashed, double) and an underline color, plus overline and strikethrough, as Ferron's
std.term(accepted). - Styles are also text in Rich's syntax (
"bold red on #ff8000","bright-red","color(208)"), used by theme files (D019); colors are downgraded automatically to what the terminal shows (24-bit → 256 → 16) (accepted). - Images are in std:
std.term.graphicsshows images through the kitty graphics protocol (kitty, Ghostty, WezTerm, Konsole), following Ferron'sstd.term.graphics: PNG or raw RGBA/RGB pixels, optional compression, placements at the cursor or a cell with scaling, source rectangles and z-order, animation frames, deletion, and a query for support; every function returns a control string. Terminals without the protocol get no image, only a short text placeholder; there is no block-character fallback. Sixel and iTerm2's protocol may come later (accepted; this replaces the earlier "images are a package"). - TUI frameworks and Markdown rendering are packages, not std.
cli
-
Commands are records described by field metadata and a deriver (
:derive #[cli.Command]), not a separate macro; the same metadata mechanism serves JSON decoding and other derivers (D010). Adefcommandmacro may come later as sugar that expands into the samedeftype. -
Subcommands are
defenumvariants, so dispatch is amatchwith exhaustiveness checks. -
Usage errors have their own light form, not the frame of a code diagnostic (accepted, 2026-11-16; replaces "usage errors are D014 diagnostics over the command line"). A person who mistyped a command is not reading source code: no frame, no
command linelabel, no line number. The command line is shown with an underline only when there is a token to point at; otherwise one line says what is missing. Then the usage line and where to read more. Exit status 2.error: invalid value `sevice` for `--as`: expected one of server, service jt check --as sevice data/bad.json ^^^^^^ did you mean service? Usage: jt check [OPTIONS] [FILE]... More: jt check --help$ diaspar bild error: unknown command `bild`: did you mean build? Usage: diaspar [OPTIONS] <COMMAND> More: diaspar --help -
A program run with no arguments when it needs a command prints its help, as git, go and clap's
arg_required_else_helpdo, instead of an error; exit status 2, since it did nothing. Diagnostics with a frame and line numbers (D014) stay for errors in source code. -
Every program built with
clianswers--help=json, a machine-readable description for coding agents.
random
- Generators are values that can be saved and restored, as in Ferron.
- How seeds and labels derive generators (
derive, per-test seeds, named streams) is specified and frozen with published test vectors, like the raw ChaCha8Rand and xoshiro256++ streams, so saved seeds and saved games keep working across versions. - The default algorithm is ChaCha8Rand, as Go's: deriving child generators by label (spawn index, test path, named streams) is correct by construction, and misuse for a secret does not become a vulnerability. xoshiro256++ is available by name for hot numeric loops with one stream.
- The ambient source is an effect; tasks get split generators (D006); secure randomness is a separate effect, never affected by
--seed. diaspar testuses a fresh seed per run and prints it with a rerun command (D016).