Skip to content
Source on GitHubVisitors

16. Canonical layout

Contents of ATD 0.1

16.1 The layout

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.

16.2 Comments

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.

16.3 Idempotence

Formatting a formatted description changes nothing. A file that does not parse is not formatted: the formatter changes nothing and reports why.

16.4 Machine edits

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.

Referenced from