Home / Docs

Get started

Release v0.4.0Edition 0.2

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:

sh
curl -fsSL https://raw.githubusercontent.com/una-lang/una/main/install.sh | sh

It puts the release in ~/.una and changes nothing else. Put that directory on your PATH:

sh
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:

sh
una --version

It 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:

una.tomltoml
[package]
name = "wordfreq"
version = "0.1.0"
edition = "0.2"
src/wordfreq.unauna
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 .:

Diagnostic
[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 = 0

The promise does not hold, and Una shows why:

The fix is to say what initial needs, with requires:

una.tomltoml
[package]
name = "wordfreq"
version = "0.1.0"
edition = "0.2"
src/wordfreq.unauna
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.

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.tomltoml
[package]
name = "wordfreq"
version = "0.1.0"
edition = "0.2"

[run]
entry = "wordfreq"
grants = ["console"]
verification.locktoml
encoding_version = "una-smt-1"
solver           = "z3"
solver_version   = "5.1.0"
logic            = "QF_UFLIA"
step_budget      = 5000000
random_seed      = 0
src/wordfreq.unauna
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)

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:

Check it and run it:

sh
una check .
una run .
Output
8 words

una 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:

una.tomltoml
[package]
name = "wordfreq"
version = "0.1.0"
edition = "0.2"

[run]
entry = "wordfreq"
grants = ["console"]
src/wordfreq.unauna
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)
sh
una test .
una run .
Output
{"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.

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:

sh
una build .
./target/una/wordfreq
Output
built 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:

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:

  1. Its tests are written example, the form of editions 0.1 and 0.2. From edition 0.3 on they are written test, and una fix rewrites them in a package of edition 0.3 only. So first set edition = "0.3" in una.toml, then run una fix ., which rewrites both tests.
  2. Run una migrate .. It writes ita.una and ita.lock, removes una.toml and verification.lock, and prints every diagnostic that the change of edition causes, none here.
  3. una check ., una test . and una run . then work as before, in edition 0.4.

The ita.una it writes:

una
ita wordfreq
  version 0.1.0
  edition 0.4

run
  entry wordfreq
  grants
    console

The 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