Home / Learn / 10 Collections
10.6 Day-to-day: a daily sales report
Page 7 of 11
10.6.1 What the report must do
At the end of each day the shop exports its order lines, one JSON object per line. Some lines are incomplete. The report must read every line it can, say how many it skipped, total the units and the revenue of each category, name the best seller, and hand the totals to the accounting service as JSON.
The design follows from the data. The export is text, so each line is parsed on its own, and a bad line becomes None instead of stopping the report. The fields have types, so a Line record holds them once they are read, and nothing after read_line deals with JSON. The totals are per category and per SKU, so two maps hold them, and their key order gives the report its order.
The program is one module, and each part uses one idea of this chapter: records hold the fields, JSON and Option read them (section 10.5), a loop over a list keeps the good lines (section 10.1), maps group them (section 10.4), and fold and first_where find the best seller (section 10.3). Here it is in parts.
10.6.2 The records
Two kinds: one for a line of the export, and one for what a category sold.
--- One line of an order: a SKU, its category, how many units, and the price of one unit in cents.
pub kind Line
sku: Text
category: Text
quantity: Int
cents: Int
--- What one category sold: its units and its revenue in cents.
pub kind Summary
category: Text
units: Int
cents: Int10.6.3 Reading a line
This is the only part of the program that sees JSON. Two private helpers read one field each, as an Option: they use the reading form of Reading a field, and give None when the field is missing or holds another kind of value. read_line parses the text, checks that it is an object, and builds a Line when the fields it needs are there.
--- The text in the field `name` of a JSON object, or `None` when it is missing or not a string.
text_field(fields: Map[Text, Json], name: Text) -> Option[Text]
=
let found = fields.get(key: name).or_else(default: Null)
when found
is Str(value) -> Some(value)
else -> None
--- The whole number in the field `name` of a JSON object, or `None`.
int_field(fields: Map[Text, Json], name: Text) -> Option[Int]
=
let found = fields.get(key: name).or_else(default: Null)
when found
is Number(value) -> Some(value)
else -> None
--- An order line from one line of the export, or `None` when the line cannot be read.
--- A line without a category counts under "other".
pub read_line(text: Text) -> Option[Line]
=
let json = text.parse_json()
if error use Null
when json
is Object(fields) ->
let category = text_field(fields, name: "category").or_else(default: "other")
let sku = text_field(fields, name: "sku")
let quantity = int_field(fields, name: "quantity")
let cents = int_field(fields, name: "cents")
when sku
is None -> None
is Some(code) ->
when quantity
is None -> None
is Some(units) ->
when cents
is None -> None
is Some(price) -> Some(Line(sku: code, category: category, quantity: units, cents: price))
else -> NoneA missing category has a sensible default, so or_else gives "other". A missing SKU, quantity or price has none: the line cannot be used, so the result is None. Each when handles one of these fields, and the three nest: the Line is built only in the innermost arm, where all three are Some.
10.6.4 Keeping the lines that could be read
A for loop over the export, with a list, lines, declared before it with let edit. At each turn, a when over the Option that read_line gives appends the Some values. The None arm gives unit, and so does nothing: the line is skipped.
--- The lines that could be read, in the order of the export.
pub read_all(export: List[Text]) -> List[Line]
=
let edit lines: List[Line] = []
for text in export
let found = read_line(text)
when found
is Some(line) ->
lines = lines.append(item: line)
is None -> unit
lines10.6.5 Grouping
The pattern of Stock by SKU, twice. by_category keeps a Summary per category, and units_by_sku an Int per SKU.
--- The units and revenue of each category, ordered by category.
pub by_category(lines: List[Line]) -> Map[Text, Summary]
=
let edit totals: Map[Text, Summary] = empty_map()
for line in lines
let empty = Summary(category: line.category, units: 0, cents: 0)
let before = totals.get(key: line.category).or_else(default: empty)
let units = before.units + line.quantity
let cents = before.cents + line.quantity * line.cents
edit totals.set(key: line.category, value: Summary(category: line.category, units: units, cents: cents))
totals
--- The units sold of each SKU.
pub units_by_sku(lines: List[Line]) -> Map[Text, Int]
=
let edit units: Map[Text, Int] = empty_map()
for line in lines
let before = units.get(key: line.sku).or_else(default: 0)
edit units.set(key: line.sku, value: before + line.quantity)
unitsThe default for a new category is a Summary with zeros, so the same lines handle the first line of a category and every later one. No list of categories is written anywhere: a category the store adds tomorrow gets its own entry the first time a line names it.
10.6.6 The best seller
fold finds the largest number of units. Then first_where finds the first entry with that number. Entries come in SKU order, so on a tie the first SKU in order wins, and the result does not depend on the order of the export. An empty map gives None, and headline says so. An Entry is the prelude's record of one key and its value, so in headline, entry.key is the SKU and entry.value its units.
--- The SKU that sold the most units, the first in SKU order on a tie; `None` for no sales.
pub best_seller(units: Map[Text, Int]) -> Option[Entry[Text, Int]]
=
let most = units.values().fold(initial: 0, step: fn(top, n) -> max(top, b: n))
units.entries().first_where(keep: fn(entry) -> entry.value == most)
--- The report's line about the best seller.
pub headline(best: Option[Entry[Text, Int]]) -> Text
=
when best
is Some(entry) -> "best seller: {entry.key}, {entry.value} units"
is None -> "no sales"10.6.7 Money and the JSON summary
money writes cents as an amount with two decimals. totals_json adds up the categories with map and sum, and builds a JSON object field by field.
--- Cents as a decimal amount: 13930 is "139.30".
pub money(cents: Int) -> Text
=
let rest = cents mod 100
if rest < 10 then "{cents / 100}.0{rest}" else "{cents / 100}.{rest}"
--- The totals of the day as one JSON object, for the accounting service.
pub totals_json(summaries: List[Summary], skipped: Int) -> Text
=
let units = summaries.map(each: fn(summary) -> summary.units).sum()
let cents = summaries.map(each: fn(summary) -> summary.cents).sum()
let edit fields: Map[Text, Json] = empty_map()
edit fields.set(key: "categories", value: Number(value: summaries.len))
edit fields.set(key: "units", value: Number(value: units))
edit fields.set(key: "cents", value: Number(value: cents))
edit fields.set(key: "skipped", value: Number(value: skipped))
Object(fields).to_json()For an amount that is not negative, cents / 100 is the whole part and cents mod 100 the cents left over. The if … then … else on one line chooses the form with a leading zero.
10.6.8 Running it
sample_export holds the day's export as literals. Each line is appended on its own, since canonical form keeps a list literal on one line. main reads it, groups it, and prints the report.
--- The day's export: one JSON object per order line.
pub sample_export() -> List[Text]
=
let edit lines: List[Text] = []
lines = lines.append(item: "\{\"sku\": \"LAMP-01\", \"category\": \"lighting\", \"quantity\": 2, \"cents\": 1990\}")
lines = lines.append(item: "\{\"sku\": \"DESK-02\", \"category\": \"furniture\", \"quantity\": 2, \"cents\": 15900\}")
lines = lines.append(item: "\{\"sku\": \"RUG-07\", \"category\": \"textiles\", \"quantity\": 3, \"cents\": 4500\}")
lines = lines.append(item: "\{\"sku\": \"LAMP-01\", \"category\": \"lighting\", \"quantity\": 4, \"cents\": 1990\}")
lines = lines.append(item: "\{\"sku\": \"CHAIR-09\", \"category\": \"furniture\"\}")
lines = lines.append(item: "\{\"sku\": \"SHADE-05\", \"category\": \"lighting\", \"quantity\": 2, \"cents\": 1250\}")
lines = lines.append(item: "\{\"sku\": \"VASE-03\", \"quantity\": 2, \"cents\": 2400\}")
lines = lines.append(item: "\{\"sku\": \"RUG-07\", \"category\": \"textiles\", \"quantity\": 1, \"cents\": 4500\}")
lines
pub main() -> Unit
uses @console: Console[print]
=
let export = sample_export()
let lines = read_all(export)
let skipped = export.len - lines.len
@console.print("{export.len} lines, {skipped} skipped")
let summaries = by_category(lines).values()
for summary in summaries
@console.print("{summary.category}: {summary.units} units, {money(summary.cents)}")
@console.print(headline(best_seller(units_by_sku(lines))))
@console.print(totals_json(summaries, skipped: skipped))In the day-to-day directory, una run . prints the report shown in What you'll build: eight lines, the CHAIR-09 line skipped for its missing quantity, and the VASE-03 line counted under "other". summaries comes from values(), so the categories print in name order. skipped is the difference of two lengths, since every line of the export either became a Line or was left out.
Security
The export here is a literal. A program that reads it from a file needs the right to read files, a capability (chapter 12). The text it reads is marked as internal data, which may reach the console only under a declared policy (chapter 17).
10.6.9 The whole program
The whole file, to read in one piece or to copy:
module report
--- One line of an order: a SKU, its category, how many units, and the price of one unit in cents.
pub kind Line
sku: Text
category: Text
quantity: Int
cents: Int
--- What one category sold: its units and its revenue in cents.
pub kind Summary
category: Text
units: Int
cents: Int
--- The text in the field `name` of a JSON object, or `None` when it is missing or not a string.
text_field(fields: Map[Text, Json], name: Text) -> Option[Text]
=
let found = fields.get(key: name).or_else(default: Null)
when found
is Str(value) -> Some(value)
else -> None
--- The whole number in the field `name` of a JSON object, or `None`.
int_field(fields: Map[Text, Json], name: Text) -> Option[Int]
=
let found = fields.get(key: name).or_else(default: Null)
when found
is Number(value) -> Some(value)
else -> None
--- An order line from one line of the export, or `None` when the line cannot be read.
--- A line without a category counts under "other".
pub read_line(text: Text) -> Option[Line]
=
let json = text.parse_json()
if error use Null
when json
is Object(fields) ->
let category = text_field(fields, name: "category").or_else(default: "other")
let sku = text_field(fields, name: "sku")
let quantity = int_field(fields, name: "quantity")
let cents = int_field(fields, name: "cents")
when sku
is None -> None
is Some(code) ->
when quantity
is None -> None
is Some(units) ->
when cents
is None -> None
is Some(price) -> Some(Line(sku: code, category: category, quantity: units, cents: price))
else -> None
--- The lines that could be read, in the order of the export.
pub read_all(export: List[Text]) -> List[Line]
=
let edit lines: List[Line] = []
for text in export
let found = read_line(text)
when found
is Some(line) ->
lines = lines.append(item: line)
is None -> unit
lines
--- The units and revenue of each category, ordered by category.
pub by_category(lines: List[Line]) -> Map[Text, Summary]
=
let edit totals: Map[Text, Summary] = empty_map()
for line in lines
let empty = Summary(category: line.category, units: 0, cents: 0)
let before = totals.get(key: line.category).or_else(default: empty)
let units = before.units + line.quantity
let cents = before.cents + line.quantity * line.cents
edit totals.set(key: line.category, value: Summary(category: line.category, units: units, cents: cents))
totals
--- The units sold of each SKU.
pub units_by_sku(lines: List[Line]) -> Map[Text, Int]
=
let edit units: Map[Text, Int] = empty_map()
for line in lines
let before = units.get(key: line.sku).or_else(default: 0)
edit units.set(key: line.sku, value: before + line.quantity)
units
--- The SKU that sold the most units, the first in SKU order on a tie; `None` for no sales.
pub best_seller(units: Map[Text, Int]) -> Option[Entry[Text, Int]]
=
let most = units.values().fold(initial: 0, step: fn(top, n) -> max(top, b: n))
units.entries().first_where(keep: fn(entry) -> entry.value == most)
--- The report's line about the best seller.
pub headline(best: Option[Entry[Text, Int]]) -> Text
=
when best
is Some(entry) -> "best seller: {entry.key}, {entry.value} units"
is None -> "no sales"
--- Cents as a decimal amount: 13930 is "139.30".
pub money(cents: Int) -> Text
=
let rest = cents mod 100
if rest < 10 then "{cents / 100}.0{rest}" else "{cents / 100}.{rest}"
--- The totals of the day as one JSON object, for the accounting service.
pub totals_json(summaries: List[Summary], skipped: Int) -> Text
=
let units = summaries.map(each: fn(summary) -> summary.units).sum()
let cents = summaries.map(each: fn(summary) -> summary.cents).sum()
let edit fields: Map[Text, Json] = empty_map()
edit fields.set(key: "categories", value: Number(value: summaries.len))
edit fields.set(key: "units", value: Number(value: units))
edit fields.set(key: "cents", value: Number(value: cents))
edit fields.set(key: "skipped", value: Number(value: skipped))
Object(fields).to_json()
--- The day's export: one JSON object per order line.
pub sample_export() -> List[Text]
=
let edit lines: List[Text] = []
lines = lines.append(item: "\{\"sku\": \"LAMP-01\", \"category\": \"lighting\", \"quantity\": 2, \"cents\": 1990\}")
lines = lines.append(item: "\{\"sku\": \"DESK-02\", \"category\": \"furniture\", \"quantity\": 2, \"cents\": 15900\}")
lines = lines.append(item: "\{\"sku\": \"RUG-07\", \"category\": \"textiles\", \"quantity\": 3, \"cents\": 4500\}")
lines = lines.append(item: "\{\"sku\": \"LAMP-01\", \"category\": \"lighting\", \"quantity\": 4, \"cents\": 1990\}")
lines = lines.append(item: "\{\"sku\": \"CHAIR-09\", \"category\": \"furniture\"\}")
lines = lines.append(item: "\{\"sku\": \"SHADE-05\", \"category\": \"lighting\", \"quantity\": 2, \"cents\": 1250\}")
lines = lines.append(item: "\{\"sku\": \"VASE-03\", \"quantity\": 2, \"cents\": 2400\}")
lines = lines.append(item: "\{\"sku\": \"RUG-07\", \"category\": \"textiles\", \"quantity\": 1, \"cents\": 4500\}")
lines
pub main() -> Unit
uses @console: Console[print]
=
let export = sample_export()
let lines = read_all(export)
let skipped = export.len - lines.len
@console.print("{export.len} lines, {skipped} skipped")
let summaries = by_category(lines).values()
for summary in summaries
@console.print("{summary.category}: {summary.units} units, {money(summary.cents)}")
@console.print(headline(best_seller(units_by_sku(lines))))
@console.print(totals_json(summaries, skipped: skipped))
example "a line with every field is read"
do read_line("\{\"sku\": \"LAMP-01\", \"category\": \"lighting\", \"quantity\": 2, \"cents\": 1990\}")
expect result == Some(Line(sku: "LAMP-01", category: "lighting", quantity: 2, cents: 1990))
example "a line without a category counts under other"
do read_line("\{\"sku\": \"VASE-03\", \"quantity\": 2, \"cents\": 2400\}")
expect result == Some(Line(sku: "VASE-03", category: "other", quantity: 2, cents: 2400))
example "a line without a quantity is skipped"
do read_line("\{\"sku\": \"CHAIR-09\", \"category\": \"furniture\"\}")
expect result == None
example "a line that is not JSON is skipped"
do read_line("LAMP-01, 2")
expect result == None
example "two lines of one category add up"
do by_category([Line(sku: "LAMP-01", category: "lighting", quantity: 2, cents: 1990), Line(sku: "SHADE-05", category: "lighting", quantity: 1, cents: 1250)])
expect result.get(key: "lighting") == Some(Summary(category: "lighting", units: 3, cents: 5230))
example "on a tie, the first SKU in order is the best seller"
do best_seller(empty_map().with(key: "RUG-07", value: 3).with(key: "LAMP-01", value: 3))
expect result == Some(Entry(key: "LAMP-01", value: 3))
example "a day without sales has no best seller"
do headline(best_seller(empty_map()))
expect result == "no sales"
example "amounts keep two digits of cents"
do money(1205)
expect result == "12.05"Next:10.7 Testing it