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:
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
Optionfor 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:
- 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. - A failure is a value of a sum kind. You declare it like any other kind, and its variants can carry data.
- A header says what a function can fail with.
fails OrderErroris part of the header, next torequiresanduses. A public function that does not sayfailscannot fail, and the checker holds it to that. - 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.
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.