Home / Docs / Language guide / Capabilities and effects

@ bindings and with

Release v0.4.0Edition 0.1 and laterU1002U2001U3001U3005U3006U3010U3016U3020U3024

What it does

A capability reference, @name, is a name for authority (the right to act outside the program), not a value. Capabilities pass downward by name: a callee that says uses @x: C[ops] gets the caller's @x. with changes what the callee's name refers to, for one statement:

Learn more: Passing authority: with, rebinding and narrowing.

una
module shop

pub capability Log
  op write(line: Text) -> Unit

note(line: Text) -> Unit
  uses @log: Log[write]
=
  @log.write(line)

pub caller(line: Text) -> Unit
  uses @audit: Log[write]
=
  note(line) with @log = @audit

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
handled         = line_expr [ with_clause ] NEWLINE [ INDENT handling { handling } DEDENT ] ;
with_clause     = "with" cap_binding { "," cap_binding } ;
cap_binding     = cap_ref "=" ( cap_ref | handler_call ) ;

Examples

A handler installed for one call. The handler's operations run in place of a real store:

una
module shop

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

handler fixed(value: Text) for Store
  op get(key) = value

read(key: Text) -> Text
  uses @store: Store[get]
=
  @store.get(key)

pub preview_name() -> Text
=
  let name = read("LAMP-01") with @store = fixed(value: "Desk lamp")
  name

Both sides of a rebinding have the same capability:

una
-- fails with U3001
module shop

pub capability Log
  op write(line: Text) -> Unit

pub capability Ticker
  op now() -> Int

note(line: Text) -> Unit
  uses @log: Log[write]
=
  @log.write(line)

pub caller(line: Text) -> Unit
  uses @ticker: Ticker[now]
=
  note(line) with @log = @ticker

Edge cases

References are second-class (usable only in the few places the language allows, never as ordinary data). A capability reference cannot be bound with let, passed as an ordinary argument, returned, stored, compared or interpolated:

una
-- fails with U3005
module shop

pub capability Log
  op write(line: Text) -> Unit

pub keep() -> Unit
  uses @log: Log[write]
=
  let saved = @log
  unit

So are effectful function values (function values that act outside the program or can fail). A function value with uses or fails may only be called, or passed directly as an argument. It never outlives the with scope it was created in:

una
-- fails with U3006
module shop

pub capability Log
  op write(line: Text) -> Unit

pub keep(writer: fn() -> Unit uses @log: Log[write]) -> Unit
  uses @log: Log[write]
=
  let later = writer
  later()

Handlers are not values. A handler is installed with with, or with given in an example:

una
-- fails with U2001
module shop

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

handler fixed(value: Text) for Store
  op get(key) = value

pub keep() -> Unit
=
  let catalog = fixed(value: "Desk lamp")
  unit

Further rules:

Diagnostics

Edition

with and the second-class rule are the same in editions 0.1 and 0.2. From edition 0.3, a preview, the language adds the narrowed rebinding with @x = @y[ops], which gives the callee the caller's @y restricted to ops, and checks each call into a boundary (a group of modules whose authority una.toml, or from edition 0.4 ita.una, caps) against that cap. A call into a boundary gets no capability by name, so each one it needs is passed with with (U3020), and no policy call may be reachable from it (U3024). See Granting less at the call and [boundaries].

Normative source