Home / Learn / 7 Results and failures
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
--- 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
NoneOutOfStock 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.
--- 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.
--- 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
orderThe 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.
--- 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 pass7.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.
--- 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:
--- 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:
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:
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