18 Tools
Page 1 of 11
Writing a program is half of the work. The other half is finding out whether it is right: reading what the checker reports, letting it repair what it can, seeing what it proved and what the program may do, and finally running, testing and shipping it. In Una all of that is one command, una, and each of its subcommands prints a text for people, or with --json a document for programs. This chapter takes a small pricing package through the commands you use every day, in the order you use them, and explains what each one tells you and why it is built that way.
What you'll build
Price tags for a sale at a store. Each tag shows a product's price and its sale price, which must never fall below what the store paid for the product, and a SKU the catalog does not list gets a tag that says so:
LAMP-01 19.90 now 13.93
DESK-02 129.00 now 110.00
CHAIR-09 not in the catalogYou will learn to:
- run the loop of
una check,una fmtanduna fix, and know whatuna fixwill and will not change; - read a diagnostic: its code, its places, its repairs and its counterexample, as text and as JSON;
- list what the verifier proved with
una obligations,una contractanduna trace; - read the build report, which says what the package may do and what it trusts;
- run, test and build a native executable, and connect an editor with
una lsp.
Download this chapter's packages: each step is a package under steps/, and the chapter's program is day-to-day/; run una check . and una run . in one.
Why it works this way
A compiler, the program that checks code and turns it into something a machine runs, often prints only a wall of text for a person. A script, a file of commands run one after another, an editor or an agent, a program built on an AI model that writes code, then parses messages never meant to be parsed, and breaks when one changes. And a compiler that only says "error" leaves the reader to work out the repair, even when the compiler knew exactly what it was.
Una's tools are built around three rules:
- Every problem is a diagnostic with a code. The code has a page and an explanation in the binary,
una explain U2004. The text of a message may improve from release to release, and the code stays. - Every command has two renderings of one result. By default a command prints for people. With
--jsonit prints the same content as one JSON document, data for programs (section 18.1 shows one), named by its schema, the name of its shape, such asuna.diagnostics/1. A schema keeps its version when keys are added, and changes it when a key is removed or changes meaning. - A repair is data. A diagnostic lists its repairs, ranked. A repair whose change is exact carries the edit itself, and
una fixapplies those edits, and only those that keep what the program is allowed to do.
The checks also give more than a yes or a no: the obligations, a function's full contract and the build report show a reviewer what was proven, not only that the check passed.
Whatever
una checkreports,una explainexplains,--jsongives as data, anduna fixrepairs when the edit is exact and widens nothing.