Home / Learn / 7 Results and failures

Release v0.4.0Edition 0.2

7.7 Day-to-day: order intake

Page 8 of 12

7.7.1 What the program must do

Now the program from What you'll 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); one for the stock list, StockError, which the order layer translates with a clause (section 7.3); an Option for a SKU the stock list does not know (section 7.1); and attempt around each line, so that every line gets its report (section 7.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

day-to-day/src/orders.unathe kinds and the stock listuna
--- 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 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.

day-to-day/src/orders.unauna
--- 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.

day-to-day/src/orders.unauna
--- 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.

day-to-day/src/orders.unauna
--- 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 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.

day-to-day/src/orders.unauna
--- 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 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:

day-to-day/src/orders.unauna
--- 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. 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:

day-to-day/src/orders.unathe whole programcheckruntestuna
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"

Next:7.8 Testing it