Home / Docs / Language guide / Capabilities and effects

uses

Release v0.4.0Edition 0.1 and laterU1002U3001U3002U3003U3004

What it does

uses @x: C[ops] is the header clause that gives a function authority (the right to act outside the program): inside its body, @x names a capability C, and the body may perform the operations ops on it. There is no ambient authority (no power that code has just by existing, such as a global file system), so a function's capability context is exactly its uses clauses. A line acts outside the program only through an @ operation, or through a call of a function that has uses.

Learn more: Declaring what a function may do: uses in full.

una
module shop

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

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

A call may perform an effect even when its line has no @. Here, emit performs @console.print, and main calls it. Both public headers declare Console[print]. A public caller that leaves it out is U3003, as an example below shows.

una
module shop

pub emit() -> Unit
  uses @console: Console[print]
=
  @console.print("hello")

pub main() -> Unit
  uses @console: Console[print]
=
  emit()

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
clause          = "requires" line_expr NEWLINE
                | "ensures" line_expr NEWLINE
                | "uses" cap_ref ":" cap_type NEWLINE
                | "fails" upper_ident NEWLINE
                | "derived" "from" upper_ident { "," upper_ident } NEWLINE ;
cap_type        = upper_ident [ "[" lower_ident { "," lower_ident } "]" ] ;

Examples

Capabilities pass downward by name. A callee that needs @log gets the caller's @log, with at least the operations it needs:

una
module shop

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

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

pub twice(line: Text) -> Unit
  uses @log: Log
=
  note(line)
  note(line)

An operation outside the clause's list is rejected:

una
-- fails with U3002
module shop

pub capability Store
  op get(key: Text) -> Text
  op put(key: Text, value: Text) -> Unit

pub save(key: Text) -> Unit
  uses @store: Store[get]
=
  @store.put(key, value: "Desk lamp")

Edge cases

A reference must be in scope:

una
-- fails with U3001
module shop

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

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

A public function without uses is pure (it does nothing outside the program). In a pub function, which declares its uses, an @ is rejected:

una
-- fails with U3004
module shop

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

pub note(line: Text) -> Unit = @log.write(line)

A call with effects needs the caller's uses. A pure pub function cannot call a function with effects:

una
-- fails with U3003
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 = note(line)

One clause per reference:

una
-- fails with U1002
module shop

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

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

Further rules:

Diagnostics

Edition

uses is the same in editions 0.1 and 0.2. Edition 0.2 adds uses of p. Edition 0.3, a preview, adds conditions on operations, as Catalog[price, set_price where not dry_run], which the checker proves wherever the operation may run, and lets una.toml lock the uses of public functions under [contracts], so that a header granting more than its lock is an error. See Conditions on operations.

Normative source