Home / Learn / 18 Tools

Release v0.4.0Edition 0.2

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.

day-to-day/src/pricetags.unathe requirement, the kinds and the cataloguna
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.

day-to-day/src/pricetags.unauna
--- 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

18.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.

day-to-day/src/pricetags.unauna
--- 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:

day-to-day/src/pricetags.unauna
--- 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:

day-to-day/src/pricetags.unathe whole programcheckruntestuna
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:

sh
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:

Terminal
$ 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.cost

The 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:

Output
authority:
  pricetags.main (pub): @console: Console[print]
  pricetags.tag (pub): @catalog: Catalog[product]
assumptions:
  pricetags.Catalog: product

una contract shows the same for one function, which is what a reviewer of tag checks:

Terminal
$ 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:

Terminal
$ una build .
built target/una/pricetags

Every 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