Home / Docs / Specification
04. Functions and contracts
Status: Normative, v0.1.
1. Declaration forms
A function is written as header = body. The header is the contract; the body is the implementation.
double(x: Int) -> Int = x * 2 -- short form: no clauses
pub availability(e: Event) -> Availability -- long form
ensures e.remaining < 1 implies result is SoldOut
derived from EVENTS_3
=
when e.remaining
in 0..0 -> SoldOut
in 1..<20 -> Few
in 20..5000 -> OpenThe short form is canonical when there are no clauses and the body is a single-line expression; otherwise the long form is canonical (una fmt converts). The v0.1 formatter does not enforce a maximum line width. The whole canonical form is defined in spec/15.
2. Clauses
| Clause | Meaning | Verification |
|---|---|---|
requires p |
Precondition over parameters | Obligation at every call site; hypothesis inside the body |
ensures q |
Postcondition over parameters and result |
Obligation on every normal return path; hypothesis for callers after the call |
uses @c: C[ops] |
The function may perform operations ops through capability @c |
Effects of the body MUST be included (U3003) |
fails E |
The function may fail with variants of sum kind E |
Failures of the body MUST be variants of E (U3009) |
derived from R1, R2 |
Traceability to requirements | Each Ri MUST be declared (U1006) |
Rules:
requiresandensuresMUST be in RL (spec/03 §3), U2014 otherwise.ensuresdescribes normal returns only. Failures carry no postcondition in v0.1.- Contracts express partial correctness:
ensuresholds if the function returns. Termination is not checked in v0.1. - A function without
failscannot fail. A function withoutusesis pure: it cannot contain any@(U3004).
(v0.2, ADR 0056.) A parameter MAY be declared edit or take (spec/17 §3). In ensures, an edit parameter denotes its final value, and old(x) its value on entry.
3. Calls and labeled arguments
- A call with one argument MAY omit the label.
- A call with two or more arguments MAY omit the label of the first argument and MUST label all others (U2004). An unlabeled first argument always binds the first parameter, whatever its name (ADR 0049). Unknown labels are U2005; duplicates U2006.
- Punning: from the second argument on, an argument that is a bare identifier equal to the parameter name counts as labeled:
record(key, decision)isrecord(key: key, decision: decision)when those are the parameter names. With parameters(a, b),minus(b, a)bindsbtoaand givesatwice (U2006). - Record and variant constructors with two or more fields require every field labeled (punning allowed), in any order; missing or unknown fields are U2009. The formatter orders them by declaration. A constructor with exactly one field MAY omit the label (
Some(a)), and a pattern on a single-field variant MAY bind the field under any name (is Some(a)). - Arguments are evaluated left to right in source order. A constructor's arguments are evaluated in the order its kind declares its fields, the order canonical form gives them (rule 4, spec/15), so the two orders agree on every program that checks; a source that writes them in another order is U7001 (ADR 0081).
Method-call syntax. e.f(args) means field access followed by a call if the type of e has a field f of function type; otherwise it means f(e, args) with f resolved in scope, e taking the first parameter unlabeled. e.f without arguments is field access, or f(e) if no field f exists and f is a function with one parameter. xs.len and t.len are built in.
4. One effect per line
A capability operation, or a call to a function that uses capabilities or can fail, MUST be the entire expression of a statement, a let right-hand side or a block's final expression, optionally wrapped in attempt (U3013). It cannot be nested inside other expressions or arguments. This fixes evaluation order, gives every failure a handling site and makes every effect visible on its own line.
let registration = @registrations.find(key) -- allowed
if error fail Unavailable(reason: "registrations")
if none fail NotRegistered
show(@registrations.find(key)) -- U30135. Visibility and inference
- Declarations are private to their module unless marked
pub. - A
pubfunction MUST declare everyusesand itsfailsexplicitly (U3003, U3009). - A private function MAY omit
usesandfails. The compiler infers them as the least fixed point over the module's call graph.una contractprints the inferred header, and the build report marks it as inferred.- (v0.2, ADR 0062.) A private function without
usesclauses getsuses of pinferred for each parameterpof function type, without its ownusesorfails, that its body calls or passes on only where a call with effects may stand: as the whole expression of a statement, aletor a one-line body. The body mentionspin no other way, and not inside a lambda. A parameter used otherwise stays pure. - Without a
failsclause, the function also getsfails of pinferred when the body passes the failure of such a call ofpwithif error passand fails in no other way. That is, it raises no variant and passes or maps no other failure. - A
pubfunction writes these clauses (spec/05 §9 rule 9). - (ADR 0099.) The inferred
failsis the kind of the body's first failure in source order. A failure is a variant raised withfail(also afterchecked ... else,if errorandif none), or a failure passed on withif error pass, which has the kind of the call it handles. A failure of no known kind, such as the pass of a call that cannot fail, decides nothing. A pass of a function whosefailsis inferred too has that function's kind, so the result does not depend on the order of the declarations. Functions still undecided may each pass first the failure of another undecided function. Then each group of them that pass each other's failures, directly or not, and no failure of an undecided function outside the group, decides at once. Each member whose later failures, without its passes of the group's members, include one of a known kind takes the kind of the first of them; the other members then follow the rules above. If no member has one, no member of the group fails. - A body whose failures have two kinds is ill-typed (spec/10 §1). Each failure of a kind other than the inferred one is reported at its site: U3009 at the variant of a
fail, U3008 at anif error pass.
- (v0.2, ADR 0062.) A private function without
- Types of parameters and results are never inferred.
6. Lambdas
let adults = people.filter(keep: fn(p) -> adult(p.age))- A lambda is pure unless its expected type declares
usesorfails(spec/02 §2,fn_type_clause).- (v0.2, ADR 0062.) A lambda given for a parameter that the callee's
uses oforfails ofclause names may also use capabilities and fail, as its body requires. A pure lambda stays valid there.
- (v0.2, ADR 0062.) A lambda given for a parameter that the callee's
- A lambda that uses capabilities or can fail is second-class (spec/05 §6): it can be passed as an argument but not returned, stored in a kind or bound with
letto escape its scope. - Lambdas capture variables by value. They cannot capture capability references unless their type declares the corresponding
uses.
7. Recursion
Direct and mutual recursion are allowed. There is no tail-call guarantee in the reference interpreter; the interpreter reports stack exhaustion as runtime diagnostic U6003.
8. Entry point
A program's entry point is pub main() -> Unit in the module named by una run. It MAY declare uses over host capabilities (spec/14 §3) and a fails clause.
una rungrants only the capabilities listed in--grantflags or[run] grantsinuna.toml. Ausesclause onmainfor a capability not granted is U3012 before execution starts.- If
mainfails, the runtime prints the variant name to stderr and exits with code 1. Payload fields are printed only if their labels arepublic.