Skip to content

6. Declarations and scope

A file’s top level holds declarations only: imports, functions, types, interfaces, impls, derives, once values, tests, host declarations and keyword declarations (phrase, noun, embed). A binding, an expression or another statement at top level is an error; code runs inside a function. x = 3 at top level is a binding cannot be written at file level: a file binds a value only with `once`.

A top-level declaration is private to its file unless it is pub (§14).

Taught in Bindings & Expressions.

Inside a body, pattern = value evaluates value, matches it against the pattern and binds the names the pattern introduces. A binding is immutable; there is no assignment. A pattern that can fail takes an else (§10). An optional annotation follows a plain name: count: Int = parse(s)? (§5).

fn main()
    x = 5
    (a, b) = (1, 2)
    dbg x + a + b // 8
end

Every name a binding, a parameter or a pattern introduces must be read. That includes a destructured parameter’s names, the names a case arm, an else arm, an if condition or a test’s setup binding introduces, and parameters in every body (boot and interface defaults included). An unread one is an error: fn f((word, count): ...) that reads only count is parameter 'word' is never read. A value kept on purpose is bound to a discard name (§2 Discard names). A struct pattern leaves out a field it does not need (.Suspended{reason:}). An impl function that must keep a parameter’s name may discard it in its body with _ = name. A bodyless declaration has nothing to check.

An ordinary name = value binding may shadow an earlier binding or parameter in the same scope, and a file-level declaration. The newest binding is the one later code reads, and it may have another type. A closure made before the shadow keeps the value it captured (§7 Closures).

fn normalize(name: String) -> String
    name = String.trim(name)
    name = String.lowercase(name)
    name
end

fn main()
    dbg normalize("  Ada ") // "ada"
end

Bindings in nested scopes (bodies, lambdas, case arms) may shadow outer ones.

Every other declaration is declared once in its scope: two once, fn, type, struct, enum, interface or typealias declarations of one name, two parameters of one signature, and one name twice in a pattern are errors ('x' is already defined in this scope as a once binding). A top-level declaration that shares a name with an imported name is an error too (§14). There is no last-wins rule.

Taught in Bindings & Expressions.

once name = expression declares a value computed the first time it is read and kept for every later read. It stands at file scope or in an inherent impl block, and is read like any value (config.value, Money.zero_usd), with no call. It is the only file-level value computed by code; an embed declaration (§18 Embedded files) names a value of files read when the program is compiled.

once max_retries = 3

struct Money
    cents: Int
end

impl Money
    pub once zero = Money{cents: 0}
end

fn main()
    dbg max_retries      // 3
    dbg Money.zero.cents // 0
end
  • Annotation. once name: T = expression is optional; the type is inferred otherwise, and holds at every read, in any file and above the declaration. Unannotated once values whose values read each other have no type to infer: once 'a' has no type annotation and its value depends on its own type (a → b → a) — annotate it (`a: T = …`), at each.
  • Where. In a function body it is 'once x' must appear at file level or in an inherent impl block — function bodies use ordinary 'name = value' bindings. In an impl Iface for Type block it is interface impl blocks hold only `fn` / `host fn` implementation items; write `once` as a file or inherent impl declaration. It may not stand in a type body either.
  • Effects. The initializer may do anything a function call may. Its effects happen once, on the first read, even when several tasks read it at once.
  • No early exits. An initializer is not a function body, so a ?, return, break, continue or assertion written directly in it is an error at that token: `?` cannot be used in the initializer of `once port`: a `once` has no function to return from. A lambda, a nested fn or a concurrent block inside it is a boundary of its own.
  • Cycles. A once whose initializer reaches the once itself is an error at its declaration, naming the chain: cyclic 'once' binding: `seed` depends on itself: it calls `read_seed` (main.nomi:7), which reads `once seed` (main.nomi:4). Each once on the cycle is reported. The check follows, across modules, what an initializer does while it runs: each once it reads, and each call whose function is known when the program is compiled, into that function’s body and on. Those calls are a call by name or as Type.f, an interface function called on a value of a concrete type (Display.to_string(money)), a pipe stage or tap naming a function, and the lambda a then or tap stage applies. Every branch counts, whether or not initialization takes it. A lambda, capture or nested fn written anywhere else runs when something calls it, so a once that holds a lambda reading the once is no cycle: once retry: () -> Int = fn -> retry() + 1. Not followed are a call through a function value, an interface value or a type parameter, an operator’s implementation, and a default argument. A cycle closed through one of those traps when the read re-enters, at that read: line 2: cyclic 'once' binding: 'a' depends on itself.
  • A function value has no defaults. A once that holds a lambda or a partial capture is a value, and a call through it passes every argument (§7 Default Arguments).

Each name inside a declaration is declared once: a struct field, a struct-shaped variant’s field, an enum variant, an interface function, and a function’s or lambda’s parameter declared twice is an error at the second, with a note at the first: field 'x' is declared twice in struct `Point` . So is a repeated field in an anonymous struct type.

Two functions on one line of an interface body are a parse error, interface functions are newline- or semicolon-separated, as two fields on one line of a struct body are (§4 Structs); a ; may separate them.

Names resolve over the whole program. A top-level declaration is visible in its whole file, above and below it, and order between files and imports never matters (§14).

A nested fn or type in a body is visible in the rest of its block and the blocks inside it, and not outside. A nested fn can call only fns declared before it, so nested fns are never mutually recursive.

Inside an impl or an interface default, a bare call first uses the name’s lexical binding, a local function value or an ordinary file function included; a function of the same owner supplies the callee only when no such binding exists. The same order holds for a pipe stage.