---
title: "7.7 Day-to-day: order intake"
url: https://una-lang.org/en/learn/failure/day-to-day-order-intake/
release: v0.4.0
edition: "0.2"
---

# 7.7 Day-to-day: order intake

## 7.7.1 What the program must do

Now the program from [What you'll build](https://una-lang.org/en/learn/failure/#what-youll-build). Orders arrive as lines of text, such as `LAMP-01, 2`. Each line must have a comma, a whole number of at least 1 after it, and a SKU the store's stock list knows, and it must ask for no more units than are on hand. A shelf that is being counted has no count for now. Every line gets its own report line, and a rejected line says why, in words an operator can act on.

The design follows from that, and each part uses one section of this chapter: one error kind for the order layer, `OrderError`, whose variants carry what an operator needs ([section 7.2](https://una-lang.org/en/learn/failure/declaring-a-failure-fails-and-fail/#s7-2)); one for the stock list, `StockError`, which the order layer translates with a clause ([section 7.3](https://una-lang.org/en/learn/failure/handling-a-failure-the-clauses/#s7-3)); an `Option` for a SKU the stock list does not know ([section 7.1](https://una-lang.org/en/learn/failure/a-value-that-may-be-missing-option/#s7-1)); and `attempt` around each line, so that every line gets its report ([section 7.4](https://una-lang.org/en/learn/failure/failures-as-values-attempt-and-result/#s7-4)). Every function except `main` is pure: it only computes, so each one can be tested with a plain example.

## 7.7.2 The kinds and the stock list

```una include="day-to-day/src/orders.una#Order..on_hand" title="day-to-day/src/orders.una" caption="the kinds and the stock list"
--- One line of an order: a stock-keeping unit (SKU) and how many of it.
pub kind Order
  sku: Text
  quantity: Int

--- Why an order line was rejected. Each variant carries what a person needs to act on it.
pub kind OrderError = Malformed(line: Text) | BadQuantity(line: Text) | UnknownSku(sku: Text) | OutOfStock(sku: Text, wanted: Int, left: Int) | Unavailable(sku: Text)

--- Why the stock list cannot give a count.
pub kind StockError = | BeingCounted(sku: Text)

--- The units on hand of a SKU, `None` for a SKU the store does not sell. It fails while the
--- SKU's shelf is being counted.
pub on_hand(sku: Text) -> Option[Int]
  fails StockError
=
  if sku == "LAMP-01"
    Some(4)
  else if sku == "DESK-02"
    Some(1)
  else if sku == "RUG-07"
    fail BeingCounted(sku)
  else
    None
```

`OutOfStock` carries the SKU, the units wanted and the units left, which is everything the report line needs. `Unavailable` carries the SKU whose shelf is being counted, since the operator's action is to retry that line later.

`on_hand` is the store's stock list, written as a function. Its result says two things at once. `Some(4)` is a count, and `None` means that the store does not sell the SKU: a normal answer. A failure, `BeingCounted`, means that the stock list cannot answer for now: the shelf of `RUG-07` is being counted. In a larger program the counts would come from a file or a service, [chapter 12](https://una-lang.org/en/learn/capabilities/) shows how; the rest of the program would not change.

## 7.7.3 Parsing, a step on the text alone

`parse_order` only looks at the text. Each problem with the text becomes its own variant: `if none fail` for a part that is missing, and `fail` in a branch for a quantity below 1.

```una include="day-to-day/src/orders.una#parse_order" title="day-to-day/src/orders.una"
--- Reads `"SKU, quantity"`. It only looks at the text.
pub parse_order(line: Text) -> Order
  fails OrderError
=
  let comma = line.find(text: ",")
    if none fail Malformed(line)
  let sku = line.slice(start: 0, end: comma).trim
  let quantity = line.slice(start: comma + 1, end: line.len).trim.to_int()
    if none fail BadQuantity(line)
  if quantity < 1
    fail BadQuantity(line)
  else
    Order(sku: sku, quantity: quantity)
```

`find` gives the position of the comma, or `None` when the line has none. The SKU is the text before the comma, and the quantity the text after it, each trimmed. The verifier proves both `slice` calls, since `find` tells it that the comma lies inside the line.

## 7.7.4 Checking stock, a step with two clauses

Two clauses handle the one call: the stock list's failure becomes `Unavailable`, and an unknown SKU becomes `UnknownSku`. After them, `left` is a plain `Int`, and the comparison with the quantity wanted is ordinary code. `check_stock` gives back the order unchanged when there is enough stock, so the next step can use it.

```una include="day-to-day/src/orders.una#check_stock" title="day-to-day/src/orders.una"
--- Confirms that the stock list holds enough units of the order's SKU.
pub check_stock(order: Order) -> Order
  fails OrderError
=
  let left = on_hand(order.sku)
    if error fail Unavailable(sku: order.sku)
    if none fail UnknownSku(sku: order.sku)
  if order.quantity > left
    fail OutOfStock(sku: order.sku, wanted: order.quantity, left: left)
  else
    order
```

The two clauses are in the fixed order: `if error` first, for the call's failure, then `if none`, for the value it gave.

## 7.7.5 Composing the steps

Both steps fail with `OrderError`, the same kind as `accept`, so `if error pass` hands their failures on unchanged. The order of the two statements is the order of the work: a line that does not parse never reaches the stock list.

```una include="day-to-day/src/orders.una#accept" title="day-to-day/src/orders.una"
--- One line, from text to an order that can be shipped.
pub accept(line: Text) -> Order
  fails OrderError
=
  let order = parse_order(line)
    if error pass
  check_stock(order)
    if error pass
```

## 7.7.6 The report

`reason` has one arm per variant. If `OrderError` gains a variant, the checker reports this `when` until it has an arm for it ([exercise 1](https://una-lang.org/en/learn/failure/exercises/#exercise-1-a-per-line-limit) shows this). `reason` writes the fields of each variant into its sentence, which is why each variant carries what it does: an operator who reads `3 of DESK-02 wanted, 1 left` knows what to change.

```una include="day-to-day/src/orders.una#reason..report" title="day-to-day/src/orders.una"
--- What a person reads in the report.
pub reason(failure: OrderError) -> Text
=
  when failure
    is Malformed(line) -> "cannot read the line '{line}'"
    is BadQuantity(line) -> "the quantity in '{line}' is not a whole number above 0"
    is UnknownSku(sku) -> "no product has the SKU {sku}"
    is OutOfStock(sku, wanted, left) -> "{wanted} of {sku} wanted, {left} left"
    is Unavailable(sku) -> "the shelf of {sku} is being counted; retry later"

--- One line of the report: the order line accepted, or the reason it was not.
pub report(line: Text) -> Text
=
  let outcome = attempt accept(line)
  when outcome
    is Ok(order) -> "ok      {order.quantity} x {order.sku}"
    is Err(failure) -> "reject  {reason(failure)}"
```

`report` is where [section 7.4](https://una-lang.org/en/learn/failure/failures-as-values-attempt-and-result/#s7-4) pays off. `attempt` keeps the outcome of `accept`, so `report` itself never fails: its header has no `fails`, and that is a promise to its callers. Every line gets a report line, accepted or rejected, with the reason.

## 7.7.7 Running it

`main` reports one line of each kind:

```una include="day-to-day/src/orders.una#main" title="day-to-day/src/orders.una"
--- Prints the report of the day's order lines.
pub main() -> Unit
  uses @console: Console[print]
=
  @console.print(report("LAMP-01, 2"))
  @console.print(report("DESK-02, 3"))
  @console.print(report("CHAIR-09, 1"))
  @console.print(report("RUG-07, 1"))
  @console.print(report("LAMP-01, two"))
  @console.print(report("LAMP-01"))
```

In the `day-to-day` directory:

```sh
una check .
una run .
```

`una run .` prints the report shown in [What you'll build](https://una-lang.org/en/learn/failure/#what-youll-build). The order lines here are literals, one for each outcome: a line in stock, too many units, an unknown SKU, a shelf being counted, a quantity in words and a line with no comma. `report` pads `ok` and `reject` to the same width, so the reasons line up.

## 7.7.8 The whole program

The whole file, to read in one piece or to copy:

```una include="day-to-day/src/orders.una" title="day-to-day/src/orders.una" caption="the whole program" verified="check, run, test"
module orders

--- One line of an order: a stock-keeping unit (SKU) and how many of it.
pub kind Order
  sku: Text
  quantity: Int

--- Why an order line was rejected. Each variant carries what a person needs to act on it.
pub kind OrderError = Malformed(line: Text) | BadQuantity(line: Text) | UnknownSku(sku: Text) | OutOfStock(sku: Text, wanted: Int, left: Int) | Unavailable(sku: Text)

--- Why the stock list cannot give a count.
pub kind StockError = | BeingCounted(sku: Text)

--- The units on hand of a SKU, `None` for a SKU the store does not sell. It fails while the
--- SKU's shelf is being counted.
pub on_hand(sku: Text) -> Option[Int]
  fails StockError
=
  if sku == "LAMP-01"
    Some(4)
  else if sku == "DESK-02"
    Some(1)
  else if sku == "RUG-07"
    fail BeingCounted(sku)
  else
    None

--- Reads `"SKU, quantity"`. It only looks at the text.
pub parse_order(line: Text) -> Order
  fails OrderError
=
  let comma = line.find(text: ",")
    if none fail Malformed(line)
  let sku = line.slice(start: 0, end: comma).trim
  let quantity = line.slice(start: comma + 1, end: line.len).trim.to_int()
    if none fail BadQuantity(line)
  if quantity < 1
    fail BadQuantity(line)
  else
    Order(sku: sku, quantity: quantity)

--- Confirms that the stock list holds enough units of the order's SKU.
pub check_stock(order: Order) -> Order
  fails OrderError
=
  let left = on_hand(order.sku)
    if error fail Unavailable(sku: order.sku)
    if none fail UnknownSku(sku: order.sku)
  if order.quantity > left
    fail OutOfStock(sku: order.sku, wanted: order.quantity, left: left)
  else
    order

--- One line, from text to an order that can be shipped.
pub accept(line: Text) -> Order
  fails OrderError
=
  let order = parse_order(line)
    if error pass
  check_stock(order)
    if error pass

--- What a person reads in the report.
pub reason(failure: OrderError) -> Text
=
  when failure
    is Malformed(line) -> "cannot read the line '{line}'"
    is BadQuantity(line) -> "the quantity in '{line}' is not a whole number above 0"
    is UnknownSku(sku) -> "no product has the SKU {sku}"
    is OutOfStock(sku, wanted, left) -> "{wanted} of {sku} wanted, {left} left"
    is Unavailable(sku) -> "the shelf of {sku} is being counted; retry later"

--- One line of the report: the order line accepted, or the reason it was not.
pub report(line: Text) -> Text
=
  let outcome = attempt accept(line)
  when outcome
    is Ok(order) -> "ok      {order.quantity} x {order.sku}"
    is Err(failure) -> "reject  {reason(failure)}"

--- Prints the report of the day's order lines.
pub main() -> Unit
  uses @console: Console[print]
=
  @console.print(report("LAMP-01, 2"))
  @console.print(report("DESK-02, 3"))
  @console.print(report("CHAIR-09, 1"))
  @console.print(report("RUG-07, 1"))
  @console.print(report("LAMP-01, two"))
  @console.print(report("LAMP-01"))

example "a line in stock is accepted"
  do accept("LAMP-01, 2")
  expect result == Order(sku: "LAMP-01", quantity: 2)

example "the spaces around the SKU and the quantity do not matter"
  do parse_order(" DESK-02 , 1 ")
  expect result == Order(sku: "DESK-02", quantity: 1)

example "a line without a comma is Malformed"
  do accept("LAMP-01")
  expect fails Malformed

example "a quantity that is not a number is BadQuantity"
  do accept("LAMP-01, two")
  expect fails BadQuantity

example "a quantity of 0 is BadQuantity"
  do accept("LAMP-01, 0")
  expect fails BadQuantity

example "a SKU the stock list does not know is UnknownSku"
  do accept("CHAIR-09, 1")
  expect fails UnknownSku

example "a shelf being counted is Unavailable"
  do accept("RUG-07, 1")
  expect fails Unavailable

example "too many units are out of stock"
  do accept("LAMP-01, 9")
  expect fails OutOfStock

example "the report says how many units are left"
  do report("DESK-02, 3")
  expect result == "reject  3 of DESK-02 wanted, 1 left"
```
