Home / Learn / 12 Capabilities
Release v0.4.0Edition 0.2
12.7 Common mistakes
Page 8 of 10
Most of the mistakes below are a small change to day-to-day/src/notices.una. The others change a step of this chapter, as each one says. The capability diagnostics are U3 codes, reported before any proof is tried. Each names the binding or the handler and what is missing, and marks the place in the code where it is needed.
12.7.1 Forgetting to hand over a binding (U3001)
Leave @log = @console out of the first with in main:
--- a/src/notices.una
+++ b/src/notices.una
@@ -105,3 +105,3 @@
let morning = [Shipment(order: "A-1001", customer: "C-17", carrier: "Parcelo"), Shipment(order: "A-1002", customer: "C-20", carrier: "Parcelo"), Shipment(order: "A-1003", customer: "C-99", carrier: "Parcelo"), Shipment(order: "A-1004", customer: "C-21", carrier: "Parcelo")]
- dispatch(morning) with @customers = directory(customers), @mailer = outbox(), @log = @console
+ dispatch(morning) with @customers = directory(customers), @mailer = outbox()
let late = [Shipment(order: "A-1005", customer: "C-17", carrier: "Rapida")]
[U3001] Error: `dispatch` needs `@log: Console[print]`, which is not in scope here
Why: the console is right there in main, so it seems dispatch should find it. But dispatch needs @log, and main holds only @console. Bindings are found by name, never by type. The message names the callee, the binding with its capability, and "not in scope here"; the mark is on the call.
Fix: add @log = @console to the with. The repair una offers, a uses @log line on main, would widen main's header instead, so una fix skips it, and una fix --dry-run . says so (For agents). See U3001.
In the step of Narrowing: a greeting that may only look up, give erase the header of greeting, uses @customers: Customers[find]:
--- a/src/accounts.una
+++ b/src/accounts.una
@@ -21,3 +21,3 @@
erase(id: Text) -> Unit
- uses @customers: Customers[forget]
+ uses @customers: Customers[find]
uses @audit: Console[print]
[U3002] Error: `@customers` permits `find`, not `forget`
Why: the header was copied from a similar function. The brackets list every operation the function may perform, and the mark is on the operation the header does not list, forget. The repair una offers widens the header, so it is yours to judge.
Fix: write Customers[forget]. Add an operation to a header only when it belongs to the function's job: every caller must then hold it too. See U3002.
12.7.3 An effect in a pure pub function (U3004)
Add a log line to notice:
--- a/src/notices.una
+++ b/src/notices.una
@@ -32,3 +32,6 @@
--- The text of a shipping notice. Pure: it has no `uses`, so it cannot reach any service.
-pub notice(customer: Customer, shipment: Shipment) -> Text = "Hello {customer.name}, your order {shipment.order} is on its way with {shipment.carrier}."
+pub notice(customer: Customer, shipment: Shipment) -> Text
+=
+ @log.print("writing the notice for {shipment.order}")
+ "Hello {customer.name}, your order {shipment.order} is on its way with {shipment.carrier}."
[U3004] Error: `@log` is used here, but this code declares no `uses`, so it is pure
Why: a log line is a habit when something needs watching. But a pub function declares every uses, so one without uses is pure, and the mark is on the binding it tries to use, @log.
Fix: log in the caller, which already holds @log. A message text should stay a pure function, which an example can call with values alone. See U3004.
12.7.4 Installing a handler of another capability (U3010)
Write @mailer = directory_down():
--- a/src/notices.una
+++ b/src/notices.una
@@ -107,3 +107,3 @@
let late = [Shipment(order: "A-1005", customer: "C-17", carrier: "Rapida")]
- dispatch(late) with @customers = directory(customers), @mailer = mail_down(), @log = @console
+ dispatch(late) with @customers = directory(customers), @mailer = directory_down(), @log = @console
[U3010] Error: this handler implements `Customers`, and `dispatch` needs `@mailer` to be `Mailer`
Why: both handlers stand for a service that never answers, and their names are close. The message says which capability the handler implements, Customers, and which one the callee needs at that name, Mailer; the mark is on the handler's call.
Fix: install mail_down(), the handler of Mailer that never answers. See U3010.
12.7.5 Using a host capability that is not granted (U3012)
In the step of An end-of-day stock export, remove "clock" from [run] grants:
--- a/una.toml
+++ b/una.toml
@@ -7,2 +7,2 @@
entry = "export"
-grants = ["console", "clock", "files:src:write"]
+grants = ["console", "files:src:write"]
[U3012] Error: `main` uses `now` of `Clock`, which `[run] grants` does not grant
│ Help: repair 1 (widens grant: the program then gets this host authority when it runs): grant `now` of `Clock` in `[run] grants` of `una.toml`, or with `--grant`
Why: grants are easy to forget when a uses line is added to main. The mark is on the uses line that is not granted, and the help line widens the grant, which is for the people who maintain the package to decide.
Fix: grant "clock" if the program needs the time. Otherwise remove the uses line and the call. See U3012.
12.7.6 Adding an operation that the handlers lack (U3011)
Give Mailer a second operation, delivered, which asks whether a message arrived, and leave the handlers as they are:
--- a/src/notices.una
+++ b/src/notices.una
@@ -28,4 +28,6 @@
pub capability Mailer
op send(to: Text, subject: Text, body: Text) -> Unit
+ fails ServiceError
+ op delivered(to: Text) -> Bool
fails ServiceError
[U3011] Error: handler `outbox` does not implement the operation `delivered` of `Mailer`
[U3011] Error: handler `mail_down` does not implement the operation `delivered` of `Mailer`
Why: the capability is the description of the service, and every handler must do the whole job. A new operation therefore breaks every handler of the capability at once: here outbox and mail_down, one diagnostic each, with the mark on the handler's name.
Fix: give each handler an op delivered(to) = … line, such as true for outbox and fail Timeout for mail_down. Or leave the operation out until the service has it. See U3011.
Next:12.8 Exercises