Home / Docs / Language guide / Errors
if error and if none
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.
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
registrationForms
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.
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:
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 0error names the original failure inside if error fail, so it can travel as a payload:
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:
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 ""
foundInside if error use, error names the failure too, so the recovered value can come from it:
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:
-- 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 passEdge 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:
-- 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 passOrder and repetition. Each clause appears at most once, and if error comes before if none:
-- 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
foundA clause on its own line. A clause written on the statement's line is a syntax error:
-- 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 passif none needs an Option:
-- fails with U2001
module shop
pub kind LookupError = | Missing
pub price(cents: Int) -> Int
fails LookupError
=
let found = cents
if none fail Missing
foundThe recovered value has the expression's type:
-- 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:
-- fails with U2013
module shop
pub kind StockError = | OutOfStock
pub reserve(units: Int) -> Int
fails StockError
=
if units > 10 then fail OutOfStock else errorFurther rules:
- One effect per line. A fallible call is the whole expression of its statement,
letor final expression, so that its clause has one site (U3013). Bind its result withletfirst. - The
failof a clause obeys the rules offail: its variant belongs to the function's error kind (U3009), and it is allowed only when the Branches and failures: implicit flows, the label of the conditions that decided whether this line runs, ispublic(U4002). - Labeled failures. A failure decided by labeled data (data marked with a label above
public, such asinternalorsecret), such as anHttprequest's, carries that label.if error usethen runs under it, andif error passandif error failare U4002 when it is abovepublic. - An
if errorclause on a statement that cannot fail. In edition0.3, anif errorclause after a statement that cannot fail, such aslet x = n + 1, is U3025, anduna fixdeletes it. Onlyif erroris judged: on anOptionthat cannot fail, such aslet first = codes.first(), anif noneclause stays. Editions0.1and0.2accept theif errorclause. - Alternative.
attempthandles a failure by turning it into aResultvalue instead. Seeattempt.
Diagnostics
- U0101: a clause on the statement's own line.
- U0102: a repeated clause, or
if errorafterif none. - U2001:
if noneon a value that is not anOption, or a recovered value of the wrong type. - U2013:
erroroutside a handling clause. - U3007: a fallible statement without a clause.
- U3008:
if error passacross error kinds. - U3009: the variant of
if error failorif none failoutside the function's error kind. - U3013: a fallible call nested inside another expression.
- U3025: in edition
0.3, anif errorclause on an expression that cannot fail. - U4002: the
failof a clause under a program counter abovepublic, orif error passorif error failon a failure labeled abovepublic.
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
- spec/06 §3: handling clauses, their order, and, in edition
0.3, a clause on a statement that cannot fail; spec/06 §1: one error kind per function; spec/06 §2: the variant of afail; spec/06 §5:attempt. - spec/02 §6: the grammar of
handledandhandling; spec/02 §8: whereerrormay appear. - spec/04 §4: one effect per line.
- spec/07 §3 rule 3: failures under the program counter; spec/07 §7 rule 4: labeled failures of operations.
- Decision record: ADR 0100, for U3025.