Skip to content

2. Lexical structure

A source file is UTF-8 text. Outside string literals, codepoint literals and comments it holds only ASCII: any other character is an error at that character (unexpected `Ã`).

A line ends in \n or \r\n, and the two mean the same program: a multi-line string or a comment holds no \r from a \r\n line end.

Spaces, tabs and line ends separate tokens. Indentation has no meaning to the grammar. Only a multi-line string’s body (§3 String Literals) and the lambda body check (§7 Lambdas) read it.

A file may begin with a #! line, so that it runs as a script (tooling reference). The #! must be the file’s first two bytes. The compiler ignores the rest of that line, and line numbers count it, so every later line keeps its position in diagnostics, test reports and the editor. #! anywhere else is the error a `#!` line is allowed only as the first line of a file, starting at its first byte.

#!/usr/bin/env nomi
import std::io

fn main()
    io.print("hi")
end

Taught in Bindings & Expressions.

Every comment runs from its marker to the end of the line. There are no block comments.

MarkerMeaning
//An ordinary comment. Four or more slashes are one too.
///A doc comment. It documents the declaration that follows it.
//#File-level documentation. To the compiler it is an ordinary comment that attaches to nothing; the standard library reference reads a module’s //# lines as its page intro.
//!An attached test line (§17).

A /// comment with no declaration after it, above an import or a test for instance, is the error a `///` doc comment must be followed by a declaration it documents; use `//` for an ordinary comment or `//#` for file-level text. Inside a body, a /// line is the error a `///` doc comment documents the declaration after it, so it can't go inside a body; use `//` for a comment here, and so is a //! line that no nested declaration follows.

A //! line must start its line. After code on the same line it is the error a `//!` attached test must start its own line, above the declaration it tests; write `//` for a comment after code.

A comment may stand inside a bracketed, comma-separated list: a call’s arguments; a list, vector, set, map, tuple or struct literal; a function’s or lambda’s parameters; type parameters and type arguments; a list, vector, set, tuple, map, struct or variant pattern; a destructure; and an import’s {...} selector. It goes on a line of its own before an item, after the opening bracket or after the last item, or at the end of a line after an item’s comma.

fn add(a: Int, b: Int) -> Int
    a + b
end

fn main()
    total = add(
        // the base
        1,
        2, // the step
    )

    dbg total // 3
end

An identifier is an ASCII letter or _, followed by ASCII letters, digits and _. Its first character decides its class:

  • A name that starts with an uppercase letter is a type name: a type, an interface, a type parameter, an enum variant, or the prefix of a typed literal.
  • Any other name is a value name: a function, a binding, a parameter, a field, a once, a module.

A type name is PascalCase and holds no _. A value name is snake_case and holds no uppercase letter. The checker enforces both, for every kind of declaration:

EntityCaseExample
Types (struct, enum, type, typealias, interface)PascalCaseUser, HttpRequest
Enum variantsPascalCaseSome, Active
Type parametersPascalCaseT, Elem
Functions, bindings, parameters, fields, once valuessnake_caseparse_input, max_retries
Modules (files)snake_casemath_utils

userName = 1 is the error binding name "userName" must be snake_case, and struct Http_Request is struct name "Http_Request" must be PascalCase.

Case is not visibility: a declaration is visible outside its file only when it is pub (§14).

A ? or ! written right after a name is the postfix operator of §11, not part of the name: f?(x) propagates the failure of f and calls the function it holds.

In a binding position, _ and a name that starts with a single _ (_unused) are discard names. A discard name matches any value and binds nothing; _name only labels the value for the reader. Read as a value, _ is the error `_` is a discard name, not a value. That error makes _ a typed hole: where the place it stands in expects a type, its help names the type and the values in scope that have it, nearest binding first, as in as a hole, it stands for a value of type `String` and in scope with that type: `label`, `fallback`. A program with a hole does not run. A name that starts with two underscores (__x) is not a discard name; it is an ordinary binding.

These words are reserved and cannot name anything:

and, as, assert, begin, break, case, continue, dbg, defer, else, end, enum, export, extern, fn, for, if, impl, import, in, interface, is, not, once, opaque, or, pub, refute, return, self, struct, subtype, tap, test, then, type, typealias, unreachable, when, where, with.

One written as a parameter, a binding, a field or a function’s name is the error `type` is a keyword (declares a distinct type), so it can't name a binding; name it something else, such as `kind`, which says what the word is for and offers another name.

when stands only before an arm’s guard (§10 Guards) and a type’s rule (§4 Subtypes, §4 Validated types). extern has no construct: extern fn is the error runtime-provided declarations use `host fn`, not `extern fn` , and extern before any other declaration is unexpected 'extern'; runtime-provided declarations use `host`, and Go package handles use `gopkg`.

