Home / Learn / 12 Capabilities

Release v0.4.0Edition 0.2

12.8 Exercises

Page 9 of 10

The exercises come with the chapter's download, 12-capabilities.tar.gz. Each one starts from exercises/N/start: the day-to-day package with the exercise's examples added, and a stub of what to write when there is one. una test . fails there until the exercise is done. Run una fmt . before una check ., so the layout is canonical.

12.8.1 Exercise 1: a directory of one customer

Small examples often need a directory with exactly one customer. Write a handler only(customer: Customer) for Customers whose find gives that customer for their id and None for any other. The start package ends with these examples, and una check . reports U1001 until the handler exists:

exercises/1/start/src/notices.unauna
example "a directory of one customer finds that customer"
  given @customers = only(Customer(id: "C-17", name: "Rosa", email: "rosa@example.invalid", wants_notices: true))
  given @mailer = outbox()
  do notify(Shipment(order: "A-1001", customer: "C-17", carrier: "Parcelo"))
  expect result == "rosa@example.invalid"

example "a directory of one customer knows no one else"
  given @customers = only(Customer(id: "C-17", name: "Rosa", email: "rosa@example.invalid", wants_notices: true))
  given @mailer = outbox()
  do notify(Shipment(order: "A-1002", customer: "C-20", carrier: "Parcelo"))
  expect fails UnknownCustomer

Hint: start from directory, which has the same shape. Write handler only(customer: Customer) for Customers, then one line op find(id) = …: the operation takes the parameter names only, and its body can read the handler's parameter customer. find returns an Option[Customer], so the body gives Some(customer) when id == customer.id and None otherwise, with an if … then … else … on one line.

Check your answer with una test ..

Answer (check, run, test; exercises/1/answer).

Add the handler next to the others:

src/notices.unadiff
--- a/src/notices.una
+++ b/src/notices.una
@@ -88,2 +88,6 @@
 
+--- A directory that holds one customer, for small tests.
+handler only(customer: Customer) for Customers
+  op find(id) = if id == customer.id then Some(customer) else None
+
 --- A directory that never answers.

una test . reports 9 examples passing.

12.8.2 Exercise 2: archive every notice

The store keeps a copy of every notice it sends in an archive mailbox, archive@example.invalid, through a second mail service. A notice counts as sent only once its copy is archived. The start package has notify_and_archive, which holds a second binding of Mailer, @archive, and does not use it yet:

exercises/2/start/src/notices.unauna
--- Sends the notice, then a copy of it to the store's archive mailbox. A notice counts as sent
--- only once its copy is archived. Exercise 2: send the copy.
pub notify_and_archive(shipment: Shipment) -> Text
  uses @customers: Customers[find]
  uses @mailer: Mailer[send]
  uses @archive: Mailer[send]
  fails NoticeError
=
  notify(shipment)
    if error pass

and two examples: a notice that is sent and archived gives the address, and one whose copy cannot be archived fails with MailDown.

exercises/2/start/src/notices.unauna
example "a notice that is sent and archived gives the address"
  given @customers = directory(sample_customers())
  given @mailer = outbox()
  given @archive = outbox()
  do notify_and_archive(Shipment(order: "A-1001", customer: "C-17", carrier: "Parcelo"))
  expect result == "rosa@example.invalid"

example "a notice whose copy cannot be archived is MailDown"
  given @customers = directory(sample_customers())
  given @mailer = outbox()
  given @archive = mail_down()
  do notify_and_archive(Shipment(order: "A-1001", customer: "C-17", carrier: "Parcelo"))
  expect fails MailDown

Hint: keep the address that notify returns with let, then send the copy on @archive, and give the address back on the last line. A failure of the archive means the notice does not count as sent, so turn it into the variant the example expects, with if error fail MailDown.

Check your answer with una test .. On the start package it reports:

Output
example notices "a notice whose copy cannot be archived is MailDown" ... FAILED
  src/notices.una:171: expect fails MailDown
  the `do` line completed with `"rosa@example.invalid"`
9 examples: 8 passed, 1 failed
Answer (check, run, test; exercises/2/answer).

Replace the body:

src/notices.unadiff
--- a/src/notices.una
+++ b/src/notices.una
@@ -51,3 +51,3 @@
 --- Sends the notice, then a copy of it to the store's archive mailbox. A notice counts as sent
---- only once its copy is archived. Exercise 2: send the copy.
+--- only once its copy is archived.
 pub notify_and_archive(shipment: Shipment) -> Text
@@ -58,4 +58,7 @@
 =
-  notify(shipment)
+  let address = notify(shipment)
     if error pass
+  @archive.send("archive@example.invalid", subject: "Notice for order {shipment.order}", body: "sent to {address}")
+    if error fail MailDown
+  address
 

The two bindings have the same capability and different names, so an example installs a different handler for each: the second example sends the notice through outbox() and fails the copy through mail_down().

12.8.3 Exercise 3: a contact line that never fails

A packer writes the customer's name and address on each parcel. Write contact(id: Text) -> Text, which gives "Rosa <rosa@example.invalid>" for a known customer, and "<id>: no address on file" for an unknown one or when the directory does not answer. Its header has no fails, so no failure may leave it. The start package has the header with a stub body, and three examples:

exercises/3/start/src/notices.unauna
--- The line a packer writes on a parcel: the customer's name and address, or a note when the
--- directory does not know the customer or does not answer. It never fails. Exercise 3.
pub contact(id: Text) -> Text
  uses @customers: Customers[find]
=
  ""
exercises/3/start/src/notices.unauna
example "a known customer gives a name and an address"
  given @customers = directory(sample_customers())
  do contact("C-17")
  expect result == "Rosa <rosa@example.invalid>"

example "an unknown customer gives a note"
  given @customers = directory(sample_customers())
  do contact("C-99")
  expect result == "C-99: no address on file"

example "a directory that does not answer gives a note, and no failure"
  given @customers = directory_down()
  do contact("C-17")
  expect result == "C-17: no address on file"

Hint: do as orderable does in Recovering with a default from a service. Call @customers.find(id) and turn its failure into None with if error use None. Then take the Option apart with when: is Some(customer) builds the line from customer.name and customer.email, and is None gives the note.

Check your answer with una test .. On the start package it reports:

Output
example notices "a known customer gives a name and an address" ... FAILED
  src/notices.una:158: expect result == "Rosa <rosa@example.invalid>"
  it is false, with `result` = `""`
10 examples: 7 passed, 3 failed
Answer (check, run, test; exercises/3/answer).

Replace the body:

src/notices.unadiff
--- a/src/notices.una
+++ b/src/notices.una
@@ -67,3 +67,3 @@
 --- The line a packer writes on a parcel: the customer's name and address, or a note when the
---- directory does not know the customer or does not answer. It never fails. Exercise 3.
+--- directory does not know the customer or does not answer. It never fails.
 pub contact(id: Text) -> Text
@@ -71,3 +71,7 @@
 =
-  ""
+  let found = @customers.find(id)
+    if error use None
+  when found
+    is Some(customer) -> "{customer.name} <{customer.email}>"
+    is None -> "{id}: no address on file"
 

The directory's failure becomes None, so the third example falls into the same arm as an unknown customer, and contact keeps the promise of its header: a text, always.

Next:12.9 Recap and reference