Home / Learn / 13 Limits on authority

Release v0.4.0Edition 0.2, 0.3

13.4 Day-to-day: a price sale

Page 5 of 9

13.4.1 What the sale must do

Twice a year the store runs a sale: a percentage off every product on a list. Before the prices change, the staff want a rehearsal: a dry run that prints each old and new price, and the total taken off, and changes nothing. Then the sale runs for real: it sets each new price in the price list, and prints a shelf tag for each product.

Three rules must hold, and each one gets a rule of this chapter:

The package has three modules: vendor.tags, the tag printer's code; store.sale, the sale itself; and store.app, which runs it.

13.4.2 The manifest: a lock and a boundary

day-to-day/una.tomltoml
[package]
name = "store"
version = "0.1.0"
edition = "0.3"

[run]
entry = "store.app"
grants = ["console"]

# What the sale may do with the price list, and when.
[contracts]
"store.sale.apply_sale" = ["@prices: PriceList[set_price where not dry_run]"]
"store.sale.run_sale" = ["@prices: PriceList[set_price where not dry_run]", "@console: Console[print]"]

# Code from the maker of the tag printer: the most the store may ever grant it.
[boundaries]
"vendor.tags" = ["Console[print]"]

13.4.3 The tag printer, a vendored module

day-to-day/src/vendor/tags.unacheckuna
module vendor.tags

--- Prints a price tag for a shelf. This module comes from the maker of the tag printer, and
--- `una.toml` lists it as a boundary.
pub print_tag(name: Text, cents: Int) -> Unit
  uses @console: Console[print]
=
  @console.print("  tag: [{name} | {cents} cents]")

The module is ordinary Una, and knows nothing of the boundary: its header asks for the console, as any public function that prints does. The boundary is the store's decision, in the store's una.toml.

13.4.4 The price of one item

store.sale starts with its kinds and its capability:

day-to-day/src/store/sale.unathe kinds, the capability and the price ruleuna
--- A discount in whole percent, from 0 to 100.
pub kind Percent = Int in 0..100

--- A product in the sale: its SKU, its name, and its price before the sale, in cents.
pub kind Item
  sku: Text
  name: Text
  cents: Int

--- The store's price list, where the tills read each price.
pub capability PriceList
  op set_price(sku: Text, cents: Int) -> Unit

--- The price `cents` with `percent` taken off. The discount is rounded down to whole cents.
pub sale_price(cents: Int, percent: Percent) -> Int = cents - cents * percent / 100

apply_sale prices one item:

day-to-day/src/store/sale.unacheckuna
--- Takes `percent` off the price of one item, and gives back its sale price. A dry run changes
--- no price.
pub apply_sale(item: Item, percent: Percent, dry_run: Bool) -> Int
  uses @prices: PriceList[set_price where not dry_run]
=
  let sale = sale_price(item.cents, percent)
  if not dry_run
    @prices.set_price(item.sku, cents: sale)
  sale

Its header allows set_price only where not dry_run holds, and its body guards the operation with the same test. It gives back the sale price in both cases, so a dry run can report what it would set.

13.4.5 Running the sale over every item

day-to-day/src/store/sale.unathe line of a dry run, and the whole saleuna
--- The line a dry run prints for one item.
pub planned_line(item: Item, sale: Int) -> Text = "  {item.sku} would go from {item.cents} to {sale}"

--- Runs the sale over every item, and gives back the cents taken off in all. A dry run prints
--- what it would do, and changes no price; a real run sets each price and prints its tag.
pub run_sale(items: List[Item], percent: Percent, dry_run: Bool) -> Int
  uses @prices: PriceList[set_price where not dry_run]
  uses @console: Console[print]
=
  let edit saved = 0
  for item in items
    let sale = apply_sale(item, percent, dry_run)
    saved = saved + item.cents - sale
    if dry_run
      @console.print(planned_line(item, sale))
    else
      print_tag(item.name, cents: sale) with @console = @console
  saved

run_sale walks the list with for, and keeps the total taken off in saved, a name that changes with let edit (chapter 9). Two calls in its loop are checked by this chapter's rules:

13.4.6 The app: a dry run, then the sale

day-to-day/src/store/app.unacheckrununa
module store.app

import store.sale (Item, PriceList, run_sale)

--- A price list that prints each change instead of storing it.
handler printed() for PriceList
  uses @console: Console[print]
  op set_price(sku, cents) = @console.print("  set {sku} to {cents}")

--- The products of the spring sale.
spring_items() -> List[Item]
=
  let lamp = Item(sku: "LAMP-01", name: "Desk lamp", cents: 1990)
  let desk = Item(sku: "DESK-02", name: "Oak desk", cents: 24900)
  let rug = Item(sku: "RUG-07", name: "Wool rug", cents: 4500)
  [lamp, desk, rug]

