Home / Learn

Release v0.4.0

7 Results and failures

Page 1 of 12

Real programs spend much of their code on what goes wrong: a text that is not a number, a product the store does not sell, more units wanted than are on the shelf. This chapter shows how Una says so. A value that may be missing has a type of its own, Option. A function that can fail says so in its header, with a kind you declare for its failures, and every call of it is followed by a line that says what to do when it fails. You learn to write those lines, to keep a failure as a value, and to check data from outside the program once, where it enters.

What you'll build

An order intake for a small store. It reads order lines such as LAMP-01, 2, checks each one against the store's stock list, and reports every line, accepted or rejected, with a reason a person can act on:

Output
ok      2 x LAMP-01
reject  3 of DESK-02 wanted, 1 left
reject  no product has the SKU CHAIR-09
reject  the shelf of RUG-07 is being counted; retry later
reject  the quantity in 'LAMP-01, two' is not a whole number above 0
reject  cannot read the line 'LAMP-01'

You will learn to:

  • use an Option for a value that may be missing, and take it apart;
  • declare a kind of failures whose variants carry what someone needs to fix the problem;
  • choose among the five handling clauses, and translate a failure from one layer to the next;
  • keep a failure as a value with attempt, so that one bad line still gets its own report;
  • test data from outside the program once, with a guard or with checked.

Download this chapter's packages: each step is a package under steps/, and the chapter's program is day-to-day/; run una check . and una run . in one.

Why it works this way

In many languages a function can fail in ways its header does not show: an exception thrown three calls deep, or a special "no value" returned on a path nobody tested. A reader has to read the bodies to find out what can go wrong, and a reviewer cannot tell from a change whether it added a new way to fail.

Una puts all of that in view. Four rules do it:

  1. A missing value has its own type. A search that may find nothing gives an Option, and the checker refuses to use it as if the value were there.
  2. A failure is a value of a sum kind. You declare it like any other kind, and its variants can carry data.
  3. A header says what a function can fail with. fails OrderError is part of the header, next to requires and uses. A public function that does not say fails cannot fail, and the checker holds it to that.
  4. Every call that can fail is handled where it is made. The next line, indented, says what happens: carry on with a value, pass the failure on, or turn it into a failure of your own kind. Nothing passes a failure on unless that line says so.

The price is a few extra lines at each call. In return, a function's failures can be read from its header, and none goes unhandled.

Key idea

Nothing in Una fails at run time without the code saying so, apart from a few stops outside the program's logic, such as running out of call depth or memory (U6003); Reference lists them all. Division by zero and a broken precondition are ruled out by proof (chapter 5), and there are no exceptions to catch.

View the Markdown

Next:7.1 A value that may be missing: Option