Home / Learn / 11 Packages and modules
11.4 Day-to-day: the store's invoice
Page 5 of 9
11.4.1 Five modules, one job each
Now the program from the start of the chapter. An order is a list of SKUs with quantities. The invoice looks each SKU up in the catalog, prices the line, shows what a member would pay for one unit, and names the SKUs the catalog does not list. Five modules under src/store/ share the work, each about one subject:
money.una:Cents, andformatfor amounts as people read them;catalog.una:Product, andfind, which looks a product up in a list of products;pricing.una: line prices and the members' price;invoice.una: order lines, lookups, and the text of each line;app.una:main, the entry of the package.
The manifest is the one of section 11.1, in edition 0.2, with store.app as its entry.
11.4.2 The import graph
The imports form a graph with no cycle: money imports nothing, catalog and pricing import money, invoice imports the three, and app imports catalog and invoice. An import cycle is U1003 (An import cycle).
Each import goes from a module that knows more to one that knows less. money knows nothing of products, and pricing takes amounts, not products, so a price rule can be tested without a catalog. Only invoice puts a product, its price and its text together, and only app decides which catalog the program runs against.
11.4.3 The interface of each module
The pub lines are the interface of each module. money shares Cents and format. catalog shares all it declares. pricing shares line_cents and member_price, and keeps discount. invoice shares its two kinds and its two functions. app shares only main, which una run needs, since the entry's main must be pub.
11.4.4 Money
The same module as in section 11.2, with its examples. format handles a negative amount, for a refund, and its private helper handles the digits:
module store.money
--- An amount of money in cents, never below zero.
pub kind Cents = Int where it >= 0
--- An amount in cents as a person reads it: 1990 is "19.90", and -150 is "-1.50".
pub format(cents: Int) -> Text = if cents < 0 then "-{digits(0 - cents)}" else digits(cents)
--- The digits of an amount of 0 or more, with two after the point.
digits(cents: Int) -> Text
=
let rest = cents mod 100
if rest < 10 then "{cents / 100}.0{rest}" else "{cents / 100}.{rest}"
example "two digits after the point"
do format(1990)
expect result == "19.90"
example "a leading zero is kept"
do format(24905)
expect result == "249.05"
example "a refund keeps its sign"
do format(-150)
expect result == "-1.50"The examples sit in the module, next to the function they test, as Testing it explains.
11.4.5 The catalog
Unchanged from section 11.2: the record, and the lookup. find takes the catalog, the list of products, as a parameter, so the app and each example pass the catalog they need, and the module keeps no product list of its own.
module store.catalog
import store.money (Cents)
--- A product the store sells.
pub kind Product
sku: Text
name: Text
cents: Cents
--- The product with a SKU in a catalog, or `None` for a SKU the catalog does not list.
pub find(catalog: List[Product], sku: Text) -> Option[Product] = catalog.first_where(keep: fn(product) -> product.sku == sku)11.4.6 Pricing
Two public functions and one private helper:
module store.pricing
import store.money (Cents)
--- The price of `quantity` units at `cents` each.
pub line_cents(cents: Cents, quantity: Int) -> Int = cents * quantity
--- What a member pays: 10 percent off, rounded in the store's favor.
pub member_price(cents: Cents) -> Int
ensures result >= 0 and result <= cents
=
cents - discount(cents)
--- The members' discount, rounded down to a whole cent.
discount(cents: Cents) -> Int
ensures result >= 0 and result <= cents
=
cents / 10
example "members pay 10 percent less"
do member_price(24900)
expect result == 22410
example "the discount rounds down"
do discount(1999)
expect result == 199line_cents returns a plain Int, not a Cents. quantity is any Int, so a line of -1 units gives a negative total, and a Cents result is refuted (U5001, with quantity = -1). Even with a quantity of 0 or more, the verifier leaves the product of two values uninterpreted, so it could not prove the result is 0 or more (U5002). format takes any Int for that reason.
member_price promises that a member never pays more than the price, nor less than 0. The verifier proves that promise from discount's header, not from its body, so discount states its own bounds in ensures. Both take a Cents, so neither can be called with a negative price. discount stays private: the invoice shows what a member pays, not how the discount is computed. Exercise 2 changes that decision on purpose.
11.4.7 The invoice
It imports from three modules, and is the only module that knows how an invoice line reads:
module store.invoice
import store.catalog (Product, find)
import store.money (format)
import store.pricing (line_cents, member_price)
--- Why a line could not be invoiced.
pub kind InvoiceError = | UnknownSku(sku: Text)
--- One line of an order: a SKU and how many units of it.
pub kind OrderLine
sku: Text
quantity: Int
--- The product an order line names, looked up in a catalog.
pub product_of(line: OrderLine, catalog: List[Product]) -> Product
fails InvoiceError
=
find(catalog, sku: line.sku)
if none fail UnknownSku(sku: line.sku)
--- One line of the invoice, as text, with the members' price of one unit.
pub describe(line: OrderLine, product: Product) -> Text
=
let total = line_cents(product.cents, quantity: line.quantity)
let member = member_price(product.cents)
"{line.quantity} x {product.name} at {format(product.cents)} (members {format(member)}): {format(total)}"product_of looks the line's SKU up in the catalog it is given, with find, and turns a missing product into its own failure, UnknownSku, with the SKU. Its header writes its fails, since it is pub. describe needs no catalog at all: it takes the product that product_of found, so a test can call it with any product. It uses three imported functions, line_cents, member_price and format, and the import lines at the top of the file name each of them, so a reader knows where to look for each one.
11.4.8 The app
It holds the catalog and the order, both as lists, and runs the order against the catalog. attempt keeps each lookup's outcome, so an unknown SKU becomes a line of the invoice instead of stopping it:
module store.app
import store.catalog (Product)
import store.invoice (OrderLine, describe, product_of)
--- Prints the invoice of one order.
pub main() -> Unit
uses @console: Console[print]
=
let catalog = [Product(sku: "LAMP-01", name: "Desk lamp", cents: 1990), Product(sku: "DESK-02", name: "Oak desk", cents: 24900)]
let order = [OrderLine(sku: "LAMP-01", quantity: 2), OrderLine(sku: "DESK-02", quantity: 1), OrderLine(sku: "CHAIR-09", quantity: 1)]
for line in order
let found = attempt product_of(line, catalog)
when found
is Ok(product) -> @console.print(describe(line, product))
is Err -> @console.print("{line.sku}: not in the catalog")store.app imports product_of and describe, but not InvoiceError. It never writes that type's name, and is Err matches any failure. A module imports a kind when it writes the kind, in a parameter's type for example, or builds one of its variants.
main passes the same catalog to every lookup: product_of(line, catalog) names its second argument by a name equal to the parameter's, so it needs no label (section 6.1), and so does describe(line, product). Only app decides which products the program knows. In a real store the catalog would come from a service outside the program; chapter 12 shows how a function declares that it uses one.
11.4.9 Running it
The whole package checks, runs and passes its tests. una run . prints the invoice shown in What you'll build: two lines for the products the catalog lists, with their members' prices, and one for the chair it does not.
Next:11.5 Testing it