Home / Docs / Language guide

Functions and contracts

Release v0.4.0

4.1 Two forms

una
module demo

requirement EVENTS_3
  text "An event with no remaining seats is always shown as sold out"
  source policy "Box Office Handbook 2.1"
  owner box_office
  status active

pub kind Seats = Int in 0..5000

pub kind Availability = SoldOut | Few | Open

pub kind Event
  name: Text
  remaining: Seats

--- Short form.
double(x: Int) -> Int = x * 2

--- Long form.
pub availability(e: Event) -> Availability
  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 -> Open

una fmt converts between them: a long form with no clauses and a one-line body becomes the short form.

4.2 Clauses

Clause Meaning Checked how
requires p precondition over parameters proven at every call site; assumed inside the body
ensures q postcondition over parameters, result and old(x) proven on every normal return path; assumed by callers
uses @c: C[ops] may perform ops through capability @c effects of the body must fit (U3003)
uses of p may perform the effects of the function argument p (edition 0.2) U3017 to U3019 for a malformed clause
fails E may fail with variants of sum kind E failures of the body must be variants of E (U3009)
fails of p may fail as the function argument p does (edition 0.2) as uses of p
derived from R1, R2 traceability to requirements each requirement must exist (U1006)

Rules:

una
module demo

pub kind Seats = Int in 0..5000

pub kind Event
  name: Text
  remaining: Seats

pub seats_after(e: Event, count: Int) -> Seats
  requires count >= 1
  requires count <= e.remaining
  ensures result == e.remaining - count
=
  e.remaining - count

The compiler proves that e.remaining - count fits Seats (between 0 and 5000) using both requires clauses, and proves the ensures clause. Every caller must prove both requires clauses at the call site.

Effect polymorphism (edition 0.2, ADR 0062). uses of p and fails of p name a parameter p of function type, written without its own uses or fails. At each call, the callee's effects and failures are its own plus those of the argument passed for p. Inside the body, p is only called, or passed on to a parameter that the callee's of clause names. A callee with its own fails E accepts for p only an argument that fails with E, so each function keeps one error kind.

una
module demo

pub kind ParseError = | NotANumber

--- `each` may have effects and may fail; `apply_all` has them too, at each call.
pub apply_all(xs: List[Text], each: fn(Text) -> Int) -> List[Int]
  uses of each
  fails of each
=
  xs.map(each: each)
    if error pass

pub parse(t: Text) -> Int
  fails ParseError
=
  t.to_int()
    if none fail NotANumber

pub parse_all(xs: List[Text]) -> List[Int]
  fails ParseError
=
  apply_all(xs, each: parse)
    if error pass

pub shout(names: List[Text]) -> Unit
  uses @console: Console[print]
=
  let printed = names.map(each: fn(n) -> @console.print(n))
  unit

4.3 Visibility and inference

4.4 Calls and labeled arguments

Rule Example
One argument: the label is optional double(4)
Two or more: the first may be unlabeled, the rest must be labeled (U2004) seats_after(event, count: 2)
Punning: from the second argument on, a bare identifier equal to the parameter name counts as labeled; the first argument always binds the first parameter (ADR 0049) record(key, status)
Argument count: too many arguments, or a parameter that receives none, is U2001. The count is checked before the labels. f(1, b: 2, b: 3) for a two-parameter f: U2001 "f takes 2 arguments, but 3 are given", and no U2006
Unknown label: U2005 f(1, c: 2)
Duplicate argument, with the right count: U2006 f(a: 1, a: 2)
Arguments are evaluated left to right

Constructors follow related rules:

una
module demo

pub kind Registration
  name: Text
  seat: Int

pub kind Lookup = Found(registration: Registration) | Missing

pub kind Event
  name: Text
  remaining: Int

pub sample(r: Registration) -> Lookup
=
  let e = Event(name: "Meetup", remaining: 120)
  let found = Found(registration: r)
  let maybe = Some(r)
  found

4.5 Method-call syntax

una
module demo

pub kind Event
  name: Text
  remaining: Int

pub open_names(schedule: List[Event]) -> Int
=
  let open_events = schedule.filter(keep: fn(e) -> e.remaining > 0)
  let names = open_events.map(each: fn(e) -> e.name)
  names.len

4.6 Lambdas and function types

una
module demo

pub increments(xs: List[Int]) -> List[Int] = xs.map(each: fn(x) -> x + 1)

pub next() -> fn(Int) -> Int = fn(x: Int) -> x + 1

4.7 Recursion and the entry point


Constructs