Skip to content

Files and layout

Run nomi fmt -w after editing a .nomi file, or let the editor format on save through nomi-lsp. Don’t line code up by hand or fight a break fmt chose. What it does is in the tooling reference; the choices it leaves to you are these:

  • A pipe inline or stacked (§7). fmt keeps the form you wrote.
  • A blank line between one-line statements to mark a step. fmt keeps one; it sets multi-line statements apart on its own.
  • A literal broken after its opening bracket stays one element per line even when it would fit. Delete that one line break to let fmt join it.
  • A lambda body below its ->, closed by end, stays there. Write fn x -> x + 1 to let fmt put a short body on the header’s line.
  • A blank line within a run of one-line declarations (once, type, host fn) marks a group. Use one only at a real boundary.

Order declarations by what helps the reader build the API model first.

The normal file shape is:

  1. imports, when needed
  2. file-level once values
  3. public types, each followed by its impl block, derives and interface impls
  4. file-level functions: entry points first, then helpers
  5. standalone named tests

A type’s own operations and constants go in an impl Type block right after the type, and its derives and interface implementations follow that block. A once that describes a type (Float.pi, Status.ok, RetryPolicy.default) belongs in that block, so a caller reaches it through the type; a file-level once is for a value that belongs to the file, such as its configuration or a lookup table its functions share:

pub struct RetryPolicy
    attempts: Int
    delay:    Duration
end

impl RetryPolicy
    pub once default = RetryPolicy{
        attempts: 3,
        delay:    Duration.seconds(1),
    }

    pub fn with_attempts(policy: RetryPolicy, attempts: Int) -> RetryPolicy
        {..policy, attempts:}
    end
end

derive Equatable for RetryPolicy

impl Display for RetryPolicy
    fn to_string(policy: RetryPolicy) -> String
        "${policy.attempts} attempts"
    end
end

An impl for a type from another file sits with the code that needs it.

This is a house style. Keep a different order when the local narrative is clearer, for example a tiny helper type right next to the one function that builds it, or a once right above the one function that reads it.

Attached tests (//!) stay with the declaration they exercise, even if that means a test appears before later functions. The ordering rule is for independent declarations.

Import a file for its file-level functions and a type by name (spec §14 Import forms; tour: Modules & Imports). import std::io and then io.print(x) keeps the file’s name at each call, so the reader sees where print comes from. import std::calendar.Date and then Date.parse(text) names the type once, and every call through it says which type it works on. Don’t import a file only to write calendar.Date at every use.

import
    std::calendar.{Date, Months}
    std::io
    myapp::config.Config
end

Several names from one path go in one selector list, as std::calendar above.

Use self only when you need both an owner (a file or an enum type) and selected children from it. self inside an owner selector binds the owner as well as the named items, so one line replaces two:

// no
import
    shape.Shape
    shape.Shape.{Circle, Rectangle}
end

// yes
import shape.Shape.{self, Circle, Rectangle}

If you need only the owner or only one member, don’t add self for its own sake: import shape.Shape and import shape.Shape.Circle stay as they are.

A dot-shorthand pattern (.Some(v)) names no imported variant, so don’t import a variant you only match with the dot form.

Use a file by its short name, the last part of its path: import db::posts, then posts.find(1). Where the short name is ambiguous (two files share it) or taken (a declaration has it), import the directory and write dir::file at the use; alias the file only where a directory import does not help (spec §14 Short names, Directory imports; tour: Modules & Imports). The path says which file at the use itself; an alias is one more name to look up.

// no
import
    db::notifications as db_notifications
    jobs::notifications as job_notifications
end

// yes
import
    db
    jobs
end

fn pending() -> Int
    db::notifications.pending() + jobs::notifications.pending()
end

Import a directory to reach several files under it with one line: import views::admin, then admin::users.index(rows) and admin::reports::daily.show(). Don’t import a directory to reach one file whose short name is free; import views::admin::users and users.index(rows) say the same thing more briefly.