Skip to the content
Diaspar

Decision D014 · accepted as a goal; format proposed

Diagnostics show the code, with notes and hints

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 as a goal (2026-11-15); the exact format is proposed

Decision

Errors and warnings, from the reader, the compiler, and the runtime, look like Rust's and Ferron's: a message, the location, the source line with the place underlined, then notes and hints.

error: config not found
  --> app.dias:4:5
   |
 4 |     (error "config not found" :path path)
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   = data: {:path "app.toml"}
   = called from: app.main (app.dias:12:3)

error: mismatched brackets
  --> app.dias:5:18
   |
 4 |   (let [a 1
   |        - this `[` ...
 5 |         b 2) (+ a b))
   |            ^ ... is closed by `)`
   = help: close it with `]`, or open it with `(`
  • Every diagnostic has a location and the source excerpt. Errors raised at run time also show the chain of calls that led there.
  • Notes and hints are part of the design of each error, not an afterthought: an error that has an obvious fix says it (help:).
  • Warnings use the same format (D007, D005).
  • A machine-readable form (JSON) comes later, for editors, the LSP, and coding agents, as in Ferron. Its first step exists (2026-11-16): every tool can write its diagnostics as Diaspar data instead of drawing them, with DIASPAR_DIAGNOSTICS_DATA=FILE: a map per diagnostic, #{:severity :error :message "…" :file "app.dias" :at #[4 5] :end #[4 42] :label … :related … :notes #["while: …"] :help #["…"] :data "…" :called-from #["app.main (app.dias:12:3)"]}, the same from the interpreter, compiled programs, the compiler and the evaluator. The language's test cases compare these fields (D016).

One Span, one ReadError (accepted, 2026-11-17)

  • Span (std.lang.syntax: file, line, column, end line, end column) is the one type for a place in source: in syntax, diagnostics, ReadError, and the traces of failures at run time (Failure :trace). std.core uses it without putting it in the prelude's vocabulary.
  • ReadError is one type, in std.lang.reader, with its Span, a label, related places, help, and whether the input is incomplete (what the REPL needs to wait for more lines). The prelude's own ReadError (text, line, column) is removed, and the compiler and the front end use the reader's.

A dot after a form, separated by a space (accepted, 2026-11-17)

(list (f x) .y) passes two arguments, while (f x).y reads a field (D029). A .name separated by a space from a closing bracket among a call's arguments gets a warning: ".y after a form is a separate argument: write (f x).y for the field". It is a check on tokens and costs nothing; putting .y on its own line silences it. When types are inferred (D007) the warning narrows to forms whose value is known to have that field.

Why

  • Rust and Ferron show that a diagnostic with the code and a hint saves most of the time spent on an error.
  • Coding agents fix errors faster from a precise location and a hint, and a machine-readable form lets them do it without parsing text.

Plan

The bootstrap interpreter (D012) prints the source excerpt with the underline now, since it already keeps positions; hints are added error by error. The full design, including JSON, belongs to the Diaspar implementation.