Home / Learn / 8 Choosing
8.5 Day-to-day: shipment tracking
Page 6 of 10
8.5.1 What the program must do
The store ships parcels by post or by courier. Each parcel has a price for its zone and its weight. Carriers report events: a pickup, a delivery, a parcel that came back. The tracker keeps each shipment's history of events, works out its status from that history, ignores an event that does not fit, such as a pickup scan sent twice, and says how much of a returned parcel's price the store pays back.
The program uses every part of the chapter: when with one arm per variant and with range arms, if inside arms, a guard that keeps a refund from going below 0, and a recursive kind for the history. Its package is one module, tracking, the entry of its una.toml, which grants the console.
8.5.2 The kinds
The design starts from the kinds. Everything a function does follows from them.
--- How far a parcel travels.
pub kind Zone = Local | National | Abroad
--- A parcel ready to ship. `order` is the number on the customer's receipt.
pub kind Parcel
order: Text
grams: Int
zone: Zone
--- An amount of money in cents. It is never negative.
pub kind Cents = Int where it >= 0
--- Who carries a parcel.
pub kind Carrier = Post | Courier
--- Why a parcel came back.
pub kind ReturnReason = Damaged | WrongItem | Refused
--- Where a shipment is. Each state carries what is known in that state, and nothing else.
pub kind Status = Packed | InTransit(carrier: Carrier, tracking: Text) | Delivered(day: Int) | Returned(reason: ReturnReason, day: Int)
--- What a carrier or the warehouse reports about a shipment.
pub kind Event = PickedUp(carrier: Carrier, tracking: Text) | DeliveredOn(day: Int) | CameBack(reason: ReturnReason, day: Int)
--- Every event of a shipment, the latest first. `Start` is the history before any event.
pub kind History = Start | After(event: Event, earlier: History)
--- A value before and after something happened.
pub kind Change[T]
before: T
after: TRead them in order:
Zone,CarrierandReturnReasonare sums without fields: fixed lists of names.Parcelis a record of three fields, one of which is aZone.Centsis the refined kind of section 5.3, for amounts that are never negative.Statusis the heart of the program. Each variant carries what is known in that state: nothing while packed, a carrier and a tracking number while in transit, a day once delivered, a reason and a day once returned. A delivered status without a day cannot be written.Eventis what the outside world reports, and its variants mirror the transitions.Historyis a recursive kind.Startis a history with no event yet.After(event, earlier)is the historyearlierwith one more event, the latest. So the latest event is on the outside, andStartis at the bottom, where every history ends.Change[T]is a generic record of section 4.4: a value before and after something happened.
8.5.3 Pricing a parcel
postage adds the price of the zone to the supplement for the weight. Each part is a when: one arm per zone, and weight bands with range arms and an else, as in section 8.2.
--- Postage in cents: a price for the zone, and a supplement for the weight.
pub postage(parcel: Parcel) -> Int = zone_cents(parcel.zone) + weight_cents(parcel.grams)
zone_cents(zone: Zone) -> Int
=
when zone
is Local -> 300
is National -> 450
is Abroad -> 1200
weight_cents(grams: Int) -> Int
=
when grams
in 0..500 -> 0
in 501..2000 -> 150
else -> 400zone_cents has no else, so a new zone stops the program from checking until it has a price. weight_cents has an else, since weights never run out: it is what makes the bands cover every Int, negative weights included.
8.5.4 Following a history
apply takes a status and an event, and gives the next status: one when over the event, and in each arm an if that tests the status with is. An event that does not fit the current status leaves it as it is, so a second pickup scan, or a return before any delivery, changes nothing.
--- The status after an event. An event that does not fit the status changes nothing, such
--- as a pickup scan that a carrier sends twice.
pub apply(status: Status, event: Event) -> Status
=
when event
is PickedUp(carrier, tracking) -> if status is Packed then InTransit(carrier, tracking) else status
is DeliveredOn(day) -> if status is InTransit then Delivered(day) else status
is CameBack(reason, day) -> if status is Delivered then Returned(reason, day) else status
--- The status a history leads to: every event applied, the oldest first.
pub status_of(history: History) -> Status
=
when history
is Start -> Packed
is After(event, earlier) -> apply(status_of(earlier), event)
--- What the latest event of a history did: the status before it, and after it.
pub latest(history: History) -> Change[Status]
=
when history
is Start -> Change(before: Packed, after: Packed)
is After(event, earlier) ->
let before = status_of(earlier)
Change(before, after: apply(before, event))
--- Whether something changed. Any type whose values can be compared will do.
pub changed[T: Eq](change: Change[T]) -> Bool = change.before != change.afterstatus_ofis recursive, as the functions of section 8.4 are. A history with no event isPacked. A history with one more event is the status of the earlier history, with the event applied. So the oldest event is applied first.latestsays what the latest event did. Its second arm has several lines: it names the status before the event, then builds theChange.Change(before, after: …)passesbeforewithout a label, since a name equal to the field's name counts as its label (section 6.1).changedcompares the two statuses with!=, which needs theEqconstraint of section 4.4.
Why ignore an event that does not fit, rather than fail? Carriers resend scans, and a report that arrives late is still a report. The tracker keeps the status it trusts, and the Change shows that nothing happened. A function that must stop the work instead would declare a failure, as chapter 7 shows.
8.5.5 Words for people, and the refund
describe has one arm per status and binds the fields it prints. carrier_name and reason_text turn variants without fields into words. None of them has an else, so a new carrier, reason or status is reported at the when that must say something about it.
--- A status, for a person to read.
pub describe(status: Status) -> Text
=
when status
is Packed -> "packed, waiting for a carrier"
is InTransit(carrier, tracking) -> "with {carrier_name(carrier)}, tracking {tracking}"
is Delivered(day) -> "delivered on day {day}"
is Returned(reason, day) -> "returned on day {day}, {reason_text(reason)}"
carrier_name(carrier: Carrier) -> Text
=
when carrier
is Post -> "the post"
is Courier -> "the courier"
reason_text(reason: ReturnReason) -> Text
=
when reason
is Damaged -> "damaged"
is WrongItem -> "the wrong item"
is Refused -> "refused at the door"
--- What the store pays back for a shipment: all of `paid` for a parcel that came back by the
--- store's fault, `paid` less 600 cents of return postage for a refused one, and nothing
--- otherwise. The guard keeps the refund from going below 0.
pub refund(status: Status, paid: Cents) -> Cents
=
when status
is Returned(reason) ->
if reason == Refused
if paid > 600 then paid - 600 else 0
else
paid
else -> 0refund is the other kind of function: one case matters, and else covers the rest. Inside the Returned arm, an if asks about the reason. A parcel refused at the door is refunded less the 600 cents of return postage, and the inner if paid > 600 then paid - 600 else 0 is a guard of section 8.3: in its then branch, the verifier knows paid > 600, so paid - 600 is at least 1, and the result is a Cents. Without the guard, a refused parcel of 400 cents would be owed -200.
8.5.6 Running it
report turns the latest event of a history into a line of text. main prices a lamp, then builds its history one event at a time: a pickup, the same pickup again, and a delivery. Then it prices a vase sent abroad, which was delivered and then refused.
--- One line of the tracking report.
pub report(order: Text, history: History) -> Text
=
let change = latest(history)
if changed(change)
"{order}: {describe(change.after)}"
else
"{order}: no change, still {describe(change.after)}"
pub main() -> Unit
uses @console: Console[print]
=
let lamp = Parcel(order: "A-1001", grams: 1200, zone: National)
@console.print("{lamp.order}: postage {postage(lamp)}")
let picked = After(event: PickedUp(carrier: Courier, tracking: "CX-4471"), earlier: Start)
@console.print(report(lamp.order, history: picked))
let again = After(event: PickedUp(carrier: Courier, tracking: "CX-4471"), earlier: picked)
@console.print(report(lamp.order, history: again))
let arrived = After(event: DeliveredOn(day: 3), earlier: again)
@console.print(report(lamp.order, history: arrived))
let vase = Parcel(order: "A-1002", grams: 300, zone: Abroad)
@console.print("{vase.order}: postage {postage(vase)}")
let sent = After(event: DeliveredOn(day: 8), earlier: After(event: PickedUp(carrier: Post, tracking: "PO-2210"), earlier: Start))
let back = After(event: CameBack(reason: Refused, day: 12), earlier: sent)
@console.print("{report(vase.order, history: back)}; refund {refund(status_of(back), paid: 4500)}")Each history is built on the one before it: again is picked with one more event, and arrived is again with one more. una run . prints the report shown in What you'll build. The third line is the duplicate scan: the status stayed InTransit, and the report says so instead of pretending something happened. The vase paid 4500 cents and was refused, so the store pays back 4500 - 600 = 3900.
8.5.7 The whole program
The whole file, to read in one piece or to copy:
module tracking
--- How far a parcel travels.
pub kind Zone = Local | National | Abroad
--- A parcel ready to ship. `order` is the number on the customer's receipt.
pub kind Parcel
order: Text
grams: Int
zone: Zone
--- An amount of money in cents. It is never negative.
pub kind Cents = Int where it >= 0
--- Who carries a parcel.
pub kind Carrier = Post | Courier
--- Why a parcel came back.
pub kind ReturnReason = Damaged | WrongItem | Refused
--- Where a shipment is. Each state carries what is known in that state, and nothing else.
pub kind Status = Packed | InTransit(carrier: Carrier, tracking: Text) | Delivered(day: Int) | Returned(reason: ReturnReason, day: Int)
--- What a carrier or the warehouse reports about a shipment.
pub kind Event = PickedUp(carrier: Carrier, tracking: Text) | DeliveredOn(day: Int) | CameBack(reason: ReturnReason, day: Int)
--- Every event of a shipment, the latest first. `Start` is the history before any event.
pub kind History = Start | After(event: Event, earlier: History)
--- A value before and after something happened.
pub kind Change[T]
before: T
after: T
--- Postage in cents: a price for the zone, and a supplement for the weight.
pub postage(parcel: Parcel) -> Int = zone_cents(parcel.zone) + weight_cents(parcel.grams)
zone_cents(zone: Zone) -> Int
=
when zone
is Local -> 300
is National -> 450
is Abroad -> 1200
weight_cents(grams: Int) -> Int
=
when grams
in 0..500 -> 0
in 501..2000 -> 150
else -> 400
--- The status after an event. An event that does not fit the status changes nothing, such
--- as a pickup scan that a carrier sends twice.
pub apply(status: Status, event: Event) -> Status
=
when event
is PickedUp(carrier, tracking) -> if status is Packed then InTransit(carrier, tracking) else status
is DeliveredOn(day) -> if status is InTransit then Delivered(day) else status
is CameBack(reason, day) -> if status is Delivered then Returned(reason, day) else status
--- The status a history leads to: every event applied, the oldest first.
pub status_of(history: History) -> Status
=
when history
is Start -> Packed
is After(event, earlier) -> apply(status_of(earlier), event)
--- What the latest event of a history did: the status before it, and after it.
pub latest(history: History) -> Change[Status]
=
when history
is Start -> Change(before: Packed, after: Packed)
is After(event, earlier) ->
let before = status_of(earlier)
Change(before, after: apply(before, event))
--- Whether something changed. Any type whose values can be compared will do.
pub changed[T: Eq](change: Change[T]) -> Bool = change.before != change.after
--- A status, for a person to read.
pub describe(status: Status) -> Text
=
when status
is Packed -> "packed, waiting for a carrier"
is InTransit(carrier, tracking) -> "with {carrier_name(carrier)}, tracking {tracking}"
is Delivered(day) -> "delivered on day {day}"
is Returned(reason, day) -> "returned on day {day}, {reason_text(reason)}"
carrier_name(carrier: Carrier) -> Text
=
when carrier
is Post -> "the post"
is Courier -> "the courier"
reason_text(reason: ReturnReason) -> Text
=
when reason
is Damaged -> "damaged"
is WrongItem -> "the wrong item"
is Refused -> "refused at the door"
--- What the store pays back for a shipment: all of `paid` for a parcel that came back by the
--- store's fault, `paid` less 600 cents of return postage for a refused one, and nothing
--- otherwise. The guard keeps the refund from going below 0.
pub refund(status: Status, paid: Cents) -> Cents
=
when status
is Returned(reason) ->
if reason == Refused
if paid > 600 then paid - 600 else 0
else
paid
else -> 0
--- One line of the tracking report.
pub report(order: Text, history: History) -> Text
=
let change = latest(history)
if changed(change)
"{order}: {describe(change.after)}"
else
"{order}: no change, still {describe(change.after)}"
pub main() -> Unit
uses @console: Console[print]
=
let lamp = Parcel(order: "A-1001", grams: 1200, zone: National)
@console.print("{lamp.order}: postage {postage(lamp)}")
let picked = After(event: PickedUp(carrier: Courier, tracking: "CX-4471"), earlier: Start)
@console.print(report(lamp.order, history: picked))
let again = After(event: PickedUp(carrier: Courier, tracking: "CX-4471"), earlier: picked)
@console.print(report(lamp.order, history: again))
let arrived = After(event: DeliveredOn(day: 3), earlier: again)
@console.print(report(lamp.order, history: arrived))
let vase = Parcel(order: "A-1002", grams: 300, zone: Abroad)
@console.print("{vase.order}: postage {postage(vase)}")
let sent = After(event: DeliveredOn(day: 8), earlier: After(event: PickedUp(carrier: Post, tracking: "PO-2210"), earlier: Start))
let back = After(event: CameBack(reason: Refused, day: 12), earlier: sent)
@console.print("{report(vase.order, history: back)}; refund {refund(status_of(back), paid: 4500)}")
example "a heavy parcel abroad pays the zone and the weight"
do postage(Parcel(order: "A-1003", grams: 2500, zone: Abroad))
expect result == 1600
example "a second pickup scan changes nothing"
do latest(After(event: PickedUp(carrier: Post, tracking: "PO-1"), earlier: After(event: PickedUp(carrier: Post, tracking: "PO-1"), earlier: Start)))
expect not changed(result)
example "a parcel cannot come back before it was delivered"
do status_of(After(event: CameBack(reason: Damaged, day: 2), earlier: Start))
expect result is Packed
example "a damaged parcel is refunded in full"
do refund(Returned(reason: Damaged, day: 5), paid: 4500)
expect result == 4500
example "a refused parcel is refunded less the return postage"
do refund(Returned(reason: Refused, day: 5), paid: 601)
expect result == 1
example "a refund never goes below 0"
do refund(Returned(reason: Refused, day: 5), paid: 400)
expect result == 0
example "a delivered parcel is not refunded"
do refund(Delivered(day: 3), paid: 4500)
expect result == 0Next:8.6 Testing it