Home / Docs / Language guide / Expressions and control flow
let edit and edit parameters
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.
let edit x = edeclares a binding that assignments may rebind:x = e.- A place, an editable binding or a path of fields inside one, as
t.last, can be assigned too:t.last = valuerebuildstwith that field changed. - An
editparameter is passed in and out. The function receives the caller's value, and the caller's place receives its final value.
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)
tForms
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.
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 } ;let edit x = e, orlet edit x: T = ewith a type that fixes a refinement as an invariant.p = e, wherepis an editable binding or a field path of one.edit x: Tin a parameter list, andedit pat the matching argument. A method receiver is writtenedit t.record(...).old(x)in anensuresclause: the value of theeditparameterxon entry.
Examples
A list's elements change through set, never by assignment:
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)
updatedOnly an editable binding can be assigned:
-- fails with U2019
module shop
pub next_order(last: Int) -> Int
=
let order = last
order = order + 1
orderThe caller writes edit exactly where the parameter is declared edit:
-- 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)
copyA 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:
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.writeOnly 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:
-- 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:
-- 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 = recordFurther rules:
- Fixed type. An editable binding keeps its declared type, refinement and label at every rebind. Each rebind carries the obligation of an annotated
let. Without an annotation, its type is its initial value's without the refinement. In edition0.3, it also drops the refinements of nested positions, aslet edit xs = [p]is aList[Int], and an annotation such aslet edit out: List[Pos] = []keeps them. - Fields of records only. A place's fields are fields of record kinds; a field of a variant payload is not a place.
- No compound assignment, and no assignment to a list element: elements change through
set. - Lambdas capture values. A lambda captures an editable binding's value when it is created, and cannot edit it (U2019).
- Transactional. A call that fails leaves its
editarguments unchanged for the caller. Effects already performed stay performed. - Labels are fixed. A rebind under a program counter (the label of the conditions that decide whether the line runs; see Branches and failures: implicit flows) above the binding's label is U4001, never a silent raise.
- Not on operations. Capability operations and handlers cannot declare
editortakeparameters (U2020). - One effect per line. A call with an
editargument is the whole expression of a statement orlet(U3013).
Diagnostics
- U0103:
editin edition0.1, where it is reserved. - U2018: an
editargument used again in the same call. - U2019: an assignment to a binding that is not editable.
- U2020: a missing or extra
editmarker, or aneditargument that is not a place. - U2021: a function with conventions used as a value.
- U3013: a call with an
editargument inside a larger expression. - U4001: a rebind under a program counter above the binding's label.
Edition
let edit, assignments and edit parameters exist from edition 0.2 on. In edition 0.1, edit is reserved:
-- edition 0.1
-- fails with U0103
module shop
pub next_order(last: Int) -> Int
=
let edit order = last
order = order + 1
orderNormative source
- spec/17 §1: syntax; spec/17 §2: places and editable bindings; spec/17 §3: parameter conventions.
- spec/17 §5: static semantics; spec/17 §6: information flow; spec/17 §7: dynamic semantics.
- spec/04 §2:
oldinensures. - Decision record: ADR 0056, for the memory model of edition
0.2; ADR 0103, for nested refinements in edition0.3.