---
title: "pantry"
url: https://una-lang.org/en/docs/examples/pantry/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/examples/pantry/README.md
---

# pantry

A kitchen pantry: items with amounts, a shopping list of what ran out, and totals per measure.

This example is about data and contracts, with no outside world beyond the console. It declares every form of `kind`, gives several functions a contract, and lets the solver prove that no amount goes below zero and that no division is by zero. Read it when you want to see how types and contracts replace the checks that other languages leave to tests.

What it demonstrates:

- [`kind`](https://una-lang.org/en/docs/language/types/kind/) declarations of every form: a choice, an alias, a record and a generic record;
- refinements with [`where`](https://una-lang.org/en/docs/language/types/where/): `Nat`, and a list that is never empty;
- contracts with [`requires`](https://una-lang.org/en/docs/language/functions/requires/) and [`ensures`](https://una-lang.org/en/docs/language/functions/ensures/);
- `Option` and an exhaustive [`when`](https://una-lang.org/en/docs/language/control-flow/when/);
- a generic function that takes a function value;
- seven [`example`](https://una-lang.org/en/docs/language/examples/example/) blocks.

## Run it

From this directory:

```sh
una check .   # copy examples/pantry
una test .
una run .
una build .
./target/una/pantry-example
```

`una run .` and the native executable print:

```text una="run ."
to buy: rice, oil
grams in stock: 700
```

The pantry holds no rice and no oil, so they are on the list. Rice (0 g) and flour (700 g) are the items measured in grams. `una test .` runs the seven examples of `src/pantry/stock.una`:

```text una="test ."
example pantry.stock "restocking adds to the amount" ... ok
example pantry.stock "using up takes from the amount" ... ok
example pantry.stock "the shopping list names what ran out" ... ok
example pantry.stock "totals count one measure only" ... ok
example pantry.stock "an item the pantry does not have amounts to zero" ... ok
example pantry.stock "a bin counts the entries that match" ... ok
example pantry.stock "the average of three counts is rounded down" ... ok

7 examples: 7 passed, 0 failed
```

## How it works

The package has two modules. `pantry.stock` holds the types and the functions, with their examples. `pantry.main` builds this morning's stock and prints the report. It may only print.

### The types

```text file="src/pantry/stock.una"
pub kind Measure = Grams | Pieces | Milliliters

...
pub kind Label = Text

pub kind Item
  name: Text
  amount: Nat
  measure: Measure

...
pub kind Bin[T]
  label: Label
  entries: List[T]

...
pub kind NonEmpty[T] = List[T] where it.len > 0
```

- `Measure` is a choice: a value is exactly one of the three variants.
- `Label` is an alias: another name for `Text`, which documents what the text means.
- `Item` is a record. Its `amount` is a `Nat`, an `Int` that is never negative. The solver checks that fact at every place that builds an `Item`.
- `Bin[T]` is a generic record: a labeled group of anything.
- `NonEmpty[T]` is a refinement: a `List[T]` with a fact that the solver must prove wherever a value of that type is made.

### Contracts that keep amounts honest

```text file="src/pantry/stock.una"
pub use_up(item: Item, used: Nat) -> Item
  requires used <= item.amount
  ensures result.amount == item.amount - used
=
  Item(name: item.name, amount: item.amount - used, measure: item.measure)
```

`item.amount - used` must be a `Nat`, since `amount` is one. The solver proves it from the `requires`: whoever calls `use_up` must show that there is enough. `restock` has the matching `ensures` for addition. `missing` and `shopping_list` promise a result no longer than their input (`ensures result.len <= items.len`), and `count_where` a count no larger than its bin (`ensures result <= bin.entries.len`). A caller can rely on these without reading the bodies.

### A division that cannot be by zero

```text file="src/pantry/stock.una"
pub average(counts: NonEmpty[Int]) -> Int = counts.sum() / counts.len
```

Every division carries an obligation: the divisor is not zero. The parameter type says the list has at least one entry, so the solver proves it here. The caller pays instead: the example `average([2, 4, 10])` must show that its list is not empty, and the solver proves that too.

### Absence and generics

`find` returns an `Option[Item]` from `first_where`, and `amount_of` matches on it:

```text file="src/pantry/stock.una"
pub amount_of(items: List[Item], name: Text) -> Nat
=
  when find(items, name)
    is Some(item) -> item.amount
    is None -> 0
```

`count_where[T]` works on a `Bin` of any type. It takes the test to apply as a function value, `keep: fn(T) -> Bool`, and passes it straight on to `filter`.

## What `una check` proves

`una obligations .` lists 27 obligations, all proven. Among them:

- each `ensures` above, for every input;
- every `Nat` stays at or above zero, including `item.amount - used`, which `use_up`'s `requires` makes safe;
- `average` never divides by zero;
- every call meets its callee's `requires`, such as the call to `use_up` in its example, `4 <= Item(name: "eggs", amount: 6, measure: Pieces).amount`.

The type checker adds the rest without the solver: every `when` on a choice covers all its variants, and every value has the type its place requires.

## Common mistakes

### Taking more than there is

Delete the `requires used <= item.amount` line of `use_up`. `una check .` reports that the new amount may be negative (its location and repairs shown; the notes after them are left out):

```text una="check ." after="mistakes/1"
[U5001] Error: refinement `(item.amount - used) >= 0` is refuted
    ╭─[ src/pantry/stock.una:32:33 ]
    │
 32 │   Item(name: item.name, amount: item.amount - used, measure: item.measure)
    │                                 ─────────┬────────
    │                                          ╰────────── refinement `(item.amount - used) >= 0` is refuted
    │
    │ Help 1: repair 1: add a guard (`if` or a `when` arm) that handles the values where `(item.amount - used) >= 0` does not hold
    │
    │ Help 2: repair 2 (escape: checked; a runtime test replaces the static proof: the program fails at run time where the proof would have rejected it; it counts against [escape_budget] and is listed in the build report): check the value with `checked(value, (item.amount - used) >= 0) else fail <Variant>`
...
```

The diagnostic points at `item.amount - used` on line 32. Its repairs are a guard, or a `checked` that tests the value at run time. Here the right fix is the `requires`: running out is the caller's decision, not something `use_up` can repair.

### Dividing by the length of any list

Change the parameter of `average` to `counts: List[Int]`. The solver finds the empty list:

```text una="check ." after="mistakes/2"
[U5001] Error: division obligation `counts.len != 0` is refuted
    ╭─[ src/pantry/stock.una:67:41 ]
    │
 67 │ pub average(counts: List[Int]) -> Int = counts.sum() / counts.len
    │                                         ────────────┬────────────
    │                                                     ╰────────────── division obligation `counts.len != 0` is refuted
    │
    │ Help: repair 1: guard the division with `if counts.len != 0`
    │
    │ Note 1: obligation ob-57d6a6e35832 (division) is refuted: counts.len != 0
    │
    │ Note 2: counterexample: counts = List#0, counts.len = 0
    │
    │ Note 3: run `una explain U5001` for an explanation
────╯
```

The repair offers a guard. The example prefers a type, `NonEmpty[Int]`, because it states the rule once, in the header, where every caller sees it.

### Forgetting a case

Delete the `is None -> 0` arm of `amount_of`:

```text una="check ." after="mistakes/3"
[U2007] Error: `when` does not match variant `None` of `Option`
    ╭─[ src/pantry/stock.una:56:3 ]
    │
 56 │   when find(items, name)
    │   ──┬─
    │     ╰─── `when` does not match variant `None` of `Option`
    │
    │ Help: repair 1: add an arm for each missing variant, such as `is None`, or an `else` arm
    │
    │ Note: run `una explain U2007` for an explanation
────╯
```

## Extend it

1. **Name the units.** Add `pub unit_name(measure: Measure) -> Text`, a `when` with one arm per measure (`"g"`, `"pcs"`, `"ml"`). Then add a variant, `Kilograms`, to `Measure`. `una check .` reports a U2007 at your `when`: the checker finds every match that the new case affects.
2. **Warn before it runs out.** Add `pub running_low(items: List[Item], below: Nat) -> List[Item]` with `ensures result.len <= items.len`, and an example where eggs at 2 are below 3 and flour at 700 is not. *Hint:* `missing` has the same shape.
3. **Use edition `0.2`.** Set `edition = "0.2"` in `una.toml`. The package still checks. Then replace the `fold` in `main` that joins the names with `join(needed, separator: ", ")`, a prelude function of edition `0.2`. The output does not change.

## Learn more

- Construct pages: [`kind`](https://una-lang.org/en/docs/language/types/kind/), [`where`](https://una-lang.org/en/docs/language/types/where/), [`requires`](https://una-lang.org/en/docs/language/functions/requires/), [`ensures`](https://una-lang.org/en/docs/language/functions/ensures/), [`when`](https://una-lang.org/en/docs/language/control-flow/when/), [`example`](https://una-lang.org/en/docs/language/examples/example/).
- Learn, the tutorial on the Una website: "Kinds" (`/learn/kinds/`); "Collections" (`/learn/collections/`); "Contracts and the verifier" (`/learn/contracts/`).
- Specification: [kinds (spec/03 §2)](https://una-lang.org/en/docs/spec/03-types/), [refinements (spec/03 §3)](https://una-lang.org/en/docs/spec/03-types/), [clauses (spec/04 §2)](https://una-lang.org/en/docs/spec/04-functions-and-contracts/), [obligation generation (spec/12 §3)](https://una-lang.org/en/docs/spec/12-verification/), [the prelude (spec/14 §1)](https://una-lang.org/en/docs/spec/14-standard-library/).

## Edition

Edition `0.1` ([edition](https://una-lang.org/en/docs/configure/package/edition/)). It also checks unchanged under edition `0.2`, as the third exercise shows.

## Files

`una.toml`

```toml
[package]
name = "pantry-example"
version = "0.1.0"
edition = "0.1"

[run]
entry = "pantry.main"
grants = ["console"]
```

`src/pantry/main.una`

```una
module pantry.main

import pantry.stock (Grams, Item, Milliliters, Pieces, shopping_list, total)

--- What the pantry holds this morning.
stock() -> List[Item] = [Item(name: "rice", amount: 0, measure: Grams), Item(name: "flour", amount: 700, measure: Grams), Item(name: "eggs", amount: 6, measure: Pieces), Item(name: "oil", amount: 0, measure: Milliliters)]

pub main() -> Unit
  uses @console: Console[print]
=
  let items = stock()
  let needed = shopping_list(items)
  let line = needed.fold(initial: "", step: fn(line, name) -> if line == "" then name else "{line}, {name}")
  @console.print("to buy: {line}")
  let grams = total(items, measure: Grams)
  @console.print("grams in stock: {grams}")
```

`src/pantry/stock.una`

```una
module pantry.stock

--- How an item is measured.
pub kind Measure = Grams | Pieces | Milliliters

--- A shelf label, as printed on the shelf.
pub kind Label = Text

pub kind Item
  name: Text
  amount: Nat
  measure: Measure

--- A labeled group of anything: a shelf of items, a box of jars.
pub kind Bin[T]
  label: Label
  entries: List[T]

--- A list with at least one entry.
pub kind NonEmpty[T] = List[T] where it.len > 0

--- Adds `added` to an item.
pub restock(item: Item, added: Nat) -> Item
  ensures result.amount == item.amount + added
=
  Item(name: item.name, amount: item.amount + added, measure: item.measure)

--- Takes `used` from an item that has enough of it.
pub use_up(item: Item, used: Nat) -> Item
  requires used <= item.amount
  ensures result.amount == item.amount - used
=
  Item(name: item.name, amount: item.amount - used, measure: item.measure)

--- The items that have run out.
pub missing(items: List[Item]) -> List[Item]
  ensures result.len <= items.len
=
  items.filter(keep: fn(i) -> i.amount == 0)

--- The names of the items to buy, in pantry order.
pub shopping_list(items: List[Item]) -> List[Text]
  ensures result.len <= items.len
=
  missing(items).map(each: fn(i) -> i.name)

--- How much of one measure the pantry holds.
pub total(items: List[Item], measure: Measure) -> Int = items.fold(initial: 0, step: fn(sum, i) -> if i.measure == measure then sum + i.amount else sum)

--- The item called `name`, when the pantry has it.
pub find(items: List[Item], name: Text) -> Option[Item] = items.first_where(keep: fn(i) -> i.name == name)

--- The amount left of `name`, zero when the pantry has none.
pub amount_of(items: List[Item], name: Text) -> Nat
=
  when find(items, name)
    is Some(item) -> item.amount
    is None -> 0

--- How many entries of a bin satisfy `keep`.
pub count_where[T](bin: Bin[T], keep: fn(T) -> Bool) -> Nat
  ensures result <= bin.entries.len
=
  bin.entries.filter(keep).len

--- The average of some counts, rounded down.
pub average(counts: NonEmpty[Int]) -> Int = counts.sum() / counts.len

example "restocking adds to the amount"
  do restock(Item(name: "rice", amount: 200, measure: Grams), added: 300)
  expect result.amount == 500

example "using up takes from the amount"
  do use_up(Item(name: "eggs", amount: 6, measure: Pieces), used: 4)
  expect result.amount == 2

example "the shopping list names what ran out"
  do shopping_list([Item(name: "rice", amount: 0, measure: Grams), Item(name: "eggs", amount: 6, measure: Pieces), Item(name: "oil", amount: 0, measure: Milliliters)])
  expect result == ["rice", "oil"]

example "totals count one measure only"
  do total([Item(name: "rice", amount: 500, measure: Grams), Item(name: "flour", amount: 200, measure: Grams), Item(name: "eggs", amount: 6, measure: Pieces)], measure: Grams)
  expect result == 700

example "an item the pantry does not have amounts to zero"
  do amount_of([Item(name: "eggs", amount: 6, measure: Pieces)], name: "milk")
  expect result == 0

example "a bin counts the entries that match"
  do count_where(Bin(label: "jars", entries: [3, 0, 5]), keep: fn(n) -> n > 0)
  expect result == 2

example "the average of three counts is rounded down"
  do average([2, 4, 10])
  expect result == 5
```
