Home / Docs / Language guide / Errors

fails

Release v0.4.0Edition 0.1 and laterU0101U0102U2002U3007U3008U3009U3017U3018U3019

What it does

fails E is the header clause (a line between a function's signature and its body) that declares a function's error kind: the one sum kind (a kind whose values are each one of several named variants) whose variants the function may fail with. A function without fails cannot fail. Callers see the clause in the header, and must handle every failure at the line of the call.

Learn more: Declaring a failure: fails and fail.

una
module shop

pub kind OrderError = | TooMany

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

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
clause          = "requires" line_expr NEWLINE
                | "ensures" line_expr NEWLINE
                | "uses" cap_ref ":" cap_type NEWLINE
                | "uses" "of" lower_ident NEWLINE                   (* edition 0.2 *)
                | "fails" upper_ident NEWLINE
                | "fails" "of" lower_ident NEWLINE                  (* edition 0.2 *)
                | "derived" "from" upper_ident { "," upper_ident } NEWLINE ;

Edition 0.2 adds fails of p and uses of p. of is not a keyword: it is read as part of the clause only right after fails or uses.

Clauses of a header come in a fixed order: every requires, every ensures, every uses, then at most one fails E and one fails of p, then derived from.

Examples

An error kind with payloads, and a function that fails with each variant:

una
module shop

pub kind QuantityError = TooMany(limit: Int) | Negative

pub quantity(units: Int) -> Int
  fails QuantityError
=
  if units > 100 then fail TooMany(limit: 100) else if units < 0 then fail Negative else units

A private function's error kind is inferred, and a pub caller passes it on with if error pass, since the kinds are equal:

una
module shop

pub kind OrderError = | TooMany

check_units(units: Int) -> Int = if units > 100 then fail TooMany else units

pub order_units(units: Int) -> Int
  fails OrderError
=
  check_units(units)
    if error pass

In edition 0.2, fails of p lets a higher-order function (one that takes another function as a parameter) fail as the function it is given:

una
module shop

pub apply_discount(cents: Int, discount: fn(Int) -> Int) -> Int
  fails of discount
=
  discount(cents)
    if error pass

A pub function that fails without a fails clause is rejected:

una
-- fails with U3009
module shop

pub kind OrderError = | TooMany

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

An error kind is a sum kind, never a record:

una
-- fails with U2002
module shop

pub kind Address
  street: Text

pub ship(units: Int) -> Int
  fails Address
=
  units

Edge cases

One error kind per function. A second fails clause is U0102:

una
-- fails with U0102
module shop

pub kind OrderError = | TooMany

pub kind PaymentError = | Declined

pub checkout(units: Int) -> Int
  fails OrderError
  fails PaymentError
=
  units

One kind for an inferred function too. A private function without fails still has one error kind: failing with variants of two kinds is U3009:

una
-- fails with U3009
module shop

pub kind OrderError = | TooMany

pub kind PaymentError = | Declined

charge(units: Int) -> Int = if units > 100 then fail TooMany else if units < 0 then fail Declined else units

Declared, never raised. A function may declare fails E and never fail. Its callers still handle the failure, since they read the header:

una
-- fails with U3007
module shop

pub kind OrderError = | TooMany

pub reserve(units: Int) -> Int
  fails OrderError
=
  units

pub checkout(units: Int) -> Int
  fails OrderError
=
  reserve(units)

Further rules:

Diagnostics

Edition

fails E is in editions 0.1 and 0.2. fails of p is in edition 0.2 and later; in edition 0.1 the clause takes an error kind, so fails of is a syntax error (U0101):

una
-- edition 0.1
-- fails with U0101
module shop

pub apply_discount(cents: Int, discount: fn(Int) -> Int) -> Int
  fails of discount
=
  discount(cents)
    if error pass

Normative source