These words have a meaning only where their construct stands, and are ordinary names elsewhere: host (§19), open (§12), embeds (§4), phrase, noun and embed (§18), concurrent (§16), and group, clock, boot, setup and subtests (§17), and todo (§11).

todo names anything a name can: a parameter, a binding, a field, a function, a pattern’s binding, an import. Read as a value, a bare todo is the placeholder unless a binding named todo is in scope, and then it reads that binding:

fn apply(todo: Todo) -> Todo
    todo
end

returns its argument. Inside that scope the placeholder is written with a reason, todo "apply the patch", which is always the placeholder. A function named todo is such a binding throughout its file and in a file that imports it by name. A module named todo (a file todo.nomi) is not a value, so it leaves a bare todo the placeholder; todo.create(...) still names its member.

derive, gopkg and go may name a parameter or a binding, but a statement that begins with one of them always starts that declaration. So derive + 1 is an error (expected interface name after `derive`) even inside fn f(derive: Int).

TokenUse
+ - * / %arithmetic (§8)
== != < <= > >=comparison (§8)
and or notlogic (§8)
is inpattern test and membership (§8)
&&& ||| ^^^ ~~~ <<< >>>bitwise operators (§8)
? !postfix propagate and unwrap (§11)
|>pipe (§8)
->function result, lambda body, case arm
=>map entry
=binding and declaration punctuation (below)
.. ..=ranges (§3); .. is also a spread and a rest pattern
.field access, .Variant, field accessor
::joins the segments of a file’s path, with no space around it (§14)
&a capture, and &1, &2, … its parameters (§7)
, : ;separators
( ) [ ] { }brackets

The C-family spellings are errors that name Nomi’s: a && b is Nomi spells logical and `and`: write `a and b`, not `a && b`, and ||, !x, << and ~ get the same kind of message. @, ^ and a lone | are not operators.

= matches a pattern only where its left side is a pattern: a local binding, a destructure, a parameter pattern, if Pattern = expr, a binding with else (Pattern = expr else return 0) and assert Pattern = expr. Its other uses are punctuation that names or configures a value and matches nothing: a parameter’s or a field’s default (port: Int = 8080), a once initializer, and with App.logger = logger. = is never assignment.

A newline ends a statement where the statement could end. After a token that cannot end one, such as an operator, ,, = or an opening bracket, the statement continues on the next line.

A line that starts with a token no expression can start with continues the line above: |>, ), ], a comparison (==, !=, <, <=, >, >=), a bitwise operator other than ~~~, and, or, is, in and where. So a long condition breaks before its operator:

fn in_grid(rows: Int, columns: Int, top: Int, left: Int, bottom: Int, right: Int) -> Bool
    bottom > top
        and right > left
        and Int.max(bottom, right) < Int.min(rows, columns)
        and Int.min(top, left) >= 0
end

fn main()
    dbg in_grid(5, 5, 0, 0, 3, 3) // True
end

A line that starts with an arithmetic operator does not continue, since - also starts an expression: + 2 alone on a line is the error `+` cannot start a line: the line break ended the expression before it. The operator goes at the end of the line above.

; ends a statement explicitly, so several fit on one line: database.save(db, page)?; count + 1.

A statement that starts right after the end of another, with no space, newline or ; between them, is an error at its first token: "a"[1] is a string followed by a list, unexpected `[` right after the end of a statement.

Code is never written in braces. Every construct that holds statements, a function, an if branch, a case’s arms, a lambda, a declaration’s body, is a header line, the body on the lines below it, and end:

struct Point
    x: Int
    y: Int
end

fn norm(p: Point) -> Int
    if p.x > p.y then p.x else p.y
end

fn main()
    dbg norm(Point{x: 3, y: 4}) // 4
end
  • A header ends at the end of its line. Brackets carry it across lines, and a line that starts with where continues it with long bounds, as a line that starts with |> or a binary operator continues an expression.
  • The body starts on the line after its header. Anything but a comment after the header on its line is the error unexpected ...: a function's body starts on the line after its header and ends at `end`, which names the construct.
  • A { that ends a header line, where a brace-bodied body would open (fn f() -> Int {, if c {, case x {, struct P {, import {), is a body is written on the lines after its header and closed by `end`, not in braces, whose fix removes the {. When a file does not parse, this error at its first such { comes before any other, since the brace is what the later errors stem from.
  • An empty body is one line: fn noop() end, struct Empty end, impl Marker for P end.
  • begin and end around statements are a block expression (§8 Block expressions).
  • An if whose then has more on its line, an arm whose -> has more on its line and a lambda whose -> has more on its line are one-line forms with no end (§8 if/else, §8 case, §7 Lambdas).

Braces and brackets hold data only: struct and map literals, lists, sets, vectors and their patterns and types (§3). A { always begins data.