---
title: "Lexical structure"
url: https://una-lang.org/en/docs/language/lexical-structure/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/guide/syntax-reference.md
---

# Lexical structure

## 1.1 Files and characters

| Rule | Detail | Error |
| --- | --- | --- |
| Encoding | UTF-8, with no byte order mark | U0001 |
| Line endings | The lexer accepts `\n` and `\r\n` (read as `\n`); a lone `\r` is rejected. Only `\n` is canonical: `una check` reports a file with `\r\n` as one U7001 at the first of them, without an edit, and `una fmt` rewrites the file with `\n` (§13). | U0001, U7001 |
| One module per file | Extension `.una` | |
| ASCII outside literals and comments | Identifiers, keywords and punctuation are ASCII. Other characters (accents, CJK, emoji) may appear only inside text literals and comments. | U0001 |
| Control characters | U+0000 to U+001F (except tab and line feed) and U+007F are forbidden everywhere, including literals and comments | U0001 |
| Bidirectional controls | U+202A to U+202E and U+2066 to U+2069 are forbidden everywhere, as a defense against "Trojan Source" attacks | U0001 |

Characters that are forbidden in raw form can still appear in text through escapes: `"\u{202E}"` is valid.

## 1.2 Indentation

Una uses significant indentation.

- **Spaces only.** A tab in leading whitespace is an error (U0002). Tabs inside literals and comments are allowed.
- **Exactly 2 spaces per level.** Any other depth is an error (U0003), and so is dedenting to a column no enclosing block uses.
- **Blank and comment-only lines** do not affect indentation.
- **Inside `( )` and `[ ]`**, the parser accepts line breaks and ignores the indentation of continued lines. The canonical form has no line width, so it joins continued lines into one: `una fmt` joins them, and `una check` reports the split as U7001. The only exception is a line with a comment inside its brackets, whose line breaks are kept, each continuation line one level deeper (§13).
- **Brackets must be balanced** within a declaration (U0101).

```una
module demo

add_all(first: Int, second: Int) -> Int = first + second

pub total(a: Int, b: Int) -> Int
  requires a >= 0
=
  let sum = add_all(first: a, second: b)
  sum
```

## 1.3 Comments

| Form | Meaning |
| --- | --- |
| `-- text` | Line comment |
| `--- text` | Doc comment. Consecutive lines attach to the next declaration and appear in `una contract` output. |

- There are no block comments.
- A doc comment that is not followed by a declaration (at end of file, inside a body, or before `module`) is treated as a plain comment.

## 1.4 Identifiers and naming conventions

| Token | Pattern | Used for |
| --- | --- | --- |
| lower identifier | `[a-z][a-z0-9_]*` | values, parameters, fields, functions, predicates, handlers, policies, module path segments, capability operations |
| upper identifier | `[A-Z][A-Za-z0-9_]*` | kinds, variants, capabilities, label categories, requirement IDs |
| capability reference | `@` followed by a lower identifier | `@audit`, `@console` |

Naming problems fall into two cases.

**Wrong case class: a parse error (U0101).** Where the grammar expects an upper identifier, a lower one is not a name at all, and the reverse:

| You wrote | Message |
| --- | --- |
| `kind bad_kind = Int` | unexpected `bad_kind`, expected a kind name |
| a variant written in lowercase, as in `kind K = \| open` | unexpected `open`, expected a variant name |
| `requirement events3` | unexpected `events3`, expected a requirement identifier |

**Right case class, wrong convention: U1005.** The name has the right first letter, but breaks the convention of its class:

- lower identifiers use `snake_case`, without `__` and without a trailing `_` (`f__x`, `g_`);
- kinds, variants, capabilities and categories use `UpperCamelCase` (`Bad_Name`);
- requirement IDs use upper snake case ending in `_` and a number: `EVENTS_3`, `CHECKIN_12` (not `Events_3`).

The message names the construct and suggests a fix: "kind `Bad_Name` must be UpperCamelCase, as in `BadName`".

