Skip to the content
Diaspar

Decision D019 · accepted as a goal; details proposed

Terminal output is colored and carefully designed

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) as a goal; proposed for the details

Decision

Everything Diaspar's tools print to a terminal is designed, not incidental: diagnostics (D014), the REPL and the debugger (D017), test and benchmark results (D016), and build output. One shared style and one implementation serve all of them, as Rust's diagnostics look the same across cargo's commands.

Principles (proposed)

  • Meaning, not raw colors, in the toolchain. The tools' output names what a piece is (error, warning, help, location, code, value, success, muted) through the fields of component themes, and one theme file configures every tool.

  • The terminal's palette by default. Default theme styles use the 16 ANSI colors, so the user's terminal theme decides the actual colors and Diaspar looks native in any theme. 24-bit colors only when a theme asks for them.

  • Never color alone. Every meaning also has a word or a symbol (error:, ✓, ✗), for color-blind users, logs, and screenshots in black and white.

  • The standard switches. Color only when the output is a terminal; --color=auto|always|never; the NO_COLOR and FORCE_COLOR/CLICOLOR_FORCE environment variables; no color when TERM=dumb. When both NO_COLOR and FORCE_COLOR are set, NO_COLOR wins: it is the user's request. Under NO_COLOR on a terminal, bold and underline stay, as no-color.org advises (accepted).

  • Styled output is Rich markup inside an f-string (accepted). term.print is a macro over the f-string (D022), so it sees the literal parts and the interpolated values separately, as Python 3.14's t-strings (PEP 750) do:

    (term.print f"[bold red]error:[/] cannot read {path}")
    • Markup comes only from the literal parts and is parsed at compile time: [bold rde] or an unclosed tag is a compile error with a suggestion.
    • Interpolated values are never markup: a file name containing [blink] prints as it is, escaped automatically. In Rich and Spectre.Console the f-string is joined before the markup parser sees it, so text from data can restyle the output unless the caller escapes it by hand; this closes that hole.
    • The tag syntax is Rich's, known from Rich, Textual, and Spectre.Console: [bold red], [on #ff8000], [color(208)], [/] closes the last tag.
    • Stricter than Rich (accepted, 2026-11-16): [/name] must close the innermost open tag, and a tag left open at the end is a compile error; Rich repairs both silently. [[ and ]] write brackets.
    • The result is styled text as data, rendered once at the stream with its capabilities (D024); in a pipe or under NO_COLOR the markup disappears.
  • Themes are records per component (accepted). Each component that prints (diagnostics, cli help, the test runner, the REPL) has its own theme, a record whose fields are styles with defaults, as clap's Styles and miette's ThemeStyles:

    ;; std.diagnostic
    (deftype Theme
      [(error    default: (style.parse "bold red"))
       (warning  default: (style.parse "bold yellow"))
       (help     default: (style.parse "cyan"))
       (location default: (style.parse "blue"))
       (line-num default: (style.parse "dim"))])

    Markup tags may name the theme's fields, checked at compile time against the theme's type: (term.print theme f"[error]error:[/] {message}"). A package that prints its own output (a diff, say) declares its own theme record; nothing is registered globally. The user's theme file sets fields per component, decoded into the records, so a misspelled field is a decoding error with a suggestion (D010):

    ;; ~/.config/diaspar/theme.dias
    #{:diagnostic #{:error "bold bright-red" :help "bright-cyan"}
      :cli        #{:header "bold green"}}
  • Styles are built in code with a builder (accepted as the direction; the names are proposed), following Ferron's Style.new().fg(Red).bold() and ratatui's Style and Stylize. The builder functions live in std.term.style and thread with ->; colors are variants of Color (the 16 ANSI colors, (Indexed n), (Rgb r g b), (Default)):

    (use std.term.style)
    (use std.term.color [Color])
    
    (def error-style (-> style.plain (style.fg (Color.Red)) style.bold))
    (def squiggle    (-> style.plain (style.underline :curly) (style.underline-color (Color.Red))))
    
    ;; the same functions style text directly, as ratatui's Stylize: the result is a styled span
    (-> "error:" (style.fg (Color.Red)) style.bold)
    (term.styled "error:" error-style)

    style.parse reads the text form ("bold red on #ff8000"), used by theme files and configuration; literal strings are parsed at compile time. Styles combine with style.patch, where later attributes win, as ratatui's patch.

  • No global roles and no function per color (accepted). There is no language-wide list of roles (role.error): its names collided with other concepts such as the Error protocol, it needed an extension mechanism for packages, and one list fits no component well; meaning lives in component themes instead. There are no top-level functions such as term.red or term.bold: dozens of names in a module for what one markup tag or one builder call says. Also rejected: keyword roles (misspellings found only by a check against a set), a defenum of roles (heavy to write, closed to packages), and Rich's names-as-strings in one shared theme (the same global registry, without checks).

  • Unicode with a fallback. Box-drawing characters and symbols (─, │, ✓), with an ASCII fallback when the locale or terminal cannot show them.

  • Code is highlighted. Source excerpts in diagnostics, REPL input, and printed values use syntax highlighting with the same theme.

  • Curly underlines in diagnostics. Where the terminal supports extended underlines (kitty, Ghostty, WezTerm, and others), the span of an error is underlined with a red curly line and a warning with a yellow one, as editors do; elsewhere the ━/^ underline stays (accepted).

  • Theme files are data mapping component theme fields to styles written as text (#{:diagnostic #{:error "bold bright-red"}}), with automatic color downgrade (D024) (accepted).

  • Locations are links. file:line:col is printed as an OSC 8 hyperlink where the terminal supports it, so a click opens the file in the editor.

  • The width is respected. Output wraps or truncates to the terminal width; long values are abbreviated with a way to see them in full.

  • Motion only on a terminal. Progress counters and spinners appear only when the output is interactive; piped and CI output stays plain, stable, and line-based.

  • Machine-readable output is separate. --json (D014) never contains color codes.

Why

Output is the language's face: a new user meets the diagnostics, the REPL, and the test runner before anything else. Rust, Elm, and modern tools such as uv and bun show that careful output is part of why a tool feels good to use.