Home / Docs / Language guide / Capabilities and effects

capability and op

Release v0.4.0Edition 0.1 and laterU1002U3002U5001

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.

una
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 ""
  found

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
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:

una
-- 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:

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

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:

una
-- fails with U1002
module shop

pub kind Store = | Empty

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

Further rules:

Diagnostics

Edition

Capabilities are the same in editions 0.1 and 0.2. Edition 0.2 adds the host capability Http.

Normative source