Every component on this page is written in plain Markdown, so writers and translators never touch HTML. Each one is shown rendered, with its source underneath. Color carries meaning only: blue for notes, green for tips and checks, purple for what matters most, orange for warnings, gold for security and labels, rose for errors.
The strip above is the chapter meta strip. It is rendered from the page's front matter (time, editions, prerequisites, codes), never written by hand.
Text
Inline code
Backticks make a chip with presence. Its tint follows the code blocks' own colors, so a reader learns one color language: keywords purple, kinds blue, capabilities gold, commands green, file paths dashed with a file icon.
A header says fails OrderError, a call says if error pass, a parameter has the kind Option[Int], an operation needs @inventory, you run una check ., and the file is day-to-day/src/orders.una. Anything else, such as raw.trim.to_int(), is a plain chip.
markdown
A header says `fails OrderError`, a call says `if error pass`, a parameter has the kind `Option[Int]`, an operation needs `@inventory`, you run `una check .`, and the file is `day-to-day/src/orders.una`. Anything else, such as `raw.trim.to_int()`, is a plain chip.
Error codes
A diagnostic code is detected on its own, in text or in backticks, and links to its page. A backslash before it, \U3007, keeps it plain text.
Forgetting the clause is U3007, and passing a failure of another kind is U3008.
markdown
Forgetting the clause is U3007, and passing a failure of another kind is `U3008`.
Specification citations
A spec/NN §M reference becomes a citation chip that links to that section. Use it in the Reference part of a chapter, not in running prose.
The rules for handling clauses are in spec/06 §3, and refined kinds in spec/03.
markdown
The rules for handling clauses are in spec/06 §3, and refined kinds in spec/03.
Keys and anchors
Double brackets make a keyboard key; an escaped bracket, \[, keeps them plain text. Every heading from level 2 to 4 shows a link anchor on hover; hover the headings on this page. The anchor is hidden from screen readers and out of the tab order, so a heading reads as its text; the table of contents links every section.
Press / or CtrlK to search the docs.
markdown
Press [[/]] or [[Ctrl]] [[K]] to search the docs.
Callouts
GitHub-style markers on a quote. The title defaults from the marker, in the page's language once that label's translation is approved (in English until then), and can be replaced on the marker line. Use at most one callout per screen; a callout that repeats the paragraph above it should be cut.
Note
una contract prints the inferred header of a private function, with the comment -- inferred.
Retry once
attempt works on a capability operation too, so a retry needs no re-raise.
Important
When a statement can both fail and give an Option, if error comes first and if none second.
Warning
checked replaces a proof with a test, so una.toml budgets it per module.
Security
Lines read from a file are labeled internal. Printing a report built from them is a question of information flow, answered by a policy.
markdown
> [!NOTE]
> `una contract` prints the inferred header of a private function, with the comment `-- inferred`.
> [!TIP] Retry once
> `attempt` works on a capability operation too, so a retry needs no re-raise.
> [!IMPORTANT]
> When a statement can both fail and give an `Option`, `if error` comes first and `if none` second.
> [!WARNING]
> `checked` replaces a proof with a test, so `una.toml` budgets it per module.
> [!SECURITY]
> Lines read from a file are labeled `internal`. Printing a report built from them is a question of information flow, answered by a policy.
Quotes
Key idea
One per chapter: the principle the reader should leave with. It moves an existing sentence out of the prose, word for word.
Key idea
Nothing in Una fails at run time without the code saying so.
markdown
> [!KEY]
> Nothing in Una fails at run time without the code saying so.
Quote with a source
A plain quote. A last paragraph that starts with an em dash names the source.
Make it work, make it right, make it fast.
A common engineering maxim
markdown
> Make it work, make it right, make it fast.
>
> — A common engineering maxim
Chapter frame
What you'll build
Wrap the content under the "What you'll build" heading. The paragraph right before the list becomes its label.
An order-intake step for a small store. It reports every line, accepted or rejected:
Output
ok 2 x LAMP-01
reject no product has the SKU CHAIR-09
You will learn to:
declare an error kind whose variants carry what someone needs to fix the problem;
turn a failure into a value with attempt, so one bad line does not stop a batch.
markdown
::::build
An order-intake step for a small store. It reports every line, accepted or rejected:
```text
ok 2 x LAMP-01
reject no product has the SKU CHAIR-09
```
You will learn to:
- declare an error kind whose variants carry what someone needs to fix the problem;
- turn a failure into a value with `attempt`, so one bad line does not stop a batch.
::::
Code
File path and checks
The info string carries the file path, an optional caption, and the checks the block passed. Blocks without a title show their language.
parse_quantity(raw: Text) -> IntfailsQuantityError
=
let n = raw.trim.to_int()
ifnonefailNotANumber(raw)
n
markdown
```una title="steps/01-quantity/src/quantity.una" caption="the parser" verified="check, run"
parse_quantity(raw: Text) -> Int
fails QuantityError
=
let n = raw.trim.to_int()
if none fail NotANumber(raw)
n
```
Output and diagnostics
A text block is program output, in a terminal look; test results color ok and passed. A text block that holds a diagnostic is detected and drawn with a rose accent (orange for a warning), its code linked.
Output
example orders "a line in stock is accepted" ... ok
example orders "too many units are out of stock" ... ok
2 examples: 2 passed, 0 failed
Diagnostic
[U3007]Error:`parse_order` can fail with `OrderError`; handle the failure with an `if error` clause╭─[ src/orders.una:56:15 ]
│56│let order = parse_order(line)
│────────┬────────│╰────────── `parse_order` can fail with `OrderError`││Help: add `if error pass` on its own line
────╯
markdown
```text
example orders "a line in stock is accepted" ... ok
example orders "too many units are out of stock" ... ok
2 examples: 2 passed, 0 failed
```
```text
[U3007] Error: `parse_order` can fail with `OrderError`; handle the failure with an `if error` clause
╭─[ src/orders.una:56:15 ]
│
56 │ let order = parse_order(line)
│ ────────┬────────
│ ╰────────── `parse_order` can fail with `OrderError`
│
│ Help: add `if error pass` on its own line
────╯
```
Wrong and right
Two blocks marked mistake="wrong" and mistake="right", side by side inside a pair, stacked on a phone.
beforeuna
check_stock(parse_order(line))
afteruna
let order = parse_order(line)
iferrorpasscheck_stock(order)
iferrorpass
markdown
::::pair
```una title="before" mistake="wrong"
check_stock(parse_order(line))
```
```una title="after" mistake="right"
let order = parse_order(line)
if error pass
check_stock(order)
if error pass
```
::::
Walkthrough steps
A numbered list inside steps, after a code block. A step that opens with bold code is tied to the line that holds that code: the line gets the step's number, and hovering over the step highlights it.
una
let left = @inventory.on_hand(order.sku)
iferrorfailUnavailableifnonefailUnknownSku(sku: order.sku)
Walkthrough:
if error fail Unavailable. The service's failure becomes a failure of this layer.
if none fail UnknownSku(sku: order.sku). An unknown SKU is the input's fault.
markdown
::::steps
```una
let left = @inventory.on_hand(order.sku)
if error fail Unavailable
if none fail UnknownSku(sku: order.sku)
```
Walkthrough:
1. **`if error fail Unavailable`.** The service's failure becomes a failure of this layer.
2. **`if none fail UnknownSku(sku: order.sku)`.** An unknown SKU is the input's fault.
::::
Tables
Reference table
A normal Markdown table: quiet header, row hover, and a horizontal scroll inside the table, never on the page.
Clause
Use it when
if error use v
You can carry on with a sensible value
if error pass
Your function fails with the same kind
markdown
| Clause | Use it when |
| --- | --- |
| `if error use v` | You can carry on with a sensible value |
| `if error pass` | Your function fails with the *same* kind |
Decision table
Wrap a "Which to use" table in decide: the first paragraph is its title, and each row reads as a choice leading to an answer.
Which to use:
You want to…
Use
Carry on with a default
if error use / if none use
Keep going and collect outcomes
attempt, then when
markdown
::::decide
**Which to use:**
| You want to… | Use |
| --- | --- |
| Carry on with a default | `if error use` / `if none use` |
| Keep going and collect outcomes | `attempt`, then `when` |
::::
Practice
Common mistake
Each mistake is a card: its bold lead is the title (the number becomes a badge), the rest of that paragraph is what was written, then what una says, then rows that open with an emphasized label such as Why: or Fix:.
[U3009]Error:`Timeout` is a variant of `StoreError`, and this code fails with `OrderError`
Why: a function has one error kind.
Fix: name a variant of your own kind.
markdown
::::mistake
**3. Failing with a variant of another kind (U3009).** Write `if error fail Timeout` in `check_stock`:
```text
[U3009] Error: `Timeout` is a variant of `StoreError`, and this code fails with `OrderError`
```
*Why:* a function has one error kind.
*Fix:* name a variant of your own kind.
::::
Exercise, hint and answer
An exercise is a card. A hint sits in hint; the answer sits in answer, collapsed, with its summary on the marker line. The summary is a real <summary>, reachable with Tab and opened with Enter.
Exercise 2: units shipped.
Write shipped(results), the total of the units of the accepted lines.
Hint: a private function from one Result to an Int, then map and sum.
Answer (check, test; exercises/2/answer):
una
pubshipped(results: List[Result[Order, OrderError]]) -> Int = results.map(each: units).sum()
markdown
:::::exercise
**Exercise 2: units shipped.** Write `shipped(results)`, the total of the units of the accepted lines.
::::hint
*Hint:* a private function from one `Result` to an `Int`, then `map` and `sum`.
::::
::::answer Answer (*check, test*; `exercises/2/answer`):
```una
pub shipped(results: List[Result[Order, OrderError]]) -> Int = results.map(each: units).sum()
```
::::
:::::
Recap
A list inside recap becomes a checklist of rules the reader can apply.
A failure is a value of a sum kind you declare.
attempt keeps an outcome as a Result, for batches, counts and retries.
markdown
::::recap
- A failure is a value of a sum kind you declare.
- `attempt` keeps an outcome as a `Result`, for batches, counts and retries.
::::
For agents and Reference
agents frames the part written for coding agents; reference turns the closing list into a quiet index.
Every diagnostic is available as JSON with una --json check ..
::::agents
Every diagnostic is available as JSON with `una --json check .`.
::::
::::reference
- Diagnostics: U3007, U3008
- Specification: spec/06 §3
::::
Tokens
Added on top of the site's tokens (--bg, --fg, --muted, --line, --purple, --purple2, --gold, --green). Spacing runs 4, 8, 12, 16, 24, 32 pixels; radii are 6 for chips, 10 for blocks and callouts, 14 for cards.