Home / Docs / Language guide / Expressions and control flow

let edit and edit parameters

Release v0.4.0Edition 0.2 and laterU0103U2018U2019U2020U2021U3013U4001

What it does

From edition 0.2, values stay values: there are no references (names that share one value, so that a change through one shows through the other) and no lifetimes (rules for how long such a sharing name stays valid), and an editable binding can be rebound, which means the name is given a new value.

Learn more: Passing a value in and out: edit.

una
module shop

pub kind Visits
  seen: Int
  last: Int

pub record(edit t: Visits, value: Int) -> Unit
  ensures t.seen == old(t).seen + 1
=
  t.seen = t.seen + 1
  t.last = value

pub visits_of(stamps: List[Int]) -> Visits
=
  let edit t = Visits(seen: 0, last: 0)
  for stamp in stamps
    edit t.record(value: stamp)
  t

Forms

In the grammar below, each rule gives a name, =, what the name stands for and ;, quoted words are written as shown, NEWLINE, INDENT and DEDENT stand for a line break and for one more or one less level of indentation, [ ] marks an optional part, { } a part that may repeat, | separates alternatives, ( ) groups them, and (* *) holds a comment.

ebnf
param           = [ "edit" | "take" ] lower_ident ":" type ;
arg             = [ lower_ident ":" ] ( "edit" place | "take" lower_ident | line_expr ) ;
place           = lower_ident { "." lower_ident } ;
let_stmt        = "let" [ "edit" ] lower_ident [ ":" type ] "=" ( handled | block_expr ) ;
assign_stmt     = place "=" ( handled | block_expr ) ;
postfix         = [ "edit" ] primary { "." lower_ident [ call_args ] | call_args } ;

Examples

A list's elements change through set, never by assignment:

una
module shop

pub clear_first(prices: List[Int]) -> List[Int]
=
  let edit updated = prices
  if updated.len > 0
    edit updated.set(index: 0, item: 0)
  updated

Only an editable binding can be assigned:

una
-- fails with U2019
module shop

pub next_order(last: Int) -> Int
=
  let order = last
  order = order + 1
  order

The caller writes edit exactly where the parameter is declared edit:

una
-- fails with U2020
module shop

pub kind Visits
  seen: Int

pub record(edit t: Visits) -> Unit
=
  t.seen = t.seen + 1

pub log_visit(t: Visits) -> Visits
=
  let edit copy = t
  record(copy)
  copy

A failed call rolls back edits, not completed effects

An edit argument is transactional for the caller: if the call fails, its local value is unchanged. An effect already performed through a capability is external and remains performed. This example uses a test handler to make that distinction visible:

una
module demo

pub kind StoreError = | Rejected

pub capability Store
  op write(value: Int) -> Unit

pub update(edit current: Int) -> Unit
  uses @store: Store[write]
  fails StoreError
=
  current = current + 1
  @store.write(current)
  fail Rejected

pub scenario() -> Int
  uses @store: Store[write]
=
  let edit value = 10
  update(edit value)
    if error use unit
  value

handler store() for Store
  op write(value) = unit

example "local rollback preserves an already performed effect"
  given @store = store()
  do scenario()
  expect result == 10
  expect performed @store.write

Only the caller's edit arguments are restored (spec/17 §7 rules 1 and 2). An operation performed before the failure stays performed, and the trace records it; Una rolls back nothing in an external system. Undoing it takes another operation, which can fail in turn.

Edge cases

Exclusivity. An edit p argument excludes every other use of p's root binding in the same call, even of a disjoint field:

una
-- fails with U2018
module shop

pub kind Visits
  seen: Int
  last: Int

pub record(edit t: Visits, value: Int) -> Unit
=
  t.seen = t.seen + 1
  t.last = value

pub record_own_count(edit t: Visits) -> Unit
=
  record(edit t, value: t.seen)

Not a value. A function with an edit or take parameter can only be called, not passed or returned:

una
-- fails with U2021
module shop

pub kind Visits
  seen: Int

pub record(edit t: Visits) -> Unit
=
  t.seen = t.seen + 1

pub recorder() -> fn(Visits) -> Unit = record

Further rules:

Diagnostics

Edition

let edit, assignments and edit parameters exist from edition 0.2 on. In edition 0.1, edit is reserved:

una
-- edition 0.1
-- fails with U0103
module shop

pub next_order(last: Int) -> Int
=
  let edit order = last
  order = order + 1
  order

Normative source