Home / Docs / Language guide

Lexical structure

Release v0.4.0

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.

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.

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:

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

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

Text

Interpolation

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

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:

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