Home / Docs

Una for agents

Release v0.4.0Edition 0.2

A compact reference for writing Una in packages of edition 0.2, written for the v0.2 toolchain; later toolchains serve edition 0.2 unchanged. Editions 0.3 and 0.4 are previews: this guide notes where they differ and §22 moves a package to edition 0.4, but it does not teach their new constructs (for edition 0.4, see Tasks and time, Serving HTTP and Driven programs). The specification in docs/spec/ is normative; this guide summarizes it for an agent that writes, checks and repairs code.

How to read the blocks: every una block is a whole module that una check accepts in canonical form, as the only module of a package of edition 0.2, unless its first line is -- fails with U####, in which case checking it yields that code and no other. A block whose first line is -- edition 0.1 is checked in a package of edition 0.1. A block preceded by a file path belongs to a package with the other files named around it. Every json block is a document the CLI prints, and every sh block runs from the repository root, or in a fresh copy of the directory its # copy comment names. crates/una-cli/tests/guide.rs checks all of them.

1. The loop

This section has its own page: The loop.

2. Files and packages

3. Syntax in brief

una
-- fails with U0103
module demo

pub size(type: Text) -> Int = type.len

4. Kinds

una
module demo

--- An alias: a Label is a Text.
pub kind Label = Text

--- A refinement with range sugar; an Int flows into it only with a proof.
pub kind Percent = Int in 0..100

--- A record.
pub kind Tool
  name: Text
  deposit: Nat

--- Sums, with and without payloads. A sum of one variant starts with `|`.
pub kind CheckoutError = NotOnShelf(tool: Text) | ShelfDown

pub kind Oops = | TooLarge

--- Generic kinds; parameters are unconstrained.
pub kind Bin[T]
  label: Label
  entries: List[T]

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

A sum of one variant keeps its leading |: write kind Oops = | TooLarge. Without it, kind Oops = TooLarge is an alias of a type named TooLarge. That is U1001 when no such type exists, or U2002 when TooLarge is a variant of some other kind. A sum of two or more variants has no leading |.

Built-in types: Int (unbounded), Nat (Int at least 0), Bool, Text, Unit, List[T] ([a, b], xs.len), Option[T] (Some(value), None), Result[T, E] (Ok(value), Err(failure)), Hashed (from Keys only) and function types fn(A) -> B. Records and sums are nominal; aliases and refinements are their base type. Recursive kinds go only through List or Option in edition 0.1; edition 0.2 allows any recursion with a base variant, as kind Expr = Lit(value: Int) | Add(left: Expr, right: Expr) (ADR 0060).

Recursive kinds contain themselves through any field, as long as the kind has a finite value: some variant must end the recursion, or the field must be an Option or a List. A kind without a finite value is U2002.

una
module demo

--- A kind may contain itself when it has a finite value: `Lit` ends the recursion.
pub kind Expr = Lit(value: Int) | Add(left: Expr, right: Expr) | Neg(inner: Expr)

pub eval(e: Expr) -> Int
=
  when e
    is Lit(value) -> value
    is Add(left, right) -> eval(left) + eval(right)
    is Neg(inner) -> 0 - eval(inner)
una
-- fails with U2002
module demo

pub kind Stream = | Next(head: Int, tail: Stream)

Interpolation writes any value that holds no function in its Una form, the one una test shows: Point(x: 1, y: -2), [1, 2], Some(3), Err(NotFound). Text inside a structure is quoted. A record or variant with one field prints it without its name, as Some(3) or Offline("south"); with two or more fields, each is named. A field that holds a function is U2001. A value of a type parameter T needs [T: Eq]. The text keeps the labels of every field, so a record with a secret field cannot be printed (U4003) (ADR 0068).

una
module demo

pub kind Point
  x: Int
  y: Int

--- Interpolation writes the record itself: `at Point(x: 1, y: -2)`.
pub describe(p: Point) -> Text = "at {p}"

5. Functions

