Home / Docs / Language guide / Capabilities and effects
capability and op
What it does
A capability is unforgeable authority (no code can make one up: a function gets it from its caller, and main from the runtime) over something outside the program, such as a store, a clock or a network. capability C declares the operations that authority allows, each with op: an operation is one action on the outside world, such as reading a key. Code acts outside the program only through an operation of a capability it holds, written @name.op(...). Every such call is an effect (an action outside the program), recorded in the program's trace (the list of effects a run performed, in order).
Learn more: Your own capabilities and handlers. Related pages: uses, handlers and with.
module shop
pub kind StoreError = | Timeout
pub capability Store
op get(key: Text) -> Option[Text]
fails StoreError
op put(key: Text, value: Text) -> Unit
fails StoreError
pub read(key: Text) -> Text
uses @store: Store[get]
fails StoreError
=
let found = @store.get(key)
if error pass
if none use ""
foundForms
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.
capability_decl = [ "pub" ] "capability" upper_ident NEWLINE
INDENT op_decl { op_decl } DEDENT ;
op_decl = "op" lower_ident "(" [ params ] ")" "->" type NEWLINE
[ INDENT op_clause { op_clause } DEDENT ] ;
op_clause = "requires" line_expr NEWLINE
| "ensures" line_expr NEWLINE
| "fails" upper_ident NEWLINE
| "accepts" label NEWLINE ;An operation's clauses mean:
| Op clause | Meaning |
|---|---|
requires p |
Precondition over arguments; an obligation (a fact the checker must prove) at every call site |
ensures q |
Postcondition (a promise about the result) over arguments and result. It is an assumption about the external system: callers may rely on it, handlers (code that implements the capability in Una) are verified against it, host implementations are trusted to satisfy it |
fails E |
The operation may fail with variants of E |
accepts l |
Upper bound on the labels of arguments (the sink label: how sensitive the data an operation receives may be). Default: public |
Operation clauses come in a fixed order: every requires, every ensures, at most one fails, at most one accepts.
Examples
An operation's ensures is a fact for its callers. A handler of the capability must keep it, so a handler that cannot is refuted:
-- fails with U5001
module shop
pub capability Store
op get(key: Text) -> Text
ensures result.len > 0
handler blank() for Store
op get(key) = ""A function uses only the operations its uses clause lists:
-- 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
One name per declaration. A capability shares the upper-case namespace of kinds and their variants, and a name defined twice in a module is rejected:
-- fails with U1002
module shop
pub kind Store = | Empty
pub capability Store
op get(key: Text) -> TextFurther rules:
- Assumed, and reported. Every capability the package declares is listed under
assumptionsinuna report, with its operations and theirensures, since those describe a system outside the program. - Sinks. A sink is a place where data leaves the program.
acceptsbounds the labels of the arguments, so an operation that accepts onlypubliccannot receivesecretdata. - Host capabilities such as
ConsoleandFilesare declared in the modulestd.hostand implemented by the runtime. See host capabilities and grants.
Diagnostics
- U1002: a capability whose name is already defined in the module.
- U3002: an operation that the
usesclause does not permit. - U5001: a handler operation that does not keep the operation's
ensures.
Edition
Capabilities are the same in editions 0.1 and 0.2. Edition 0.2 adds the host capability Http.
Normative source
- spec/05 §1: the model; spec/05 §2: declarations; spec/05 §3: using capabilities; spec/05 §5: handlers.
- spec/02 §4: the grammar.
- spec/07 §4: sinks; spec/13 §6: the build report and its
assumptions. - spec/10 §11 rule 1: the upper-case namespace of kinds, variants and capabilities; rule 5: duplicate names.
- spec/14 §3: the host capabilities, and
Httpfrom edition0.2.