Names cannot start with `_` (U0001, with the hint "names start with a letter"). A reserved keyword cannot name a binding: `let result = ...` is U0101, and the message says what the word is reserved for (`result` names a function's result in `ensures`).

## 1.5 Keywords

**Reserved in every edition.** These are never usable as names:

```text
accepts and attempt capability checked confidential derived do else ensures
error example expect fail fails false fn for from given handler if implies
import in internal is it kind let mod module none not op opaque or pass
performed policy predicate pub public reflect requirement requires restricted
result secret then true trusted unit use uses when where with
```

**Keywords of edition `0.2`.** `edit`, `take` and `old` (the memory model, `spec/17`) and `together` (structured concurrency, `spec/19`). In edition `0.1`, `old` is an ordinary name and the others give the U0103 messages of the v0.1 table below.

**Contextual.** These are keywords only inside `requirement` and `policy` blocks, and ordinary names elsewhere (a parameter called `status` or `source` is fine):

```text
active generated human owner proposed purpose regulation source status text to via
```

`Eq`, `Ord` and `Integer` are prelude names of edition `0.2`, the built-in constraints of §3.3, and `I8` to `U64` are built-in kinds (§3.1). A kind, variant or capability with one of these names is U1002, as is one named like any other built-in type: `Int`, `Nat`, `Bool`, `Text`, `Unit`, `Hashed`, `List`, `Option`, `Result` or `Map` (ADR 0079).

**Reserved for later, or deliberately absent** (U0103). The message is `` `<word>` is `` followed by the text below, as in "`macro` is not supported (charter §6)", and names the plan or the Una alternative. In edition `0.2`:

| Word | Message |
| --- | --- |
| `shared`, `iso`, `weak` | reserved for a later edition (aliasing) |
| `parallel`, `actor` | reserved for a later version (concurrency beyond `together`) |
| `simd`, `profile` | reserved for v0.2 (systems profile) |
| `trait`, `impl` | reserved for a later version (user traits) |
| `law`, `all` | reserved for a later edition (laws) |
| `costs` | reserved for a later edition (cost contracts) |
| `traced` | reserved for a later edition (provenance tracing) |
| `service`, `table`, `query`, `observe`, `commit` | reserved for a later edition (platform) |
| `match` | not a keyword in Una; use `when` |
| `return` | not a keyword in Una; the last expression is the result |
| `var` | not a keyword in Una; use `let edit` |
| `while`, `loop` | not a keyword in Una; use `for` or recursion |
| `region` | not a keyword in Una; the backend chooses where values live |
| `type` | not a keyword in Una; use `kind` |
| `unsafe` | not a keyword in Una; use a `trusted` module |
| `macro` | not supported (charter §6) |
| `async`, `await` | not supported; use `together` |

A package of edition `0.1` keeps the table of v0.1 in every version of the compiler: there, `edit`, `take`, `region`, `shared` and `iso` are "reserved for v0.2 (memory model)", `together`, `parallel` and `actor` "reserved for v0.2 (concurrency)", `trait` and `impl` "reserved for v0.2 (constraints on generics)", `var` says "values are immutable, use `let`", `while` and `loop` say "use recursion or `fold`", and `async` and `await` "see structured concurrency in v0.2".

## 1.6 Literals

**Integers**

- Decimal only, with `_` allowed between digits: `0`, `42`, `1_000_000`.
- Negative numbers use unary minus: `-5`. A negated literal counts as one literal, so `-128` fits `I8`.
- `Int` is unbounded and never overflows. The fixed-width types of §3.1 have a range, and a literal takes the fixed-width type its context expects.
- Malformed integers are U0007, with a mechanical fix when unambiguous:

| Written | Problem | Fix |
| --- | --- | --- |
| `007` | leading zero | `7` |
| `1__000` | doubled underscore | `1_000` |
| `1_` | trailing underscore | `1` |

**Text**

- Double quotes on a single line: `"hello"`. An unterminated literal is U0004.
- Escapes: `\"`, `\\`, `\n`, `\t`, `\{`, `\}`, and `\u{H}` with 1 to 6 hex digits naming a Unicode scalar value.
- An unknown or invalid escape (`"C:\data"`, `\u{D800}`, `\u{110000}`, `\u0041`) is U0005.
- A bare `}` outside an interpolation is U0007: write `\}`. So is a `{` that no expression can follow, a quote, a backslash or a `}` after any blanks, as in JSON written in text: write `\{`. Each comes with the edit, and the literal goes on, so one brace is one diagnostic.

**Interpolation**

`"{event.name}: {label}"` embeds an expression between braces.

- The embedded expression cannot contain a text literal (U0006). Bind it with `let` first.
- Any value that holds no function and no `Hashed` can be interpolated (U2001 otherwise). It is written in its Una form, as `una test` shows it: `Event(name: "Gala", remaining: 3)`, `[1, 2]`, `Some(3)`. A `Text` inside it is quoted. A value of a type parameter `T` needs `[T: Eq]` (U2026). In edition 0.1, only integers, `Bool` and `Text` can be interpolated (ADR 0068).
- A missing closing `}` is reported as U0004 at the opening quote.
- Interpolation **propagates labels**: `"id {phone}"` is as secret as `phone` (§8).

```una
module demo

pub kind Status = SoldOut | Few | Open

pub kind Event
  name: Text
  remaining: Int

--- A record is interpolated as it is, or field by field for a shorter text.
pub describe(event: Event) -> Text = "{event.name} ({event.remaining} seats)"

--- The whole record: `Event(name: "Gala", remaining: 3)`.
pub raw(event: Event) -> Text = "{event}"

pub banner(event: Event, status: Status) -> Text
=
  let label = when status
    is SoldOut -> "sold out"
    is Few -> "few seats left"
    is Open -> "open"
  "{describe(event)}: {label}"
```

**Other literals:** `true`, `false`, and `unit`, the only value of type `Unit`.

## 1.7 Operators and precedence

From highest to lowest precedence:

| Level | Operators | Associativity |
| --- | --- | --- |
| 1 | call `f(..)`, field or method `.name`, capability operation `@c.op(..)` | left |
| 2 | unary `-` | prefix |
| 3 | `*` `/` `mod` | left |
| 4 | `+` `-` | left |
| 5 | `==` `!=` `<` `<=` `>` `>=` `is` `in` | none |
| 6 | `not` | prefix |
| 7 | `and` | left |
| 8 | `or` | left |
| 9 | `implies` | right |

Nuances:

- **No chained comparisons.** `0 < x < 10` is U0101; write `0 < x and x < 10`, or `x in 1..<10`.
- **`not` binds looser than comparisons.** `not a == b` means `not (a == b)`.
- **`implies` groups to the right.** `a implies b implies c` means `a implies (b implies c)`.
- **`and`, `or` and `implies` short-circuit.**
- **Division and `mod` are Euclidean,** so the remainder is never negative: `-7 / 2 == -4` and `-7 mod 2 == 1`. Division by a value the compiler cannot prove nonzero is a proof obligation (§11), never a runtime crash.
- **Integer operators take operands of one type.** `a + b` with `a: U8` and `b: U16` is U2001: convert one of them (§3.1).
- **Ranges:** `a..b` includes `b`; `a..<b` excludes it. Ranges appear after `in`, in `when` arms, in kind sugar, and as the source of `for` and `together for` (§5.5, §5.7). They are not values.
- **`is` tests a variant or a literal:** `result is SoldOut`, `opt is None`, `flag is true`.

Characters with no meaning in Una are U0001. Some messages carry a hint:

| Character | Hint |
| --- | --- |
| `;` | statements end at line breaks |
| `!` (not part of `!=`) | use `not` |
| `&` | use `and` |
| `'` | text literals use double quotes |
| `_` at the start of a name | names start with a letter |

---