--- Rehearses the spring sale, then runs it.
pub main() -> Unit
  uses @console: Console[print]
=
  let items = spring_items()
  @console.print("Dry run: 20 percent off")
  let planned = run_sale(items, percent: 20, dry_run: true) with @prices = printed()
  @console.print("The dry run plans {planned} cents off")
  @console.print("Sale: 20 percent off")
  let saved = run_sale(items, percent: 20, dry_run: false) with @prices = printed()
  @console.print("The sale took {saved} cents off")

The handler printed stands in for the price list: it prints each change instead of storing it, so the output shows exactly when set_price runs. main calls run_sale twice on the same items: first with dry_run: true, then with dry_run: false.

13.4.7 Running it

In the day-to-day directory:

sh
una check .
una run .
Output
Dry run: 20 percent off
  LAMP-01 would go from 1990 to 1592
  DESK-02 would go from 24900 to 19920
  RUG-07 would go from 4500 to 3600
The dry run plans 6278 cents off
Sale: 20 percent off
  set LAMP-01 to 1592
  tag: [Desk lamp | 1592 cents]
  set DESK-02 to 19920
  tag: [Oak desk | 19920 cents]
  set RUG-07 to 3600
  tag: [Wool rug | 3600 cents]
The sale took 6278 cents off

The dry run prints three planned lines and no set line: set_price never ran. The sale prints a set line from the price list and a tag from the vendored module for each item. Both runs take off the same total, 6278 cents.

13.4.8 The whole program

The sale module, with its tests, in one piece:

day-to-day/src/store/sale.unathe whole sale modulechecktestuna
module store.sale

import vendor.tags (print_tag)

--- A discount in whole percent, from 0 to 100.
pub kind Percent = Int in 0..100

--- A product in the sale: its SKU, its name, and its price before the sale, in cents.
pub kind Item
  sku: Text
  name: Text
  cents: Int

--- The store's price list, where the tills read each price.
pub capability PriceList
  op set_price(sku: Text, cents: Int) -> Unit

--- The price `cents` with `percent` taken off. The discount is rounded down to whole cents.
pub sale_price(cents: Int, percent: Percent) -> Int = cents - cents * percent / 100

--- Takes `percent` off the price of one item, and gives back its sale price. A dry run changes
--- no price.
pub apply_sale(item: Item, percent: Percent, dry_run: Bool) -> Int
  uses @prices: PriceList[set_price where not dry_run]
=
  let sale = sale_price(item.cents, percent)
  if not dry_run
    @prices.set_price(item.sku, cents: sale)
  sale

--- The line a dry run prints for one item.
pub planned_line(item: Item, sale: Int) -> Text = "  {item.sku} would go from {item.cents} to {sale}"

--- Runs the sale over every item, and gives back the cents taken off in all. A dry run prints
--- what it would do, and changes no price; a real run sets each price and prints its tag.
pub run_sale(items: List[Item], percent: Percent, dry_run: Bool) -> Int
  uses @prices: PriceList[set_price where not dry_run]
  uses @console: Console[print]
=
  let edit saved = 0
  for item in items
    let sale = apply_sale(item, percent, dry_run)
    saved = saved + item.cents - sale
    if dry_run
      @console.print(planned_line(item, sale))
    else
      print_tag(item.name, cents: sale) with @console = @console
  saved

--- A price list that keeps nothing, for the tests.
handler ignored() for PriceList
  op set_price(sku, cents) = unit

test "20 percent off a desk lamp"
  do sale_price(1990, percent: 20)
  expect result == 1592

test "0 percent off keeps the price"
  do sale_price(4500, percent: 0)
  expect result == 4500

test "100 percent off gives the item away"
  do sale_price(4500, percent: 100)
  expect result == 0

test "a discount that is not whole cents is rounded down"
  do sale_price(999, percent: 15)
  expect result == 850

test "a dry run gives the sale price"
  given @prices = ignored()
  do apply_sale(Item(sku: "LAMP-01", name: "Desk lamp", cents: 1990), percent: 20, dry_run: true)
  expect result == 1592

test "a real run gives the same sale price"
  given @prices = ignored()
  do apply_sale(Item(sku: "LAMP-01", name: "Desk lamp", cents: 1990), percent: 20, dry_run: false)
  expect result == 1592

test "the line of a dry run names the old and the new price"
  do planned_line(Item(sku: "RUG-07", name: "Wool rug", cents: 4500), sale: 3600)
  expect result == "  RUG-07 would go from 4500 to 3600"

Next:13.5 Testing it