A function is header = body. Clauses come in this order: requires, ensures, uses, fails, derived from. With no clause and a one-line body, the short form is canonical.

una
module demo

pub kind Item
  name: Text
  amount: Nat

--- Short form.
pub double(x: Int) -> Int = x * 2

--- Long form: the header is the contract, the body follows `=`.
pub restock(item: Item, added: Nat) -> Item
  ensures result.amount == item.amount + added
=
  Item(name: item.name, amount: item.amount + added)

--- Method calls and lambdas: `items.filter(keep: ...)` is `filter(items, keep: ...)`.
pub missing(items: List[Item]) -> List[Text]
  ensures result.len <= items.len
=
  items.filter(keep: fn(i) -> i.amount == 0).map(each: fn(i) -> i.name)

--- Generic functions take function parameters for what they cannot do themselves.
pub count_where[T](xs: List[T], keep: fn(T) -> Bool) -> Nat
  ensures result <= xs.len
=
  xs.filter(keep).len

example "restocking adds to the amount"
  do restock(Item(name: "rice", amount: 2), added: 3)
  expect result.amount == 5
una
-- fails with U2004
module demo

pub add(a: Int, b: Int) -> Int = a + b

pub three() -> Int = add(1, 2)
una
-- fails with U1002
module demo

pub total(items: List[Int]) -> Int
=
  let items = items.filter(keep: fn(n) -> n > 0)
  items.sum()

6. Contracts and proofs

This section has its own page: Contracts and proofs.

7. Failures

This section has its own page: Failures.

8. Capabilities

This section has its own page: Capabilities.

9. Labels and information flow

This section has its own page: Labels and information flow.

10. Requirements and examples

This section has its own page: Requirements and examples.

11. Editable values and loops

This section has its own page: Editable values and loops.

12. Fixed-width integers

This section has its own page: Fixed-width integers.

13. Constraints on generics

This section has its own page: Constraints on generics.

14. Maps

This section has its own page: Maps.

15. JSON

This section has its own page: JSON.

16. Text

This section has its own page: Text.

17. HTTP

This section has its own page: HTTP.

18. Concurrent tasks: together

This section has its own page: Concurrent tasks: together.

19. Native executables and the language server

This section has its own page: Native executables and the language server.

20. The Agent ABI

This section has its own page: The Agent ABI.

21. Migrating from edition 0.1

This section has its own page: Migrating from edition 0.1.

22. Migrating to edition 0.4

From edition 0.4, a package is described by ita.una and pinned by ita.lock, in Una's own syntax, in place of una.toml and verification.lock (spec/30). Edition 0.4 is a preview. Collections and the numeric types after F64 are in edition 0.5, also a preview and also named in ita.una, as edition 0.5 (ADR 0139); una migrate writes edition 0.4, or keeps 0.5 when una.toml names it. The steps, in the package's directory:

  1. una migrate --dry-run prints the two files it would write and every diagnostic the new edition causes, and writes nothing.
  2. una migrate writes ita.una and ita.lock, rewrites each module in the canonical form of edition 0.4, removes una.toml and verification.lock, and prints the same diagnostics, such as a function named within, a word edition 0.4 reserves (U0103). It exits with code 0: the diagnostics are the next steps. A [package] name that is not a package name, such as events-example, becomes events_example; --name gives another.
  3. una fix applies the mechanical repairs, such as renaming within, and una check checks the result.
  4. Commit ita.una, ita.lock and the rewritten modules together.

What changes:

A package of edition 0.4, with its manifest, its lock and one module:

ita.unauna
ita demo
  version 0.1.0
  edition 0.4
ita.lockuna
lock 1

solver
  encoding "una-smt-1"
  name "z3"
  version "5.1.0"
  logic "QF_UFLIA"
  steps 5000000
  seed 0
src/demo.unauna
module demo

pub total(xs: List[Int]) -> Int
=
  let edit sum = 0
  for x in xs
    sum = sum + x
  sum