Formatting

talor fmt writes the canonical shape of a program:

talor fmt src/main.talor src/parser.talor   # in place
talor fmt --check src/main.talor            # writes nothing; exit 1, naming the file
talor fmt -                                 # the program on standard input, formatted, on standard output

--check is what a build calls: it writes nothing and answers 1 when the text is not canonical, naming the file. - reads the program from standard input, so cat x.talor | talor fmt - leaves the same text talor fmt x.talor would.

A file is replaced only when the text changes, and the replacement is written through a temporary file beside it, so an interrupted run leaves either the file it was writing or the file it had, never half of one.

The shape it writes

• A block with a statement in it is never on the header's line.
• Indentation follows the file's brackets.
• A list literal that does not fit the line breaks one element per line, with a trailing comma.
• Two top-level items are separated by one blank line, whether the source had one or not; more than one is written as one. A run of use lines is a group, and an attribute or pub belongs to the item under it, so no blank line goes between #[test] and the function it marks.
• Inside a block, a blank line the writer put there is kept, at most one. None is invented.
• A comment is never moved.

The style file

A package states its style in talor.fmt at its root, and the formatter finds it by walking up from the file it is formatting. One key = value a line, # starts a comment:

# two spaces, a narrower line, and a trailing comma in a broken list
indent = 2
max_width = 60
trailing_comma = true

indent is a number of spaces from 1 to 16, or tab. A package with no talor.fmt gets four spaces and a maximum width of 100, which is what the formatters of neighbouring languages default to.

A key this version does not know is named on standard error, once per style file, the file is formatted with the keys it does understand, and the command answers 0:

warning: 'src/talor.fmt' names 'indentt', which this formatter does not know; the key is ignored

The key is not an error, because a talor.fmt written for a later version of the formatter still says what this one understands - and the warning is what tells that file apart from a key that was mistyped.

In the editor

The same formatter is behind the language server's formatting request, so a save replaces exactly the lines that changed and a file that is already canonical comes back unchanged. Whether the editor formats on save, on type or on paste is the editor's own setting, and the indentation the editor sends with the request is what the formatter uses for it. The extension has one setting of its own, talor.format.configPath, which names the style file when the one found by walking up from the file is not the one meant.