Home / Learn / 19 Editions
19.6 Day-to-day: a shelf-label printer
Page 7 of 11
19.6.1 What the program must do
Now the program from the start of the chapter. The store prints shelf labels from a stock export. A line that does not parse is left out, a line with no stock gets no label, and a dry run must count the labels without printing any, so that the night shift can check a run before it uses up the label stock. The package is on edition 0.3, because the dry run's rule is one the checker can then enforce.
19.6.2 The manifest: the edition and the lock
The manifest names the edition and locks one function's authority:
[package]
name = "labels"
version = "0.1.0"
edition = "0.3"
[run]
entry = "labels"
grants = ["console"]
[contracts]
"labels.print_labels" = ["@printer: Printer[print_label where not dry_run]"]edition = "0.3" opts into the preview. [contracts] locks the authority of print_labels: whatever its header says, it may never print a label where dry_run is true. Each key is the qualified name of a public function, its module's name, a dot and its own name, and each value lists uses clauses as a header writes them. The header may grant less than its lock, never more. A change to that line is a change to una.toml, which a reviewer sees in the diff, even when nobody touches the code.
Why both a condition and a lock? The condition makes the verifier check the body against the header. The lock makes the checker hold the header to una.toml. Without the lock, a later change could drop where not dry_run from the header and add a print without a guard, and the package would still check. With it, that change is U3023 until una.toml changes too.
19.6.3 The kinds, the printer and the parser
These use edition 0.1 and 0.2 constructs only: a record, a sum kind for the failures, a capability, and a parser that fails with LineError. text.split is a text function of 0.2; to_int and trim exist in 0.1 too.
module labels
--- A line of a stock list: a SKU and the units on hand.
pub kind Line
sku: Text
units: Int
--- Why a line of a stock export was rejected.
pub kind LineError = Malformed(text: Text) | BadUnits(text: Text)
--- The shelf-label printer.
pub capability Printer
op print_label(sku: Text, units: Int) -> Unit
--- Reads `"SKU, units"`.
pub parse_line(text: Text) -> Line
fails LineError
=
let parts = text.split(on: ",")
let sku = parts.at(index: 0)
if none fail Malformed(text)
let raw = parts.at(index: 1)
if none fail Malformed(text)
let units = raw.trim.to_int()
if none fail BadUnits(text)
Line(sku: sku.trim, units: units)
19.6.4 Reading an export
read_lines keeps the lines that parse. attempt keeps each outcome as a Result, and a when on it decides whether the line is added. On 0.3, attempt must wrap a call that can fail, and parse_line can, so U3026 does not apply.
--- Reads every line of an export; a line that does not parse is left out.
pub read_lines(export: List[Text]) -> List[Line]
=
let edit lines: List[Line] = []
for text in export
let outcome = attempt parse_line(text)
lines = when outcome
is Ok(line) -> lines.append(item: line)
is Err -> lines
lines19.6.5 Printing, with a dry run
The header gives print_label a condition: where not dry_run, a construct of 0.3. Inside the body, the operation is called only under if not dry_run, and the verifier proves that the condition holds there. Remove the guard, and the check fails with a counterexample where dry_run is true (An operation outside its condition shows it).
--- Prints a label for every line with stock, and gives how many. A dry run prints nothing.
pub print_labels(lines: List[Line], dry_run: Bool) -> Int
uses @printer: Printer[print_label where not dry_run]
=
let edit printed = 0
for line in lines
if line.units > 0
if not dry_run
@printer.print_label(line.sku, units: line.units)
printed = printed + 1
printedThe function counts a label whether or not it prints it, so a dry run gives the number of labels a real run would print. The two nested if statements have no else: an if without else is a statement that does nothing when its condition is false (section 8.1), which edition 0.2 added along with the loop. The count is a let edit binding that the loop updates, as in chapter 9. The condition is part of the header, so una contract labels.print_labels shows it, and every caller sees that a dry run prints nothing without reading the body.
19.6.6 Running it
on_console prints a label as a line of text, which stands in for the label printer here. It is a handler with a uses clause of its own, so it may print to the console and nothing else, and una report . lists it under handler authority. silent prints nothing, for the tests. main makes a dry run, then a real one, each installing on_console for one call with with:
--- A printer that writes each label to the console.
handler on_console() for Printer
uses @console: Console[print]
op print_label(sku, units) = @console.print("[{sku} | {units} on hand]")
--- A printer that prints nothing, for the tests.
handler silent() for Printer
op print_label(sku, units) = unit
--- The stock export of this run: one line has no stock, and one does not parse.
export() -> List[Text] = ["LAMP-01, 4", "DESK-02, 0", "CHAIR-09, two", "SHELF-03, 12"]
pub main() -> Unit
uses @console: Console[print]
=
let lines = read_lines(export())
let planned = print_labels(lines, dry_run: true) with @printer = on_console()
@console.print("dry run: {planned} labels")
let printed = print_labels(lines, dry_run: false) with @printer = on_console()
@console.print("printed {printed} labels")una run . prints the output shown in What you'll build. It uses the kinds and the when of 0.1, the loops, let edit and the text functions of 0.2, and the condition and the lock of 0.3. The dry run counts two labels and prints none. The real run prints the lamp and the shelf. The desk has no stock, and the chair's line, CHAIR-09, two, does not parse, so neither gets a label. una report . lists the printer handler under handler authority, with what it may do:
handler authority:
labels.on_console for labels.Printer (private): @console: Console[print]19.6.7 The whole program
The whole file:
module labels
--- A line of a stock list: a SKU and the units on hand.
pub kind Line
sku: Text
units: Int
--- Why a line of a stock export was rejected.
pub kind LineError = Malformed(text: Text) | BadUnits(text: Text)
--- The shelf-label printer.
pub capability Printer
op print_label(sku: Text, units: Int) -> Unit
--- Reads `"SKU, units"`.
pub parse_line(text: Text) -> Line
fails LineError
=
let parts = text.split(on: ",")
let sku = parts.at(index: 0)
if none fail Malformed(text)
let raw = parts.at(index: 1)
if none fail Malformed(text)
let units = raw.trim.to_int()
if none fail BadUnits(text)
Line(sku: sku.trim, units: units)
--- Reads every line of an export; a line that does not parse is left out.
pub read_lines(export: List[Text]) -> List[Line]
=
let edit lines: List[Line] = []
for text in export
let outcome = attempt parse_line(text)
lines = when outcome
is Ok(line) -> lines.append(item: line)
is Err -> lines
lines
--- Prints a label for every line with stock, and gives how many. A dry run prints nothing.
pub print_labels(lines: List[Line], dry_run: Bool) -> Int
uses @printer: Printer[print_label where not dry_run]
=
let edit printed = 0
for line in lines
if line.units > 0
if not dry_run
@printer.print_label(line.sku, units: line.units)
printed = printed + 1
printed
--- A printer that writes each label to the console.
handler on_console() for Printer
uses @console: Console[print]
op print_label(sku, units) = @console.print("[{sku} | {units} on hand]")
--- A printer that prints nothing, for the tests.
handler silent() for Printer
op print_label(sku, units) = unit
--- The stock export of this run: one line has no stock, and one does not parse.
export() -> List[Text] = ["LAMP-01, 4", "DESK-02, 0", "CHAIR-09, two", "SHELF-03, 12"]
pub main() -> Unit
uses @console: Console[print]
=
let lines = read_lines(export())
let planned = print_labels(lines, dry_run: true) with @printer = on_console()
@console.print("dry run: {planned} labels")
let printed = print_labels(lines, dry_run: false) with @printer = on_console()
@console.print("printed {printed} labels")
test "a line that does not parse is left out"
do read_lines(export()).len
expect result == 3
test "a dry run counts the labels and prints none"
given @printer = silent()
do print_labels(read_lines(export()), dry_run: true)
expect result == 2
expect not performed @printer.print_label
test "a run prints a label for each line with stock"
given @printer = silent()
do print_labels(read_lines(export()), dry_run: false)
expect result == 2
expect performed @printer.print_labelNext:19.7 Testing it