Home / Docs / Language guide / Errors

if error and if none

Release v0.4.0Edition 0.1 and laterU0101U0102U2001U2013U3007U3008U3009U3013U3025U4002

What it does

A statement whose expression can fail is followed by a handling clause, which says what the failure becomes at that line. There is no implicit propagation, so every failure is visible where it can occur. if none handles an Option (a value that is either Some of something or None) the same way, at the same place.

Learn more: Handling a failure: the clauses.

una
module shop

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

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
handled         = line_expr [ with_clause ] NEWLINE [ INDENT handling { handling } DEDENT ] ;
handling        = "if" "error" ( "fail" variant_expr | "pass" | "use" line_expr ) NEWLINE
                | "if" "none" ( "fail" variant_expr | "use" line_expr ) NEWLINE ;

The clauses and their meaning, where a fallible expression is one that can fail:

Clause Applies to Meaning
if error fail V(...) Any fallible expression Any failure becomes V. Inside the arguments, error names the original failure value.
if error pass Callee error kind equals the current function's Propagate the failure unchanged
if error use e Any fallible expression Recover with value e of the expression's type; error is in scope in e
if none fail V(...) Expression of type Option[T] None becomes failure V; the result has type T
if none use e Expression of type Option[T] None becomes e; the result has type T

A clause stands on its own line, one level below the statement it handles. A statement may be a let, a bare statement or a block's final expression.

Examples

if error pass propagates a failure of the same kind, and if error use recovers with a value:

una
module shop

pub kind OrderError = | TooMany

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

pub add_twice(units: Int) -> Int
  fails OrderError
=
  let once = add_units(units)
    if error pass
  add_units(once)
    if error pass

pub add_or_zero(units: Int) -> Int
=
  add_units(units)
    if error use 0

error names the original failure inside if error fail, so it can travel as a payload:

una
module shop

pub kind StockError = | OutOfStock

pub kind CheckoutError = Stock(cause: StockError) | Declined

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

pub checkout(units: Int) -> Int
  fails CheckoutError
=
  reserve(units)
    if error fail Stock(cause: error)

if none use gives a default for an Option, and an operation's failure can be recovered at the same line. Here if error use None turns a failure of get into None, and if none use "" then turns any None, from a failure or from a missing key, into the empty text:

una
module shop

pub kind StoreError = | Timeout

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

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

Inside if error use, error names the failure too, so the recovered value can come from it:

una
module shop

pub kind StockError = | OutOfStock(left: Int)

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

left_of(failure: StockError) -> Int
=
  when failure
    is OutOfStock(left) -> left

pub reserve_what_is_left(units: Int) -> Int
=
  reserve(units)
    if error use left_of(error)

A fallible call without a clause is rejected:

una
-- fails with U3007
module shop

pub kind OrderError = | TooMany

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

pub add_twice(units: Int) -> Int
  fails OrderError
=
  let once = add_units(units)
  add_units(once)
    if error pass

Edge cases

if error pass needs equal error kinds. A function has one error kind, so a failure of another kind is converted with if error fail:

una
-- fails with U3008
module shop

pub kind StockError = | OutOfStock

pub kind CheckoutError = | Declined

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

pub checkout(units: Int) -> Int
  fails CheckoutError
=
  reserve(units)
    if error pass

Order and repetition. Each clause appears at most once, and if error comes before if none:

una
-- fails with U0102
module shop

pub kind StoreError = | Timeout

pub kind LookupError = | Missing

price_of(sku: Int) -> Option[Int] = if sku > 999 then fail Timeout else Some(sku)

pub price(sku: Int) -> Int
  fails LookupError
=
  let found = price_of(sku)
    if none fail Missing
    if error fail Missing
  found

A clause on its own line. A clause written on the statement's line is a syntax error:

una
-- fails with U0101
module shop

pub kind StockError = | OutOfStock

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

pub checkout(units: Int) -> Int
  fails StockError
=
  reserve(units) if error pass

if none needs an Option:

una
-- fails with U2001
module shop

pub kind LookupError = | Missing

pub price(cents: Int) -> Int
  fails LookupError
=
  let found = cents
    if none fail Missing
  found

The recovered value has the expression's type:

una
-- fails with U2001
module shop

pub kind StockError = | OutOfStock

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

pub reserved(units: Int) -> Int
=
  reserve(units)
    if error use "none"

error only inside a clause. error is valid only in the fail or use part of an if error clause:

una
-- fails with U2013
module shop

pub kind StockError = | OutOfStock

pub reserve(units: Int) -> Int
  fails StockError
=
  if units > 10 then fail OutOfStock else error

Further rules:

Diagnostics

Edition

The handling clauses are the same in editions 0.1 and 0.2. Edition 0.3 adds U3025 for an if error clause on an expression that cannot fail.

Normative source