6. Declarations and scope
Top-level declarations
Section titled “Top-level declarations”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).
Bindings
Section titled “Bindings”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.
Shadowing and redeclaration
Section titled “Shadowing and redeclaration”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.
once Bindings
Section titled “once Bindings”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 = expressionis optional; the type is inferred otherwise, and holds at every read, in any file and above the declaration. Unannotatedoncevalues 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 animpl Iface for Typeblock it isinterface 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,continueor 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 nestedfnor aconcurrentblock inside it is a boundary of its own. - Cycles. A
oncewhose initializer reaches theonceitself 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). Eachonceon the cycle is reported. The check follows, across modules, what an initializer does while it runs: eachonceit 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 asType.f, an interface function called on a value of a concrete type (Display.to_string(money)), a pipe stage ortapnaming a function, and the lambda athenortapstage applies. Every branch counts, whether or not initialization takes it. A lambda, capture or nestedfnwritten anywhere else runs when something calls it, so aoncethat holds a lambda reading theonceis 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
oncethat holds a lambda or a partial capture is a value, and a call through it passes every argument (§7 Default Arguments).
A name declared twice
Section titled “A name declared twice”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.
Resolution and declaration order
Section titled “Resolution and declaration order”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.