---
title: "Canonical form"
url: https://una-lang.org/en/docs/language/canonical-form/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/guide/syntax-reference.md
---

# Canonical form

Every file has one canonical form. `una fmt` rewrites a file into it, and `una check` reports every difference as U7001, an error with a mechanical repair. Code that a program generates should go through `una fmt` before `una check`. A file with a syntax error has no canonical form: it is neither formatted nor checked for U7001. The rules, from `spec/15`:

**File**

- Line breaks are `\n` only.
- The file ends with exactly one line break.
- No line has trailing whitespace.
- The file neither starts nor ends with a blank line.

**Lines and indentation**

- Two spaces per indentation level.
- Every logical line is one line. The formatter has no maximum line width, so lines continued inside brackets are joined (§1.2).
- The exception is a line with a comment inside its brackets: its line breaks are kept, and each continuation line is indented one level deeper than the line.
- Every token keeps its source spelling: integer literals keep their `_` groups (`1_000`), and text literals their escapes.

**Spacing.** Tokens are separated by one space, except:

- no space after `(`, `[` or `.`, and none before `)`, `]`, `,`, `:` or `.`;
- no space around `..` and `..<`;
- no space after a unary `-`, unless another `-` follows;
- no space between a name and a following `(` or `[`, and none in `fn(` and `checked(`, but one space between an import's module path and its `(`;
- no space inside a text literal outside its interpolations, and none just inside the braces of an interpolation.

**Functions and bodies**

- Header clauses and op clauses are in canonical order (§4.2, §7.1), with one `uses` clause per capability.
- A function with no clauses and a body of one plain line uses the short form (§4.1). The same holds for the body of a predicate or handler operation after its `=`, and of a `when` arm after its `->`.
- A plain line has no `with` clause and no handling clause, and is not a `when` or an `if` with blocks. Otherwise the long form stays, and it also stays when a comment sits between the head and the end of the body.
- Handling clauses sit on their own indented lines, directly below the statement.

**Sums.** A sum with two or more variants has no leading `|`. A sum with one variant keeps it, since the grammar requires it: `kind PhoneError = | Malformed`.

**Constructors**

- When every argument of a record or variant constructor is labeled or punned, the arguments follow the order in which the fields are declared (§4.4).
- This applies to the records and variants the file declares or imports, and to the variants of the sum kinds it imports, when the name comes from exactly one of them and is declared once in its module.
- Arguments are not reordered on a line with a comment inside.

**Imports**

- Imports are sorted bytewise by module path, each keeping the comments that lead it: `events.keys` before `events.seating` before `std.testing`.
- The names inside each import are sorted bytewise too (`Availability, Event, availability`: uppercase letters sort before lowercase), unless a comment sits inside the import.

**Blank lines**

- Top-level items (the module header, each import and each declaration) are separated by exactly one blank line, except consecutive imports, which have none.
- Elsewhere, a run of blank lines becomes one blank line.
- No blank line follows a line that opens a block, and none precedes or follows the `=` line of the long form.

**Comments**

- The formatter never moves a comment to another line, and it removes trailing whitespace from the comment's text.
- A comment at the end of a line of code stays there, after one space.
- A comment on its own line stays in place, at the indentation level nearest to its column (ties go deeper) among the levels of the lines around it.
- A comment on its own line at level 0 between two top-level items belongs to the next item, and the item's blank line goes before it.

**How U7001 is reported**

- `una check` compares each file with its canonical form line by line, and reports one U7001 per changed region, at its first source line.
- Each U7001 carries a mechanical edit that replaces the region with its canonical text, and its message names the difference: trailing whitespace, a missing or extra blank line, a missing final line break, or lines that are not in canonical form.
- A file with `\r\n` line breaks gets a single U7001 at the first of them, without an edit (§1.1). Run `una fmt` to fix it.

---
