Home / Docs / Specification
01. Lexical structure
Status: Normative, v0.1.
1. Source text
- A source file MUST be valid UTF-8 and MUST NOT start with a byte order mark (U0001).
- Line endings
\r\nare normalized to\nbefore lexing. A lone\ris an error (U0001). - Identifiers and keywords are ASCII. Non-ASCII characters MAY appear only inside text literals and comments (U0001 elsewhere).
- A source file has the extension
.unaand contains exactly one module. - After U0001, lexing continues. Each maximal ill-formed subsequence of invalid UTF-8 is read as U+FFFD and counts as one column (spec/13 §1, ADR 0015).
- Control characters U+0000 to U+001F other than tab and line feed, U+007F, and the bidirectional controls U+202A to U+202E and U+2066 to U+2069 are an error anywhere in a file, including text literals and comments (U0001, ADR 0017). Text writes them with
\u{...}escapes. - A character that cannot start a token where it appears, such as
;or&, is an error (U0001), reported once per character (ADR 0017).
2. Lines and indentation
Una uses significant indentation. The lexer converts leading whitespace into INDENT and DEDENT tokens using an indentation stack, as follows.
- Indentation uses spaces only. A tab in leading whitespace is an error (U0002).
- Each indentation level is exactly 2 spaces deeper than the enclosing one (U0003 otherwise).
- Blank lines and lines containing only a comment do not produce
NEWLINE,INDENTorDEDENT. - Inside
()and[], newlines and indentation are ignored (implicit line joining). Brackets MUST be balanced within a declaration (U0101). - A logical line ends with a
NEWLINEtoken. At end of file the lexer emitsNEWLINEif the last logical line lacks one, then oneDEDENTper open level. - Trailing whitespace is non-canonical (U7001, reported by
una checkand fixed byuna fmt).
Algorithm, for each logical line with indentation n and stack top t:
if n == t: emit NEWLINE before the line (except the first line)
if n == t + 2: push n; emit INDENT
if n > t + 2: error U0003
if n < t: pop while top > n, emitting DEDENT per pop; if top != n: error U00033. Comments
--starts a comment that runs to the end of the line.---starts a doc comment. Consecutive doc comment lines attach to the next declaration and appear inuna contractoutput.- There are no block comments.
- A doc comment not followed by a declaration is an ordinary comment (ADR 0017).
- A declaration's doc comments are every doc comment between the end of the preceding token (the previous declaration, import or module header) and the declaration's first token, even when blank lines or ordinary comments separate them from the declaration, so a doc comment below the module header attaches to the file's first declaration.
4. Identifiers and naming conventions
| Token | Pattern | Used for |
|---|---|---|
lower_ident |
[a-z][a-z0-9_]* |
Values, parameters, fields, functions, predicates, handlers, policies, modules, capability operations |
upper_ident |
[A-Z][A-Za-z0-9_]* |
Kinds, variants, capabilities, label categories, requirement identifiers |
cap_ref |
@ immediately followed by lower_ident |
Capability references (@audit) |
Convention checks (U1005): lower_ident MUST NOT contain __ or end with _. Kinds, variants, capabilities and categories use UpperCamelCase ([A-Z][a-zA-Z0-9]*). Requirement identifiers use upper snake case ending in a number (EVENTS_3, pattern [A-Z][A-Z0-9]*(_[A-Z0-9]+)*_[0-9]+).
5. Keywords
Reserved keywords cannot be used as identifiers in any context:
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 withContextual keywords are keywords only inside requirement and policy blocks, and identifiers elsewhere:
active generated human owner proposed purpose regulation source status text to via(v0.3, ADR 0094 rule 6.) gives is a contextual keyword: in edition 0.3, after an operation name inside the brackets of a header's uses (spec/02 §3, spec/05 §3 rule 6), and an identifier everywhere else, in every edition. A program of edition 0.1 or 0.2 that writes it there gets U0103 at the word, "gives is a keyword of edition 0.3 (operation labels)"; the word is not reserved in those editions, so a function, a local or an operation named gives stays accepted.
(v0.3, ADR 0104.) In edition 0.3, measure is a keyword only at the start of a top-level declaration, after an optional pub and before an upper identifier, and of is one after an integer type (spec/25). Both are identifiers elsewhere.
Reserved, not available in v0.1. Using any of these as an identifier or keyword is an error (U0103). The message names either the planned version and feature, or the alternative in Una. It is written `<keyword>` is <message> with the message of the table below, for example `match` is not a keyword in Una; use `when` (ADR 0014).
actor all async await commit costs edit impl iso law loop macro match observe
parallel profile query region return service shared simd table take together
traced trait type unsafe var while| Keywords | Message |
|---|---|
edit, take, region, shared, iso |
reserved for v0.2 (memory model) |
together, parallel, actor |
reserved for v0.2 (concurrency) |
simd, profile |
reserved for v0.2 (systems profile) |
trait, impl |
reserved for v0.2 (constraints on generics) |
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; values are immutable, use let |
while, loop |
not a keyword in Una; use recursion or fold |
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; see structured concurrency in v0.2 |
(2026-11-10, #1899, ADR 0014 Consequences.) The messages of law, all, costs, traced, service, table, query, observe and commit say "reserved for a later edition" instead of naming v0.3 or v0.4, since no release shipped those features; the same holds for shared, iso and weak in edition 0.2 (spec/17 §9). The words stay reserved, with the same code, in every edition.
(v0.2, ADR 0056.) Editions. The keyword tables of this section are those of edition 0.1, and a package of edition 0.1 keeps them in every version of the compiler. Only a package of edition 0.2 (spec/13 §7) gets the memory model's keywords (spec/17). There:
edit,takeandoldbecome keywords;sharedandisomove to v0.3, andweakjoins them;- the messages of
region,var,whileandloopchange.
The new rows are in spec/17 §9. (v0.2, ADR 0065.) In edition 0.2, together also becomes a keyword (spec/19), and the messages of parallel, actor, async and await change (spec/19 §9).
(v0.3, ADR 0105.) In edition 0.3, test is a reserved keyword: the keyword of the test declaration (spec/08 §2), which editions 0.1 and 0.2 write example. A name test there is U0101, as any keyword used as a name: a local bound inside a function body or a handler operation body gets the exact rename to test_value (spec/13 §3, ADR 0096), and a function, a field, a handler, a predicate or a module path segment gets the rename as advice. example stays reserved in edition 0.3, so it never comes back with another meaning: at column 1, where a declaration starts, it is U0103 with the message of the table below and the exact rewrite of the keyword to test, which una fix applies; the declaration is then read as a test's, so its body gets its own checks and no U0101. Anywhere else example is the keyword it is in editions 0.1 to 0.3. Editions 0.1 and 0.2 do not change: test stays an identifier there, and example is the keyword of the test declaration.
| Keywords | Message (edition 0.3) |
|---|---|
example |
written test in edition 0.3 |
(v0.4, ADR 0116.) In edition 0.4, diverges and within are reserved as names (U0103): diverges is a word of a header and within the word of a deadline, and anywhere else neither can be a name (spec/26 §1). (Edition 0.4, ADR 0117 rule 5.) within is the word of a deadline right after for ever and right after a token that ends an expression (a name, a capability reference, a literal, ) or ]): there it is no name, and anywhere else it stays reserved (spec/27 §5). (Edition 0.4, ADR 0117 rule 6.) first, followed by of and the end of its line, opens a race (spec/27 §6); elsewhere first and of are names, so the prelude's first stays a method. (Edition 0.4, ADR 0117 rule 7.) tasks and start begin their statements where spec/27 §7 rule 1 says, and are names elsewhere; the message of async and await becomes not supported; use `tasks` and `start`, or `together` (spec/19 §9). (v0.5, ADR 0120 rule 1, moved from edition 0.4 by ADR 0139.) simd stays reserved in edition 0.4, with the message of the table above, its rename, and the advice to raise the edition of spec/13 §7. In edition 0.5, simd is no longer reserved: it is an identifier, and a contextual keyword only in the simd required clause once that clause lands (spec/29). (v0.5, ADR 0120 rule 2.) In edition 0.5, with and and right before : are also the labels of a call's arguments, as in a.dot(with: b) and c.add_product(of: a, and: b) (spec/29 §17), and keywords everywhere else; in editions 0.1 to 0.4 they are keywords there too, and such a call is a syntax error (U0101). (Edition 0.4, ADR 0105 amendment of 2026-11-05.) In edition 0.4, example is neither a keyword nor reserved: it is an identifier everywhere, so it names a local, a parameter, a function, a field or a module path segment, and a line example "..." at column 1 is an ordinary syntax error (U0101), with no U0103 and no rewrite to test. The test declaration is written test, as in edition 0.3; una fix rewrites example to test in edition 0.3 packages only. (v0.2, ADR 0066.) The message of trait and impl changes too (spec/20 §9). (v0.2, ADR 0069.) In edition 0.2, with right after . is an identifier, the name of a map's method (spec/21 §2), and a keyword everywhere else. The benchmark baseline stays on edition 0.1. (v0.3, ADR 0056 amendment.) Edition 0.3 has the keyword tables of edition 0.2 (spec/13 §7): editions are cumulative.
6. Literals
| Literal | Syntax | Notes |
|---|---|---|
| Integer | 0, 42, 1_000_000 |
Decimal only. _ only between digits. No leading zeros except 0 itself. Negative numbers use unary -. Values are unbounded (ADR 0004). A leading zero, or a doubled, leading or trailing _, is a malformed literal (U0007, ADR 0017). |
| Text | "..." |
Single line. Escapes: \", \\, \n, \t, \{, \}, \u{H..H} (1 to 6 hex digits, valid scalar value). Unknown escape: U0005. Unterminated: U0004. A } outside an interpolation MUST be escaped as \} (U0007, ADR 0017). A { that no expression can follow, a quote, a backslash or a } after any blanks, is a literal brace written without its escape: U0007, with an edit to \{, and the literal continues (#403). |
| Interpolation | "seats {e.remaining}" |
{ expr } inside a text literal. The expression MUST NOT contain a text literal (U0006). A missing } leaves the literal unterminated (U0004 at its opening quote, ADR 0017). |
| Boolean | true, false |
|
| Unit | unit |
The only value of type Unit. |
7. Operators, punctuation and precedence
Punctuation: ( ) [ ] , : -> = | . .. ..< and { } (only inside text literals).
Operator precedence, highest first:
| 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 (chaining is U0101) |
| 6 | not |
prefix |
| 7 | and |
left |
| 8 | or |
left |
| 9 | implies |
right |
Range operators .. (inclusive) and ..< (exclusive upper bound) appear only as the right operand of in, in when arms and in the range sugar of kinds (spec/03 §3). They are not general expressions.