Home / Docs / Language guide / Errors

attempt

Release v0.4.0Edition 0.1 and laterU2001U3007U3013U3026U4002

What it does

attempt f(args) evaluates one fallible call (a call that can fail) and returns a Result[T, E] instead of failing: Ok(value) on a normal return, Err(failure) on a failure. The caller then branches on the outcome. attempt is the call's handling site, so the call needs no if error clause (U3007).

Learn more: Failures as values: attempt and Result.

una
module shop

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

Forms

In the grammar below, each rule gives a name, =, what the name stands for and ;, quoted words are written as shown, NEWLINE, INDENT and DEDENT stand for a line break and for one more or one less level of indentation, [ ] marks an optional part, { } a part that may repeat, | separates alternatives, ( ) groups them, and (* *) holds a comment.

ebnf
attempt_expr    = "attempt" postfix ;

The operand is one call of a function or of a capability operation. attempt stands as the whole expression of a statement, a let or a final expression, as any fallible call does.

Examples

After let x = attempt f(...), the arm (one is line of a when) is Ok(value) knows what a normal return of f guarantees, its ensures included; the arm is Err knows nothing more. Here the verifier (the part of una check that proves facts about the code) proves result >= units from add_units's ensures:

una
module shop

pub kind OrderError = | TooMany

pub add_units(units: Int) -> Int
  ensures result > units
  fails OrderError
=
  if units > 100 then fail TooMany else units + 1

pub add_or_keep(units: Int) -> Int
  ensures result >= units
=
  let outcome = attempt add_units(units)
  when outcome
    is Ok(value) -> value
    is Err -> units

The Result is a value like any other, so a function may return it to its caller:

una
module shop

pub kind StockError = | OutOfStock

reserve(units: Int) -> Int = if units > 10 then fail OutOfStock else units

pub try_reserve(units: Int) -> Result[Int, StockError] = attempt reserve(units)

The operand must be a call:

una
-- fails with U2001
module shop

pub try_reserve(units: Int) -> Result[Int, Int] = attempt units

Edge cases

One effect per line. attempt does not let a fallible call sit inside a larger expression. Bind the Result with let first:

una
-- fails with U3013
module shop

pub kind StockError = | OutOfStock

reserve(units: Int) -> Int = if units > 10 then fail OutOfStock else units

pub can_reserve(units: Int) -> Bool = (attempt reserve(units)).is_ok()

Further rules:

Diagnostics

Edition

attempt is the same in editions 0.1 and 0.2. Edition 0.3 adds U3026 for attempt of a call that cannot fail.

Normative source