18.6 Day-to-day: price tags for a sale
Page 7 of 11
18.6.1 What the program must do
Now the program from the start of the chapter, and the checks it goes through before a release. The store runs a sale of 30 percent. Each shelf gets a tag with the price and the sale price, which a requirement says must never be below what the store paid. The prices come from the store's catalog, a capability, so the tags can be tested with a catalog held in memory. The program uses what earlier chapters taught; this chapter's part is what comes after the code is written: the commands that show it is right, what it may do, and what it promises.
18.6.2 The requirement and the kinds
The requirement records the rule in words, so that una trace can follow it to the code. Cents and Percent are refined kinds (chapter 5), so a negative price or a discount of 95 percent cannot reach the functions of The price and The tag. Product is a record, and Catalog is the store's own capability with one operation, which una report . lists under assumptions.
module pricetags
requirement PRICING_1
text "A sale price is never below what the store paid for the product"
source human
owner pricing
status active
--- An amount of money in cents, never negative.
pub kind Cents = Int where it >= 0
--- A discount in percent, from 0 to 90.
pub kind Percent = Int in 0..90
--- A product on the shelf: its SKU, its price and what the store paid for it.
pub kind Product
sku: Text
price: Cents
cost: Cents
--- The store's catalog: the product with a SKU, or `None` for a SKU it does not list.
pub capability Catalog
op product(sku: Text) -> Option[Product]
18.6.3 The price
sale_price promises result >= product.cost and names the requirement it is derived from. The verifier proves the promise on both paths of the if, which gives the postcondition obligation that una trace PRICING_1 shows at the end of this section.
--- The price after `off` percent, never below cost.
pub sale_price(product: Product, off: Percent) -> Cents
ensures result >= product.cost
derived from PRICING_1
=
let discounted = product.price - product.price * off / 100
if discounted < product.cost then product.cost else discounted18.6.4 The tag
shown writes cents as a person reads them, with mod for the remainder. tag asks the catalog, the only thing it may do, as its uses clause says, and handles a SKU the catalog does not list.
--- Cents as a person reads them, such as 19.90.
pub shown(amount: Cents) -> Text
=
let cents = amount mod 100
let pad = if cents < 10 then "0" else ""
"{amount / 100}.{pad}{cents}"
--- The tag printed on the shelf for `sku` during a sale of `off` percent.
pub tag(sku: Text, off: Percent) -> Text
uses @catalog: Catalog[product]
=
let found = @catalog.product(sku)
when found
is Some(product) -> "{sku} {shown(product.price)} now {shown(sale_price(product, off: off))}"
is None -> "{sku} not in the catalog"when found takes the catalog's answer apart. With Some(product), the tag shows the price and the sale price, each through shown. With None, it says that the catalog does not list the SKU. Both arms give a Text, and tag cannot fail: a missing product is an ordinary answer of the catalog, not a failure.
18.6.5 Running it
listed is a catalog held in a map, and main installs it for each tag with with:
--- A catalog held in memory, for this run and for tests.
handler listed(products: Map[Text, Product]) for Catalog
op product(sku) = products.get(key: sku)
--- The products of this example run.
sample() -> Map[Text, Product]
=
let lamp = Product(sku: "LAMP-01", price: 1990, cost: 1200)
let desk = Product(sku: "DESK-02", price: 12900, cost: 11000)
empty_map().with(key: lamp.sku, value: lamp).with(key: desk.sku, value: desk)
pub main() -> Unit
uses @console: Console[print]
=
for sku in ["LAMP-01", "DESK-02", "CHAIR-09"]
let line = tag(sku, off: 30) with @catalog = listed(sample())
@console.print(line)sample holds the two products of this run. In production, the handler would read the store's database, and nothing else of the program would change: tag knows only the capability.
una run . prints the tags shown in What you'll build. The lamp loses 30 percent, from 19.90 to 13.93. The desk would fall to 90.30, below its cost of 110.00, so its sale price stops at cost. The chair is not in the catalog.
18.6.6 The whole program
The whole file:
module pricetags
requirement PRICING_1
text "A sale price is never below what the store paid for the product"
source human
owner pricing
status active
--- An amount of money in cents, never negative.
pub kind Cents = Int where it >= 0
--- A discount in percent, from 0 to 90.
pub kind Percent = Int in 0..90
--- A product on the shelf: its SKU, its price and what the store paid for it.
pub kind Product
sku: Text
price: Cents
cost: Cents
--- The store's catalog: the product with a SKU, or `None` for a SKU it does not list.
pub capability Catalog
op product(sku: Text) -> Option[Product]
--- The price after `off` percent, never below cost.
pub sale_price(product: Product, off: Percent) -> Cents
ensures result >= product.cost
derived from PRICING_1
=
let discounted = product.price - product.price * off / 100
if discounted < product.cost then product.cost else discounted
--- Cents as a person reads them, such as 19.90.
pub shown(amount: Cents) -> Text
=
let cents = amount mod 100
let pad = if cents < 10 then "0" else ""
"{amount / 100}.{pad}{cents}"
--- The tag printed on the shelf for `sku` during a sale of `off` percent.
pub tag(sku: Text, off: Percent) -> Text
uses @catalog: Catalog[product]
=
let found = @catalog.product(sku)
when found
is Some(product) -> "{sku} {shown(product.price)} now {shown(sale_price(product, off: off))}"
is None -> "{sku} not in the catalog"
--- A catalog held in memory, for this run and for tests.
handler listed(products: Map[Text, Product]) for Catalog
op product(sku) = products.get(key: sku)
--- The products of this example run.
sample() -> Map[Text, Product]
=
let lamp = Product(sku: "LAMP-01", price: 1990, cost: 1200)
let desk = Product(sku: "DESK-02", price: 12900, cost: 11000)
empty_map().with(key: lamp.sku, value: lamp).with(key: desk.sku, value: desk)
pub main() -> Unit
uses @console: Console[print]
=
for sku in ["LAMP-01", "DESK-02", "CHAIR-09"]
let line = tag(sku, off: 30) with @catalog = listed(sample())
@console.print(line)
example "a sale takes the percent off the price"
do sale_price(Product(sku: "LAMP-01", price: 1990, cost: 1200), off: 30)
expect result == 1393
example "a sale price stops at cost"
do sale_price(Product(sku: "DESK-02", price: 12900, cost: 11000), off: 30)
expect result == 11000
example "cents are shown with two digits"
do shown(1905)
expect result == "19.05"
example "a SKU the catalog does not list gets no price"
given @catalog = listed(sample())
do tag("CHAIR-09", off: 30)
expect result == "CHAIR-09 not in the catalog"18.6.7 The checks before a release
Before the tags go to the printer, run the commands of this chapter, in this order:
una fmt --check .
una check .
una test .
una trace PRICING_1
una report .
una build .Each command answers one question, and each would stop the release for its own reason:
| Command | Section | It stops the release when… |
|---|---|---|
una fmt --check . |
18.1 | A file is not in canonical form (U7001) |
una check . |
18.1 | A name, a type, a capability, a security label or a proof is wrong |
una test . |
18.5 | An example fails: a number is not the one a person expects |
una trace PRICING_1 |
18.3 | An obligation derived from the requirement is not proven |
una report . |
18.4 | An obligation is not proven; and a reviewer reads what changed |
una build . |
18.5 | The executable cannot be built, for example on Linux without cc |
una fmt --check . and una check . print nothing: the package is canonical and proven. una trace PRICING_1 shows that the requirement reaches sale_price and that both of its obligations are proven:
$ una trace PRICING_1
requirement PRICING_1 (active)
text "A sale price is never below what the store paid for the product"
source human
owner pricing
pricetags.sale_price
ensures result >= product.cost
proven ob-7c59f0c13fa3 refinement result >= 0
proven ob-a498f6efa270 postcondition result >= product.costThe first obligation is the result of sale_price, a Cents; the second is the promise. una report . shows what the package may do. Its authority section has two lines, main may print and tag may ask the catalog, and assumptions lists the operation of Catalog that the proofs take on trust:
authority:
pricetags.main (pub): @console: Console[print]
pricetags.tag (pub): @catalog: Catalog[product]
assumptions:
pricetags.Catalog: productuna contract shows the same for one function, which is what a reviewer of tag checks:
$ una contract pricetags.tag
--- The tag printed on the shelf for `sku` during a sale of `off` percent.
pub tag(sku: Text, off: Percent) -> Text
uses @catalog: Catalog[product]Finally, una build . writes the executable that the store runs:
$ una build .
built target/una/pricetagsEvery one of these commands exits with code 0 on this package, so a release script can run them in turn and stop at the first that does not. The order goes from the cheapest question to the most expensive one: formatting needs no types, the checks need no run, and the examples need a package that checks. A continuous integration service, which runs such a script on every proposed change, can add --json to each command and keep the documents, so that the report of every release can be compared with the one before it.
Next:18.7 Testing it