Skip to the content
Diaspar

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)

  1. 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: cond read in pairs, let bindings one per line. Indentation-only (cljfmt) leaves overlong lines.

  2. 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")))
  3. 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.

  4. 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.

  5. Blank lines (accepted, 2026-11-16):

    • After the header, two. The header is the file's leading comments and its block of use forms; 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 use block, 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]
      …)
  6. 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).

  7. 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, use name 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 a str alternating short calls and strings stays compact. Packing still starts only after a simple first argument, so an if'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 cond clause 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 a defn on its own line, nine lines for a str), and Black's stages (all remaining items on one line: mixes an if's branches, or parameters with the body). No rule by shape keeps match and cond clauses 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.