Decision D031 · accepted; details proposed
The formatter: diaspar fmt
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-16) for the choices below; proposed for the details
Decision
Diaspar has one formatter, diaspar fmt, written in Diaspar. It gives all code one style, so style is never discussed in reviews and agents never fight over indentation.
diaspar fmt ; formats the package's files in place
diaspar fmt src/app.dias ; the files given
diaspar fmt --check ; changes nothing; exits 1 and lists the files that would change (for CI)
The choices (accepted)
-
The middle way, as gofmt and rustfmt. The author's line breaks are kept; indentation and spacing are normalized; a line wider than the limit is broken. Full re-layout (Prettier, Black, zprint) loses the author's grouping, which in a Lisp often carries meaning a formatter does not know:
condread in pairs,letbindings one per line. Indentation-only (cljfmt) leaves overlong lines. -
The simple indentation rule (Tonsky's "better Clojure formatting"): the items of a list
(broken across lines are indented by 2 under the opening bracket; the items of a vector[or a map or set{#{by 1, aligned just inside the bracket. No form needs to be known, so a new macro is formatted like everything else, with no configuration. The REPL's line editor already indents this way (D024); both use one implementation of the rule.(defn check [files] (let [results (map check-one files) failed (count (filter failed? results))] (print f"{failed} failed"))) -
No options, as gofmt and Black: one style for every package. Only the line width can be changed (
--width, default 120; accepted, 2026-11-16), for terminals and diffs. -
Nothing is lost: comments stay where they are, relative to the code; brackets keep the shape the author wrote (D008); labels, f-strings, and string contents are kept verbatim.
-
Blank lines (accepted, 2026-11-16):
- After the header, two. The header is the file's leading comments and its block of
useforms; two blank lines separate it from the code. - Between top-level forms, one. Functions, definitions and other top-level forms are separated by exactly one blank line; one-line forms the author wrote next to each other (a group of short
defs) may stay together. - Inside the
useblock, none or one, as the author wrote, to group imports, as Python's PEP 8 groups standard, third-party and local imports. - Inside forms, at most one in a row.
- A comment directly above a form belongs to it; blank lines go before the comment.
;; jt: a JSON tool. (use std.fs) (use std.json) (use jt.theme) (defn load [path] …) (defn save [path data] …) - After the header, two. The header is the file's leading comments and its block of
-
Trailing comments on adjacent lines are aligned in one column, as gofmt does (accepted); a line without a trailing comment inside such a block does not break the alignment (accepted, 2026-11-16).
-
Breaking a line the author left too long (accepted, 2026-11-16, chosen after comparing four rules on the repository's code). By shape alone, with no knowledge of forms:
-
A list: if it fits, one line. Otherwise the first line holds the head and the first argument, and, only when that argument is simple, the simple items that follow while they fit (symbols, keywords, strings, numbers, short vectors and maps that fit flat, a label with its value). The rest go below, indented by 2: each list on its own line, runs of simple items packed to the width, a label or keyword never separated from the item after it.
(defn- path-vars [p] (match p …)) (if (and (plain-name base) (not (generated-name? base))) base (str base "_" v.id)) (str "DSP_CALL" k "(ctx, " cell ", 1, " direct (if (empty? args) "" ", ") (args-c fcx args pos) ")") -
A code vector
[ … ]that looks like bindings (even length, and something other than a symbol among the values) breaks one pair per line; other code vectors (parameters,usename lists) and data vectors#[ … ]are packed to the width; maps break between pairs.(loop [pairs (vec (map vec (partition 2 b.items))) body (vec (drop 2 items)) out #[]] …) -
A short call counts as simple when packing (accepted, 2026-11-16): a list that fits flat in about 30 columns, such as
(n)or(get macros prim), is packed like an atom, so astralternating short calls and strings stays compact. Packing still starts only after a simple first argument, so anif's branches are not packed. -
A hanging indent for lines the formatter breaks (accepted, 2026-11-16): when the formatter must break a line the author wrote as one, the continuation is indented 2 deeper than the items that start the author's lines, as gofmt and Black indent continuation lines. So a
condclause too long for one line stays visibly one clause:(cond (empty? else) (vec (concat #[head] t)) (get mode :tail) (let [t (fresh lcx "")] …) :else nil) -
Rejected: breaking only the last item ("hug": the result drifts to the right), one item per line (rustfmt, Prettier:
[p]of adefnon its own line, nine lines for astr), and Black's stages (all remaining items on one line: mixes anif's branches, or parameters with the body). No rule by shape keepsmatchandcondclauses in pairs when they were written on one overlong line; when the author breaks them by clause, that is kept.
-
Details (proposed)
- Spacing: one space between items; no space after an opening or before a closing bracket; closing brackets gather at the end of the last line, never on a line of their own.
- Lossless input: the formatter reads with the compiler's reader and recovers comments and white space from the source text between the spans of the syntax nodes, so the reader needs no separate mode; a lossless syntax tree for the language server and refactoring may come later on the same idea.
- Safety: formatting never changes what the code means. The formatter checks that the formatted text reads to the same data as the original (ignoring positions), and refuses to write otherwise. Formatting is idempotent: formatting twice changes nothing.
- Where it lives: in the toolchain's package (
diaspar.fmt), with the indentation rule shared with the REPL's editor.
Why
Formatters that leave no choices (gofmt, Black, rustfmt with defaults, zig fmt) ended style debates in their languages, and generated code and agents benefit most from one canonical form. The middle way respects the structure the author chose, which Lisp code relies on, while still giving every file the same look. The simple indentation rule is the one choice that needs no knowledge of forms, so macros never need formatter configuration.
Rejected alternatives
- Full re-layout (Prettier's Wadler-style printer, zprint): loses the author's grouping.
- Indentation only (cljfmt): long lines stay long.
- Semantic indentation (Emacs, cljfmt's body rules: bodies by 2, arguments aligned under the first): prettier for known forms, but every macro needs a rule, and a missing rule gives inconsistent code.
- Configurable style: brings back the debates the formatter exists to end.