Get started
In about ten minutes you install Una, write a function with a contract, watch una check find the input that breaks it, fix it, and build a native executable.
You write wordfreq, a program that counts the words of a text and prints the counts as JSON. Every code block here is tested against this release, except that the outputs shown in text blocks are not compared with a run, and the finished program is examples/wordfreq.
Note
Una runs on macOS and Linux on arm64. More about installing lists the supported systems.
1. Install
Run the installer:
curl -fsSL https://raw.githubusercontent.com/una-lang/una/main/install.sh | shIt puts the release in ~/.una and changes nothing else. Put that directory on your PATH:
export PATH="$HOME/.una/bin:$PATH"To keep it for new shells, add the same line to your shell's profile: ~/.zshrc for zsh, the default shell on macOS, or ~/.bashrc for bash.
Check that it works:
una --versionIt prints the release, the editions it serves and the version of the prover built into it. That is everything you need to check, test and run programs.
Tip
Working with an AI agent? Give it Una, compact: the language in one page, sized for its context.
2. A contract, and a proof that fails
A contract says what a function needs and what it promises. Una proves it for every input, before the program runs.
Make a directory wordfreq with two files. una.toml names the package and its edition, and the module wordfreq lives in src/wordfreq.una. Start with a function that takes the first letter of a word:
[package]
name = "wordfreq"
version = "0.1.0"
edition = "0.2"module wordfreq
--- The first letter of a word.
pub initial(word: Text) -> Text
ensures result.len == 1
=
word.slice(start: 0, end: 1)The line ensures result.len == 1 is the promise: the result is one character long. In the wordfreq directory, run una check .:
[U5001] Error: precondition `0 <= 0 and 0 <= 1 and 1 <= word.len` of this call is refuted
╭─[ src/wordfreq.una:7:3 ]
│
7 │ word.slice(start: 0, end: 1)
│ ──────────────┬─────────────
│ ╰─────────────── precondition `0 <= 0 and 0 <= 1 and 1 <= word.len` of this call is refuted
│
│ Note 2: counterexample: word = Text#0, word.len = 0The promise does not hold, and Una shows why:
- The counterexample is
word.len = 0: an empty word. - The cause is the call of
slice, which requires its positions to lie in the text. - The repairs come with the diagnostic. With
una --json check, it is a JSON document an agent can act on.
The fix is to say what initial needs, with requires:
[package]
name = "wordfreq"
version = "0.1.0"
edition = "0.2"module wordfreq
--- 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)
example "a word's first letter"
do initial("una")
expect result == "u"Now una check . prints nothing: every check passes.
- Every caller has to prove the
requires, and the body may assume it. - The
exampleis a test.una test .runs it, anduna checkproves that"una"meets therequires.
Tip
una explain U5001 explains a diagnostic code, with a failing example and its fix.
3. A program that runs
Turn the package into a program. Three files:
una.tomlgains a[run]section: whereuna runstarts, and what the program may use.verification.lockfixes the prover's version and settings, so a check that passes on your machine passes on every other. Copy it as it is.src/wordfreq.unagets the words of a line, and amainthat prints how many there are.
[package]
name = "wordfreq"
version = "0.1.0"
edition = "0.2"
[run]
entry = "wordfreq"
grants = ["console"]encoding_version = "una-smt-1"
solver = "z3"
solver_version = "5.1.0"
logic = "QF_UFLIA"
step_budget = 5000000
random_seed = 0module 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)
pub main() -> Unit
uses @console: Console[print]
=
let text = "the cat and the hat and the bat"
@console.print("{words(text).len} words")Three things to notice:
- A function is an equation: its header, then
=, then its body. splitandfilterare prelude functions, called with method syntax.mainsays what it uses:@console, with the operationprint. A function that calls another performs its effects too, so the caller'susesmust cover them.una contractprints a function's header, itsusesincluded.
Check it and run it:
una check .
una run .8 wordsuna check runs every check, the proofs included, and prints nothing when all pass. The source must also be in canonical form; una fmt . rewrites it so.
4. Maps and JSON
Count the words with a Map, which keeps its keys in order, and write the counts as JSON. This is the whole program, with initial from section 2 back in:
[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)- Values, not references.
let editdeclares a binding that the code may change.edit counts.set(...)givescountsa new map, which is updated in place when nothing else holds it. - Absence is a value.
getreturns anOption:if none use 0handles a word not seen yet. - One effect per line. Each line that can fail or act is handled on the lines below it, as
if nonehere.
una test .
una run .{"and":2,"bat":1,"cat":1,"hat":1,"the":3}5. Capabilities and grants
main uses Console[print] and nothing else, and una run gives it exactly what [run] grants lists in una.toml.
- Without
"console"there, the program does not start: U3012 names the capability that is missing. - A grant can also come from the command line:
una run . --grant console.
The host offers these capabilities, only to main, which passes them to the functions it calls:
| Capability | Since edition |
|---|---|
Console, Clock, Env, Files, Keys |
0.1 |
Http |
0.2 |
HttpServer, for a program that serves HTTP |
0.4 |
Edition 0.4 offers them to the entry functions of a driven or served module too (Serving HTTP, Driven programs).
Note
Information flow is checked too. Text that comes from the outside, as Files.read returns, is labeled internal, and printing it needs a declassification policy (§9 of the guide for agents).
6. A native executable
una build checks the package, then compiles main into a native executable, with the grants of una.toml built in:
una build .
./target/una/wordfreqbuilt target/una/wordfreq
{"and":2,"bat":1,"cat":1,"hat":1,"the":3}The executable prints what una run prints, and traces the same events: the interpreter is the reference, and the test suite runs every example program in both.
Note
On Linux, una build links the executable through cc, against the system's C library: without cc it stops with "cannot run the system linker cc". The executable runs on the machine that built it and on systems with the same or a newer glibc, not on musl systems.
7. An editor
una lsp is a language server (LSP 3.17 over stdin and stdout) for any editor that speaks the protocol: it checks as you type, proves a file when it is opened or saved, formats on request, and never runs programs.
8. Edition 0.4
wordfreq is a package of edition 0.2, a stable edition. Edition 0.4 is a preview: a later release may still change what it accepts. It adds:
- programs that run until they are stopped;
- tasks and time limits;
- HTTP servers;
- dependencies on other packages through Itá, the package manager (in this release, path dependencies and registry packages read from a mirror directory).
A package of edition 0.4 is described by ita.una and pinned by ita.lock, not by una.toml and verification.lock: una.toml naming edition = "0.4" is U7002, and una migrate is the repair.
To move a copy of wordfreq to edition 0.4:
- Its tests are written
example, the form of editions0.1and0.2. From edition0.3on they are writtentest, anduna fixrewrites them in a package of edition0.3only. So first setedition = "0.3"inuna.toml, then rununa fix ., which rewrites both tests. - Run
una migrate .. It writesita.unaandita.lock, removesuna.tomlandverification.lock, and prints every diagnostic that the change of edition causes, none here. una check .,una test .anduna run .then work as before, in edition0.4.
The ita.una it writes:
ita wordfreq
version 0.1.0
edition 0.4
run
entry wordfreq
grants
consoleThe pages on edition 0.4 are Tasks and time, Serving HTTP, Driven programs and the package manager; Known limits says what this release does not do yet.
Where next
- With an agent: Una, compact is the language in one page, and the guide for agents is the full reference to edition
0.2, with notes where editions0.3and0.4differ. - A construct: the syntax reference lists the constructs of edition
0.2, and some of what editions0.3and0.4add. - A diagnostic:
una explain <code>explains any code, with examples. - The definition: the specification is normative.