Skip to content

Formatter (clay fmt)

Implemented

One style for every Clay file: clay fmt, the editor's Format command, and what it promises about hashes and comments.

clay fmt formats Clay source like Prettier does JavaScript: print width 80, two-space indent, trailing commas where a list breaks, spaces inside braces, binary chains and -> pipes broken the Prettier way, a last-argument lambda hugging its call, JSX laid out like Prettier’s.

let todoCount = (todos: list<todo>, done: bool): int => todos->List.filter((t: todo) => t.finished == done)->List.size

becomes

let todoCount = (todos: list<todo>, done: bool): int =>
  todos->List.filter((t: todo) => t.finished == done)->List.size

Commands

  • clay fmt file.clay prints the formatted file; clay fmt --write src/ rewrites every .clay file under the arguments; clay fmt --check src/ writes nothing, lists what would change and exits 1 (for CI).
  • In the editor: the Format button or Shift-Alt-F formats the buffer in one undo step and keeps the cursor on the same code. A buffer with a syntax error is left alone and the problem is shown. Settings has a Format on save switch (off by default).

What it promises

Formatting only changes unhashed text, so it cannot change a hash. The formatter is tested to give the same lowered program (hence the same hashes) on every .clay file, doc snippet, corpus program and fuzzer program the repository has; saving a formatted copy of a stored definition says stored, not update. It is idempotent, never drops or reorders a comment, keeps blank lines (at most one) between items, and refuses a file with a syntax error instead of guessing. As a last check it re-parses its own output and returns the input unchanged if a token, a comment or a JSX text value differs.

A few Clay choices: statements in a block end in ; (not the last), switch arms have no separator, a variant is type t = A | B when it fits and one | Constructor per line otherwise, annotations and doc comments are kept as written, and JSX text is only re-wrapped where the compiler’s whitespace rules guarantee the same value. The full style is in docs/formatting.md in the repository.