Skip to the content
Diaspar

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 of std.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 NotInteractive instead 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.graphics shows images through the kitty graphics protocol (kitty, Ghostty, WezTerm, Konsole), following Ferron's std.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). A defcommand macro may come later as sugar that expands into the same deftype.

  • Subcommands are defenum variants, so dispatch is a match with 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 line label, 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_help do, 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 cli answers --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 test uses a fresh seed per run and prints it with a rerun command (D016).