Skip to content

Formatting

nomi fmt [-w|-l|-d|-check] <paths> formats Nomi source: -w writes the result to each file, -l lists the files that would change, and -d shows a diff. -check lists them as -l does and exits 1 when there are any, which is the check a CI step runs (-l exits 0). Editors format on save through nomi-lsp.

nomi fmt gives every program one layout and has no options. It indents 4 spaces per level and breaks lines at 100 columns. It keeps a few layout choices of the author’s, which Writing Nomi lists (Let nomi fmt own the layout), and decides the rest from the syntax and the width. The formatter’s package doc says why some of these rules are built the way they are.

Blank lines between statements. A statement that spans more than one line gets a blank line before it, unless it opens its block, and after it, unless it closes its block. A block’s final expression counts as a statement. Whether a statement spans lines is decided as rendered at the block’s indent, so a call that fits in a shallow block may break, and be set apart, in a deeper one. A case, a nested block, a triple-quoted string written across lines and a literal broken after its opening bracket always span lines. A stacked pipeline, or one broken because it does not fit, is set apart; one that fits on its line sits with its neighbours. A binding else is measured by its first line, so a run of one-line guards reads as one step; a binding else with arms is laid out as a case. One-line statements sit together, and a single blank line the author writes between them is kept. A blank line at the top or bottom of a block is removed, and a block’s imports are followed by one.

Strings and templates. A string is never split: a double-quoted one, typed (Html"...") or not, stays on its line however long. A triple-quoted one written on one line, Html"""<i>${n}</i>""", stays on one line when it fits, and is framed, its body on lines of its own, when it does not. A framed triple-quoted or multi-line backtick string’s body and closing delimiter share one indent, taken from the line the opening delimiter is on. A literal that starts its line (a statement, a function’s result, an argument on a line of its own) puts them at that line’s indent:

fn footer() -> Html
    Html"""
    <footer class="site">
      <p>Made with Nomi</p>
    </footer>
    """
end

A literal that follows code on its line (after a binding’s =, a struct field’s :, a map entry’s =>, a case arm’s or lambda’s ->, return, or a declaration’s header) puts them one level in, the way a broken pipeline continues after =:

fn page(name: String, avatar: Maybe<String>) -> Html
    title = Html"""
        <h1>${name}</h1>
        """

    case avatar
        Some(url) -> Html"""
            ${title}
            <img src="${url}" alt="">
            """

        None ->
            title
    end
end

A case arm’s or a lambda’s literal stays on the -> line. nomi fmt moves a body written at another indent to this one, with its closing delimiter, so the lines keep their nesting relative to each other and the string’s value is unchanged. A ${...} written on one line stays on one line, however long the line of text around it, since that text cannot break either. One whose expression spans lines, in a triple-quoted body, is laid out from the column of its ${, so its lines stay with the text around it. nomi fmt never changes the text of a string, a template’s markup included.

Pipes. A pipe written on one line stays inline, and one written across lines stays stacked, each |> aligned with the subject. An inline chain breaks only when it overflows; a stacked one is never joined. An overflowing chain bound to a name moves under the binding, one indent in. A pipeline with a then or tap stage is always stacked, since that lambda’s body ends at the next |>.

Bodies. A function’s, a declaration’s and a test’s body always goes on the lines below its header, one indent in, closed by end at the header’s indent; an empty one is end on the header’s line.

if, binding else and lambda bodies. See one-line if and binding else for when a guard or a two-branch if is written inline on one line (a two-branch if up to 50 columns, or up to the line’s width when its else is one atom such as None, 0, "" or []); an else if chain is always in block form. A binding else whose statement holds an if or a case is always in block form too, so else, return, if and then never share a line. An inline if too wide for its line is written in block form. An inline if that something follows on its line, a binary operator’s left operand or a pipe’s head, goes in parentheses, and an if stage that another stage follows is written in block form. A single-expression lambda whose body is an if holding break, continue or return goes below the header, closed by end, as does a value-producing lambda body that does not fit, and a call it ends closes with end). A body written below its -> stays that way (the formatter’s package doc says why).

