wordfreq
Counts how often each word of a line occurs, and prints the counts as one JSON object.
This is the finished program of the getting started tutorial, which builds it step by step. Read it after hello: it is still one module, but it has a contract that the solver proves, a map built in a loop, and JSON output. It is the smallest example of edition 0.2, the edition that adds editable bindings and for loops.
What it demonstrates:
- a contract,
requiresandensures, and how a missing precondition shows up as a counterexample; - a
Map[Text, Int]built withlet editand aforloop; - absence as a value:
Map.getreturns anOption, handled withif none use; exampleblocks thatuna testruns.
Run it
From this directory:
una check . # copy examples/wordfreq
una test .
una run .
una build .
./target/una/wordfrequna run . and the native executable print:
{"and":2,"bat":1,"cat":1,"hat":1,"the":3}The keys come out in ascending order because a Map keeps its keys sorted. una test . runs the two examples at the end of the module:
example wordfreq "a word's first letter" ... ok
example wordfreq "each word is counted" ... ok
2 examples: 2 passed, 0 failedHow it works
The program is one module, src/wordfreq.una, and reads as a pipeline: main splits a line into words, builds the counts, and prints the report.
Splitting a line: words
pub words(line: Text) -> List[Text]
=
let space = " "
line.split(on: space).filter(keep: fn(part) -> part.len > 0)split has a precondition: the separator is not empty (requires on.len > 0). The solver proves it here, because space is a literal of length 1. filter takes a lambda, fn(part) -> part.len > 0, and drops the empty parts that two spaces in a row would leave.
A contract: initial
pub initial(word: Text) -> Text
requires word.len >= 1
ensures result.len == 1
=
word.slice(start: 0, end: 1)main does not call initial. It is in the package to show a contract that the solver proves:
requires word.len >= 1is a promise that every caller must keep. The body may assume it.ensures result.len == 1is a promise that the function keeps. The solver proves it from the body and from whatslicepromises.slicehas its own precondition: both positions lie inside the text. It holds because of therequires.
una obligations . lists every obligation of the package and its status. Each line says (cached) because the una check . above already proved it; on a fresh copy the listing has no (cached):
proven ob-ee99f1a645a5 precondition src/wordfreq.una:7:3 space.len > 0 (cached)
proven ob-1ef23ba876c5 postcondition src/wordfreq.una:12:11 result.len == 1 (cached)
proven ob-bdc97550ae15 precondition src/wordfreq.una:14:3 0 <= 0 and 0 <= 1 and 1 <= word.len (cached)
proven ob-68828c279e76 precondition src/wordfreq.una:41:6 "una".len >= 1 (cached)The last line is the example do initial("una"): an example is a call like any other, so it must meet the requires too.
Counting: counts
pub counts(words: List[Text]) -> Map[Text, Int]
=
let edit counts: Map[Text, Int] = empty_map()
for word in words
let seen = counts.get(key: word)
if none use 0
edit counts.set(key: word, value: seen + 1)
countsUna has values, not references. let edit declares a binding that the function may change, and edit counts.set(...) gives counts a new map. A backend may update a value in place when nothing else holds it, so the loop need not copy the map on each word. The specification allows this and makes it unobservable: the program means the same either way (spec/17 §7, rule 3).
counts.get(key: word) returns an Option[Int]: a word seen for the first time has no entry. if none use 0 handles that case on the line below the call, so seen is a plain Int. Una asks for one effect per line: each call that can be absent or fail is handled right under it.
Printing JSON: report and main
report copies each count into a Map[Text, Json] with Number(...), wraps the map in Object(...) and calls to_json(). main holds the only authority of the program, uses @console: Console[print], and una.toml grants it.
What una check proves
initialreturns one character whenever its argument has at least one.- Every call meets the precondition of what it calls: the separator of
splitinwords, the bounds ofsliceininitial, andinitial's ownrequiresin its example. - Everything else is checked by typing: the types of every expression, the
Optionthatgetreturns, and the authority ofmain.
Common mistakes
A function that does not say what it needs
Delete the requires word.len >= 1 line from initial. una check . cannot prove slice's precondition any more, and shows a value that breaks it:
[U5001] Error: precondition `0 <= 0 and 0 <= 1 and 1 <= word.len` of this call is refuted
╭─[ src/wordfreq.una:13:3 ]
│
13 │ word.slice(start: 0, end: 1)
│ ──────────────┬─────────────
│ ╰─────────────── precondition `0 <= 0 and 0 <= 1 and 1 <= word.len` of this call is refuted
│
│ Help 1: repair 1: strengthen the type of the parameter `word` to a refined kind that implies `0 <= 0 and 0 <= 1 and 1 <= word.len`
│
│ Help 2: repair 2: add a guard (`if` or a `when` arm) that handles the values where `0 <= 0 and 0 <= 1 and 1 <= word.len` does not hold
│
│ Help 3: repair 3 (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, 0 <= 0 and 0 <= 1 and 1 <= word.len) else fail <Variant>`
│
│ Note 1: obligation ob-bdc97550ae15 (precondition) is refuted: 0 <= 0 and 0 <= 1 and 1 <= word.len
│
│ Note 2: counterexample: word = Text#0, word.len = 0
│
│ Note 3: run `una explain U5001` for an explanation
────╯Read the counterexample first: word.len = 0, an empty word. Text#0 stands for some text that the solver does not spell out. The repairs are ranked, and they change only the function's own code. The fix that the example uses, a requires, is not among them. Repair 1, a refined parameter type, moves the duty to the callers in the same way, where the solver can check it. A checked (repair 3) would test it at run time instead, and costs part of the escape budget.
A caller that breaks the contract
Put the requires back, and change the first example to do initial(""). The solver now refutes the call, and points at the clause it breaks:
[U5001] Error: precondition `"".len >= 1` of this call is refuted
╭─[ src/wordfreq.una:41:6 ]
│
11 │ requires word.len >= 1
│ ──────┬──────
│ ╰──────── requires clause
│
41 │ do initial("")
│ ─────┬─────
│ ╰─────── precondition `"".len >= 1` of this call is refuted
│
│ Note 1: obligation ob-b9d5c8950b3e (precondition) is refuted: "".len >= 1
│
│ Note 2: run `una explain U5001` for an explanation
────╯Using an Option as if it were a value
Delete the if none use 0 line in counts. seen is then an Option[Int], and the addition does not type:
[U2001] Error: an operand of `+` must be `Int`, found `Option[Int]`
╭─[ src/wordfreq.una:22:39 ]
│
22 │ edit counts.set(key: word, value: seen + 1)
│ ──┬─
│ ╰─── an operand of `+` must be `Int`, found `Option[Int]`
│
│ Note: run `una explain U2001` for an explanation
────╯Tip
una --json check . prints the same diagnostics as JSON documents, with the obligation, the counterexample and the ranked repairs as fields. An editor or an agent can act on them without parsing text.
Extend it
- Ignore case. Make "The" and "the" the same word: call
to_loweron the line before you split it,words(to_lower(text)), and change the text inmainto mix cases. The output stays the same.to_lowerexists from edition0.2, and it promisesresult.len == t.len. - Keep the repeated words. Add
pub repeated(counts: Map[Text, Int]) -> List[Text], which keeps the keys whose count is above 1. Hint:counts.entries()is a list of entries withkeyandvalue, sofilterandmapdo the job in one line. Add an example:do repeated(counts(words("a b a")))andexpect result == ["a"]. - Count a file. Read the line from a file instead of a literal. Declare
uses @files: Files[read]onmain, grant"files:input:read"inuna.toml, and read@files.read("line.txt"). Paths are relative to the granted directory, so createinput/line.txtwith a line of words. The read can fail, so handle it on the line below, for example withif error use "". Then rununa check .: the text thatFiles.readreturns is labeledinternal, andwordstakes an unlabeled, that ispublic,Text, so the call is a U4001, a flow frominternaltopublic. File contents do not reach the console by accident. Thejournalexample shows how a package releases such data on purpose, through a policy.
Learn more
- Construct pages:
requires,ensures,let edit,for,if none use,example. - Tutorial: Getting started.
- Learn, the tutorial on the Una website: "Collections" (
/learn/collections/); "Contracts and the verifier" (/learn/contracts/). - Specification: clauses (spec/04 §2), one effect per line (spec/04 §4), counterexamples (spec/12 §7), editable bindings (spec/17 §2), backend freedom (spec/17 §7), maps, JSON.
Edition
Edition 0.2, for let edit and for, which edition 0.1 does not have (edition).
Files
[package]
name = "wordfreq"
version = "0.1.0"
edition = "0.2"
[run]
entry = "wordfreq"
grants = ["console"]module wordfreq
--- The words of a line: the parts between spaces, without the empty ones.
pub words(line: Text) -> List[Text]
=
let space = " "
line.split(on: space).filter(keep: fn(part) -> part.len > 0)
--- The first letter of a word.
pub initial(word: Text) -> Text
requires word.len >= 1
ensures result.len == 1
=
word.slice(start: 0, end: 1)
--- How often each word occurs, in ascending order of the words.
pub counts(words: List[Text]) -> Map[Text, Int]
=
let edit counts: Map[Text, Int] = empty_map()
for word in words
let seen = counts.get(key: word)
if none use 0
edit counts.set(key: word, value: seen + 1)
counts
--- The counts as one JSON object.
pub report(counts: Map[Text, Int]) -> Text
=
let edit fields: Map[Text, Json] = empty_map()
for entry in counts.entries()
edit fields.set(key: entry.key, value: Number(entry.value))
Object(fields).to_json()
pub main() -> Unit
uses @console: Console[print]
=
let text = "the cat and the hat and the bat"
@console.print(report(counts(words(text))))
example "a word's first letter"
do initial("una")
expect result == "u"
example "each word is counted"
do counts(words("a b a"))
expect result == empty_map().with(key: "a", value: 2).with(key: "b", value: 1)