16. Canonical layout
Contents of ATD 0.1
The formatter writes a description in one canonical layout (FR-032):
- two spaces of indentation per level of braces;
- one member per line; a block of settings (an attribute's, a style's, a shape's and the like) on one line when it holds no comment and fits in 120 columns, otherwise one setting per line between
{and}; a block of members always one member per line; - one space around
:of a setting after it only, around binary operators, after,, and before{; none inside parentheses and brackets; - members in the order written: the formatter never reorders;
- one blank line kept where the text has one or more between members; none at the start or end of a block;
- the file ends with one line end, LF unless the file's first line ends with CRLF.
Every comment stays with its construct:
- a comment on a line of its own belongs to the next construct, and is written above it at its indentation;
- a comment at the end of a line belongs to the construct on that line, and stays at its end;
- a comment before a closing brace, or at the end of the file, belongs to the enclosing block, and stays last in it.
Formatting a formatted description changes nothing. A file that does not parse is not formatted: the formatter changes nothing and reports why.
An edit a machine makes to a description (a refresh, an agent, a rename) MUST be possible as splices that leave every byte outside them as it was (FR-033): a rename is one splice per use, a fix a set of splices. The formatter's own output is the one edit that may rewrite a whole file.