Home / Docs / Language guide / Capabilities and effects
uses
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.
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.
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.
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 } "]" ] ;uses @x: C[op1, op2]permits the listed operations.uses @x: C, without brackets, permits every operation ofC.- A function may have several
usesclauses, one per reference. They come afterrequiresandensures, and beforefails. uses of p(from edition0.2on): the function performs the effects (actions outside the program) of its parameterp, a function value.
Examples
Capabilities pass downward by name. A callee that needs @log gets the caller's @log, with at least the operations it needs:
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:
-- 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:
-- 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:
-- 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:
-- 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:
-- 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:
- Inferred for private functions. A private function without
usesgets the least set that covers its operations and its callees' requirements. Apubfunction declares everyuses. - Attenuation (narrowing what a callee may do). Passing a capability with more operations than the callee needs is allowed, and the callee can use only its own list.
- Rebinding. A caller can give a callee another reference, or a handler, with
with. See@bindings andwith. - Host capabilities reach a program only through
main'suses, from the runtime's grants. See host capabilities and grants.
Diagnostics
- U1002: a reference bound twice in one header.
- U3001: a reference that is not in scope, or of another capability than the callee needs.
- U3002: an operation that the clause does not permit, or a callee that needs more operations.
- U3003: a call whose effects exceed the caller's header.
- U3004: an
@in code whose header declares nouses.
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
- spec/05 §1: the model; spec/05 §3: using capabilities, and in edition
0.3rules 4 and 5, conditions on operations and locked contracts; spec/05 §4: passing capabilities; spec/05 §9: reporting. - spec/04 §2 rule 4: pure functions; spec/04 §5: inference.
- spec/02 §3: the grammar and clause order.
- Decision records: ADR 0062, for
uses of; ADR 0092, for conditions on operations and locked contracts.