case arms. When every arm fits on one line as pattern -> body and no body is a block, the arms sit on consecutive lines. Otherwise every arm breaks: a triple-quoted body keeps its """ on the pattern’s line, any other body, a block’s statements included, goes on the lines below the -> one indent in, and one blank line separates every two arms. A triple-quoted body breaks the arms as a block does, and so does a stacked pipeline. A binding else with arms lays them out the same way. The rule is deliberate: when any arm needs more than one line, every arm moves its body below -> with a blank line between arms, so the arms of one case always share one layout. Blank lines the source put between arms are ignored, and a comment stays above its arm.

Alignment. Consecutive one-line items of one construct line up:

  • a case’s arms, with or without a subject, at their ->;
  • a struct declaration’s fields, their types after name: (at: Place); a default’s = value is not a column of its own;
  • a multi-line struct or record literal’s fields, a multi-line call’s named arguments and a multi-line parameter list’s parameters, the value or type after name: (name: "goblin",);
  • a multi-line map literal’s entries, at =>;
  • rows: a multi-line list or argument list whose items are all tuples of one length, or all calls of one callee with one argument count, pads each column after its comma to the column’s widest entry (("Mei", 100),), as a subtests table is written;
  • comments that end consecutive lines of code at one indent;
  • consecutive once declarations, at their =.
struct Monster
    name:       String
    hit_points: Int = 10
end

fn label(n: Int) -> String
    case n
        0   -> "none"
        100 -> "a hundred"
        _   -> "some"
    end
end

A block is a run of such items on consecutive lines at one indent. A blank line, a comment line or an item over several lines ends it, and each run aligns on its own, so a case whose arms put their bodies below -> aligns nothing. Where a run breaks follows gofmt: two neighbouring items whose left parts are both at most 40 columns wide always align, and past that an item starts a new section when its left part is 2.5 times wider or narrower than the geometric mean of its section’s so far. Each section aligns on its own, so one long item leaves the lines around it aligned; rows have no such limit. Widths are display columns, as line width is measured. Alignment comes after the line breaks and never changes one: a block that padding would take past 100 columns stays unaligned. Local bindings’ =, enum variants’ payloads, one-line literals and pipelines are not aligned.

Trailing commas. A multi-line call has a trailing comma after its last argument when it has more than one argument, and none when it has one.

Declarations. Declarations with bodies get a blank line between them. Bodyless declarations of one kind (once, type, typealias, host type, host fn, a run of derives for one type) may sit together, and a blank line written within a kind is kept; different kinds are separated by a blank line. A bodyless declaration with a doc comment stands apart. The same holds inside impl and interface blocks. Consecutive derives for one type lose the blank lines between them. A test group’s clock, boot and setup move to the top of the group in that order.

Imports. A file’s or block’s imports are combined into one import block, import alone on its line, one entry per line and end, sorted with std:: paths first, and a lone import stays bare. Separate import lines of one path merge into a selector list (import std::calendar.{Date, Months}); two entries of one block do not. A comment line between two import statements keeps them apart, and each side is combined and sorted on its own. A file with both writes an import block and then a pub import block. An import inside a block moves to the top of that block.

Tail return. A return that is the last thing a function, lambda or test body does is removed, including the last expression of each branch of a tail if and each arm of a tail case. A bare return at the end of a Unit body goes when an expression statement comes before it. In a test body, a tail if or case keeps its return values, since its branches’ values need not share a type there. A tail if with no final else keeps its return values too, since such an if is a statement and has no value.

Struct literals and anonymous struct types are kept on one line when short and broken one field per line, each with a comma, when long (brace-bounded field constructs). An anonymous struct type or variant written across lines keeps one field per line. Literals follow a line break after a literal’s opening bracket; lists of numbers are filled; long comparisons and boolean chains break before the operator; three levels of brackets break the outermost; and comments stay with their item. A trailing comment is never moved to make room, so it may run past 100 columns.

Small layouts. One space follows not, and parentheses written around it or its operand stay. A ? or ! sits against its expression. In a block if, else and else if c then start their own lines at the if’s indent. A long or pattern breaks after each or. The arms or branches of a |> case or |> if stage sit one indent in from the line its |> is on.