Home / Docs / Language guide
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 fmtjoins them, anduna checkreports 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).
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)
sum1.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(notEvents_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:
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 withKeywords 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):
active generated human owner proposed purpose regulation source status text to viaEq, 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-128fitsI8. Intis 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
letfirst. - Any value that holds no function and no
Hashedcan be interpolated (U2001 otherwise). It is written in its Una form, asuna testshows it:Event(name: "Gala", remaining: 3),[1, 2],Some(3). ATextinside it is quoted. A value of a type parameterTneeds[T: Eq](U2026). In edition 0.1, only integers,BoolandTextcan be interpolated (ADR 0068). - A missing closing
}is reported as U0004 at the opening quote. - Interpolation propagates labels:
"id {phone}"is as secret asphone(§8).
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 < 10is U0101; write0 < x and x < 10, orx in 1..<10. notbinds looser than comparisons.not a == bmeansnot (a == b).impliesgroups to the right.a implies b implies cmeansa implies (b implies c).and,orandimpliesshort-circuit.- Division and
modare Euclidean, so the remainder is never negative:-7 / 2 == -4and-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 + bwitha: U8andb: U16is U2001: convert one of them (§3.1). - Ranges:
a..bincludesb;a..<bexcludes it. Ranges appear afterin, inwhenarms, in kind sugar, and as the source offorandtogether for(§5.5, §5.7). They are not values. istests 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 |