Home / Learn / 7 Results and failures

Release v0.4.0Edition 0.2

7.9 Common mistakes

Page 10 of 12

Each mistake is a small change to day-to-day/src/orders.una, followed by what una check . reports.

7.9.1 Forgetting the clause (U3007)

Remove if error pass under let order = parse_order(line):

src/orders.unadiff
--- a/src/orders.una
+++ b/src/orders.una
@@ -58,3 +58,2 @@
   let order = parse_order(line)
-    if error pass
   check_stock(order)
Diagnostic
[U3007] Error: `parse_order` can fail with `OrderError`; handle the failure with an `if error` clause, or wrap the call in `attempt`
    ╭─[ src/orders.una:58:15 ]
    │
 58 │   let order = parse_order(line)
    │               ────────┬────────
    │                       ╰────────── `parse_order` can fail with `OrderError`; handle the failure with an `if error` clause, or wrap the call in `attempt`
    │
    │ Note: run `una explain U3007` for an explanation
────╯

Why: in languages with exceptions, a failure travels up by itself, so leaving the call bare feels natural. In Una nothing passes a failure on by itself. The message names the call, parse_order, and the kind it fails with, OrderError, and the mark covers the call. Its last part lists the two ways to handle it.

Fix: add the clause that matches your intent, as How to write the clauses lists them; here if error pass. See U3007.

7.9.2 Passing a failure of another kind (U3008)

In check_stock, write if error pass instead of if error fail Unavailable(sku: order.sku):

src/orders.unadiff
--- a/src/orders.una
+++ b/src/orders.una
@@ -46,3 +46,3 @@
   let left = on_hand(order.sku)
-    if error fail Unavailable(sku: order.sku)
+    if error pass
     if none fail UnknownSku(sku: order.sku)
Diagnostic
[U3008] Error: `if error pass` passes a `StockError` failure, and this code fails with `OrderError`; use `if error fail` with a variant of `OrderError`

Why: pass looks like the simplest clause, but it hands the failure on unchanged, and a function has one error kind: StockError is not OrderError. The message names both kinds, the one the call fails with and the one this code fails with, and says what to write instead.

Fix: translate with if error fail Unavailable(sku: order.sku). To keep the original, add a variant with a field of type StockError, such as StockFailed(cause: StockError), and write if error fail StockFailed(cause: error). See U3008.

7.9.3 Failing with a variant of another kind (U3009)

Write if error fail BeingCounted(sku: order.sku) in check_stock:

src/orders.unadiff
--- a/src/orders.una
+++ b/src/orders.una
@@ -46,3 +46,3 @@
   let left = on_hand(order.sku)
-    if error fail Unavailable(sku: order.sku)
+    if error fail BeingCounted(sku: order.sku)
     if none fail UnknownSku(sku: order.sku)
Diagnostic
[U3009] Error: `BeingCounted` is a variant of `StockError`, and this code fails with `OrderError`

Why: BeingCounted is the name of what went wrong, so it is tempting to reuse it. But fail names a variant of the function's own error kind, and BeingCounted belongs to StockError. The message names the variant, its kind, and the kind this code fails with.

Fix: name a variant of your own kind, Unavailable. See U3009.

7.9.4 A public function that fails without saying so (U3009)

Remove fails OrderError from parse_order:

src/orders.unadiff
--- a/src/orders.una
+++ b/src/orders.una
@@ -29,3 +29,2 @@
 pub parse_order(line: Text) -> Order
-  fails OrderError
 =
Diagnostic
[U3009] Error: this code declares no error kind, so it cannot fail with `Malformed`; declare `fails` in its header
    │ Help: repair 1: declare `fails OrderError` in the header; edit src/orders.una:29:37..29:37 to "\n  fails OrderError"

una check reports this once for every way the body fails, three times here.

Why: a private function may leave out fails, so it is easy to forget that a pub one may not: a pub header is what other modules rely on. The message is reported at each place the body fails, and the help line gives the exact edit, the line to add and where.

Fix: una fix . applies the repair shown. See U3009.

7.9.5 Nesting a call that can fail (U3013)

Write check_stock(parse_order(line)):

src/orders.unadiff
--- a/src/orders.una
+++ b/src/orders.una
@@ -57,5 +57,3 @@
 =
-  let order = parse_order(line)
-    if error pass
-  check_stock(order)
+  check_stock(parse_order(line))
     if error pass
Diagnostic
[U3013] Error: `parse_order` has effects or can fail, so it must be the whole expression of a statement or `let`; bind its result with `let` first

Why: nesting calls is how many languages chain steps. In Una a call that can fail is the whole expression of its statement, so that each failure has its own handling line and the order of the work stays visible. The message names the inner call, parse_order, and says what to do: give its result a name with let first.

Fix: let order = parse_order(line) with its clause, then check_stock(order) with its own. A do line of an example is the one place where calls that can fail may nest. See U3013.

7.9.6 The clause on the same line (U0101)

Write let order = parse_order(line) if error pass:

src/orders.unadiff
--- a/src/orders.una
+++ b/src/orders.una
@@ -57,4 +57,3 @@
 =
-  let order = parse_order(line)
-    if error pass
+  let order = parse_order(line) if error pass
   check_stock(order)
Diagnostic
[U0101] Error: a handling clause goes on its own line, indented under the expression it handles
    │ Help: repair 1: move the clause to its own line; edit src/orders.una:58:32..58:46 to "\n    if error pass"

Why: the clause reads like part of the sentence, so it is natural to write it on the same line. But a clause is a line of its own, so that every handling decision starts a line a reviewer can scan. The help line gives the exact edit: the clause moves to the next line, indented.

Fix: una fix . moves it. See U0101.

7.9.7 if none before if error (U0102)

Swap the two clauses under on_hand(order.sku) in check_stock:

src/orders.unadiff
--- a/src/orders.una
+++ b/src/orders.una
@@ -46,4 +46,4 @@
   let left = on_hand(order.sku)
+    if none fail UnknownSku(sku: order.sku)
     if error fail Unavailable(sku: order.sku)
-    if none fail UnknownSku(sku: order.sku)
   if order.quantity > left
Diagnostic
[U0102] Error: `if error` clause after `if none`; handling clauses go in the order if error, if none

Why: both clauses handle one call, so their order can look free. It is fixed: the if error clause handles the call, and if none handles the value it gave, so the call's failure comes first. The message names the clause out of place and the order to use.

Fix: put if error first. See U0102.

7.9.8 Re-raising a stored failure (U0101)

In report, after attempt, write is Err(failure) -> fail failure:

src/orders.unadiff
--- a/src/orders.una
+++ b/src/orders.una
@@ -78,3 +78,3 @@
     is Ok(order) -> "ok      {order.quantity} x {order.sku}"
-    is Err(failure) -> "reject  {reason(failure)}"
+    is Err(failure) -> fail failure
 
Diagnostic
[U0101] Error: unexpected `failure`, expected a variant
    │ Help: repair 1: `fail` takes a variant of the error kind, as in `fail Broke`, not a stored value; fail where the error is found, or pass a call's failure on with `if error pass`

Why: after attempt, the failure is in a name, and handing it on with fail looks natural. But fail takes a variant of the error kind, at the place the failure is decided, not a stored value: the parser expected a variant name where failure stands. The help line explains both ways out.

Fix: if you only want to pass the failure on, do not attempt; use if error pass. Here report must not fail at all, so its Err arm gives back the reason, as before. See U0101.

Next:7.10 Exercises