Home / Docs / Language guide

Expressions and control flow

Release v0.4.0

5.1 Blocks, let and statements

A block is a sequence of statements followed by a final expression, which is the block's value.

una
module demo

pub kind Seats = Int in 0..5000

pub kind Availability = SoldOut | Few | Open

pub kind Event
  name: Text
  remaining: Seats

clamp_seats(raw: Int) -> Seats = if raw < 0 then 0 else if raw > 5000 then 5000 else raw

availability(e: Event) -> Availability = if e.remaining == 0 then SoldOut else if e.remaining < 20 then Few else Open

pub status(n: Text, raw: Int) -> Availability
=
  let seats = clamp_seats(raw)
  let event: Event = Event(name: n, remaining: seats)
  availability(event)

5.2 if

una
module demo

pub size(n: Int) -> Text = if n > 100 then "large" else "small"

pub band(n: Int) -> Text
=
  if n > 100
    "large"
  else if n > 10
    "medium"
  else
    "small"

5.3 when

una
module demo

pub kind Seats = Int in 0..5000

pub kind Availability = SoldOut | Few | Open

pub kind Registration
  name: Text

pub kind Lookup = Found(registration: Registration) | Missing

--- Variants.
pub label(status: Availability) -> Text
=
  when status
    is SoldOut -> "sold out"
    is Few -> "few seats left"
    is Open -> "open"

--- A payload bound by its field name, or under another name.
pub name_of(lookup: Lookup) -> Text
=
  when lookup
    is Found(registration) -> registration.name
    is Missing -> "unknown"

pub name_again(lookup: Lookup) -> Text
=
  when lookup
    is Found(registration: r) -> r.name
    is Missing -> "unknown"

--- Ranges, proven to cover every `Seats` value.
pub band(remaining: Seats) -> Availability
=
  when remaining
    in 0..0 -> SoldOut
    in 1..<20 -> Few
    in 20..5000 -> Open

--- Literals, with `else`.
pub reason(code: Int) -> Text
=
  when code
    is 200 -> "ok"
    is 404 -> "not found"
    else -> "other"

--- A block arm.
pub greeting(status: Availability) -> Text
=
  when status
    is SoldOut ->
      let note = "try another date"
      note
    else -> "welcome"

Rules:

5.4 One effect per line

A capability operation, a call to a function that uses capabilities or can fail, or a call with an edit or take argument, must be the whole expression of a statement, a let or a final expression, optionally wrapped in attempt (U3013). It cannot be nested inside another expression.

una
module demo

pub kind Availability = SoldOut | Few | Open

pub kind Registration
  name: Text
  status: Availability

pub kind StoreError = | Timeout

pub kind CheckInError = NotRegistered | Unavailable

pub capability Registrations
  op find(key: Text) -> Option[Registration]
    fails StoreError

pub status_of(key: Text) -> Availability
  uses @registrations: Registrations[find]
  fails CheckInError
=
  let registration = @registrations.find(key)
    if error fail Unavailable
    if none fail NotRegistered
  registration.status
una
-- fails with U3013
module demo

pub capability Store
  op get(key: Text) -> Int

double(x: Int) -> Int = x * 2

pub doubled(key: Text) -> Int
  uses @store: Store[get]
=
  double(@store.get(key))

This fixes evaluation order, gives every failure a handling site and makes every effect visible on its own line. Pure calls nest freely. Example do lines are exempt (§10).

5.5 for loops (edition 0.2)

for x in xs visits the elements of a list in order, and for i in a..<b or for i in a..b the integers of a range in increasing order (spec/17 §1, §4).

una
module demo

--- A `for` loop over a list, updating a `let edit` binding.
pub total(xs: List[Int]) -> Int
=
  let edit sum = 0
  for x in xs
    sum = sum + x
  sum

--- Over a range: `a..<b` excludes `b`, `a..b` includes it. The bounds are evaluated once.
pub squares(n: Int) -> List[Int]
=
  let edit out: List[Int] = []
  for i in 0..<n
    out = out.append(item: i * i)
  out

--- The loop variable takes the integer type of the bounds: here `U8`.
pub bytes(low: U8, high: U8) -> List[U8]
=
  let edit out: List[U8] = []
  for b in low..high
    out = out.append(item: b)
  out

--- An `if` without `else` is a statement.
pub count_large(xs: List[Int], limit: Int) -> Int
=
  let edit count = 0
  for x in xs
    if x > limit
      count = count + 1
  count

5.6 Mutable value semantics (edition 0.2)

Una has no references and no lifetimes: values stay values, and a binding declared editable can be rebound (ADR 0056, spec/17).

una
module demo

pub kind Tally
  seen: Int
  last: Int

--- An `edit` parameter is passed in and out; `old(t)` is its value on entry.
pub record(edit t: Tally, value: Int) -> Unit
  ensures t.seen == old(t).seen + 1
=
  t.seen = t.seen + 1
  t.last = value

pub tally(xs: List[Int]) -> Tally
=
  let edit t = Tally(seen: 0, last: 0)
  for x in xs
    edit t.record(value: x)
  t

--- `take` consumes its argument: the caller cannot use it afterwards.
pub finish(take t: Tally) -> Int = t.seen

pub summary(xs: List[Int]) -> Int
=
  let t = tally(xs)
  let n = finish(take t)
  n

--- List elements change through `set`.
pub reset_first(xs: List[Int]) -> List[Int]
=
  let edit ys = xs
  if ys.len > 0
    edit ys.set(index: 0, item: 0)
  ys
una
-- fails with U2017
module demo

pub finish(take xs: List[Int]) -> Int = xs.len

pub twice(xs: List[Int]) -> Int
=
  let n = finish(take xs)
  xs.len + n
una
-- fails with U2019
module demo

pub bump(x: Int) -> Int
=
  let n = x
  n = n + 1
  n

A backend may update a uniquely held value in place, and reuse the memory of a value passed by take. None of this is observable.

5.7 Concurrent tasks with together (edition 0.2)

together runs independent work as concurrent tasks, and every task ends before its block does (ADR 0065, spec/19). A program's result and its trace are those of running the tasks one after another, in order.

una
module demo

pub capability Sensor
  op reading() -> Int

pub kind FetchError = Missing | Gone

handler fixed(value: Int) for Sensor
  op reading() = value

pub warmest() -> Int
  uses @north: Sensor[reading]
  uses @south: Sensor[reading]
=
  together
    let north = reading() with @sensor = @north
    let south = reading() with @sensor = @south
  max(north, b: south)

reading() -> Int
  uses @sensor: Sensor[reading]
=
  @sensor.reading()

fetch(id: Int) -> Int
  fails FetchError
=
  if id < 0
    fail Missing
  else
    id * 10

--- One task per element; the results come back in list order.
pub pages(ids: List[Int]) -> List[Int]
  fails FetchError
=
  let pages = together for id in ids
    fetch(id)
      if error pass
  pages

--- Over a range, the variable takes the integer type of the bounds.
pub doubled(n: U8) -> List[Int]
=
  let out = together for i in 0..<n
    i.to_int() * 2
  out
una
-- fails with U2023
module demo

bump(edit n: Int) -> Int
=
  n = n + 1
  n

pub count(xs: List[Int]) -> Int
=
  let edit seen = 0
  together
    let a = xs.len
    let b = bump(edit seen)
  seen + a + b
una
-- fails with U2024
module demo

pub one() -> Int
=
  together
    let a = 1
  a

Constructs