Home / Docs / Language guide

Errors

Release v0.4.0

Errors are values. There are no exceptions, no panics and no implicit propagation.

6.1 Error kinds and fails

Any sum kind can serve as an error kind. A function declares at most one, with fails E.

una
module demo

pub kind CheckInError = NotRegistered | Unavailable

pub kind StoreError = Timeout | Corrupted(detail: Text)

6.2 fail

fail V or fail V(field: value) ends the function with a failure. V must be a variant of the function's error kind (U3009).

una
module demo

pub kind Seats = Int in 0..5000

pub kind Event
  name: Text
  remaining: Seats

pub kind BookingError = | InvalidCount

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

pub book(e: Event, count: Int) -> Seats
  fails BookingError
=
  if count < 1 or count > e.remaining
    fail InvalidCount
  else
    seats_after(e, count)

In the else branch the verifier knows count >= 1 and count <= e.remaining, so the preconditions of seats_after are proven. The second argument uses punning (§4.4).

6.3 Handling clauses

A statement whose expression can fail must be followed by an indented if error clause (U3007), unless it is wrapped in attempt. Each clause stands on its own line, one level below the statement: fetch(id) if error pass on one line is U0101.

Clause Applies to Meaning
if error fail V(...) any fallible expression any failure becomes V; inside the arguments, error is the original failure
if error pass callee error kind equals the current function's propagate the failure unchanged (U3008 if the kinds differ)
if error use e any fallible expression recover with value e; error is in scope
if none fail V(...) an expression of type Option[T] None becomes failure V; the result has type T
if none use e an expression of type Option[T] None becomes e; the result has type T
una
module demo

pub kind Registration
  name: Text

pub kind StoreError = Timeout | Corrupted(detail: Text)

pub kind CheckInError = NotRegistered | Unavailable

pub capability Registrations
  op find(key: Text) -> Option[Registration]
    fails StoreError

pub capability Store
  op read(path: Text) -> Text
    fails StoreError

pub capability Cache
  op get(key: Text) -> Option[Text]
    fails StoreError

pub lookup(key: Text) -> Registration
  uses @registrations: Registrations[find]
  fails CheckInError
=
  let registration = @registrations.find(key)
    if error fail Unavailable
    if none fail NotRegistered
  registration

pub load(path: Text) -> Text
  uses @store: Store[read]
  fails StoreError
=
  let detail = @store.read(path)
    if error fail Corrupted(detail: "read failed")
  detail

pub cached(key: Text) -> Option[Text]
  uses @cache: Cache[get]
=
  let found = @cache.get(key)
    if error use None
  found

6.4 attempt

attempt turns a single fallible call into a Result, so you can branch on the outcome instead of failing:

una
module demo

pub kind Registration
  name: Text

pub kind StoreError = | Timeout

pub capability Registrations
  op find(key: Text) -> Option[Registration]
    fails StoreError

pub registered(key: Text) -> Bool
  uses @registrations: Registrations[find]
=
  let outcome = attempt @registrations.find(key)
  when outcome
    is Ok(value) -> value.is_some()
    is Err(failure) -> false

The operand must be one call (U2001), and attempt counts as its handling site.

6.5 checked (escape hatch)

checked(v, p) else fail V tests predicate p at runtime, with it bound to v. The package must allow it in its escape budget:

una.tomltoml
[package]
name = "phones"
version = "0.1.0"
edition = "0.2"

[escape_budget]
checked_per_module = 1
src/phones.unauna
module phones

pub kind Phone = Text where valid_phone(it)

pub kind PhoneError = | Malformed

pub predicate opaque valid_phone(t: Text) -> Bool = t.len == 11 and is_digits(t)

pub parse_phone(raw: Text) -> Phone
  fails PhoneError
=
  checked(raw, valid_phone(it)) else fail Malformed

6.6 What is not a failure


Constructs