Home / Docs / Language guide / Capabilities and effects
handler
What it does
A handler implements a capability in Una: it gives a body to each operation. A caller installs it for one statement with with, or an example (a test written next to the code) installs it with given, so code that needs the capability runs against the handler instead of the outside world, as a fake store does in a test. Handler bodies are ordinary Una code, fully checked and verified (their contracts proved by the checker).
Learn more: Your own capabilities and handlers.
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")
nameForms
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.
handler_decl = [ "pub" ] "handler" lower_ident "(" [ params ] ")" "for" upper_ident NEWLINE
INDENT { "uses" cap_ref ":" cap_type NEWLINE }
handler_op { handler_op } DEDENT ;
handler_op = "op" lower_ident "(" [ lower_ident { "," lower_ident } ] ")"
"=" inline_or_block ;- Parameters of the handler are captured values, given where it is installed:
fixed(value: "Desk lamp"). for Cnames the capability the handler implements.useslines give the handler capabilities of its own.op name(params) = bodyimplements one operation. Its parameters are written without types: they come from the capability's declaration.
Examples
A handler implements every operation of its capability:
-- fails with U3011
module shop
pub capability Store
op get(key: Text) -> Text
op put(key: Text, value: Text) -> Unit
handler fixed(value: Text) for Store
op get(key) = valueA handler body must keep the operation's ensures, which callers rely on:
-- fails with U5001
module shop
pub capability Store
op get(key: Text) -> Text
ensures result.len > 0
handler blank() for Store
op get(key) = ""Edge cases
Only the capability's operations:
-- fails with U3010
module shop
pub capability Store
op get(key: Text) -> Text
handler fixed(value: Text) for Store
op get(key) = value
op extra(key) = valuefor names a capability:
-- fails with U3010
module shop
pub kind Address
street: Text
handler shipping() for Address
op get(key) = keyFailures of the operation's kind only. An operation body fails only with its operation's error kind, and passes only an equal kind (U3008):
-- fails with U3009
module shop
pub kind StoreError = | Timeout
pub kind PaymentError = | Declined
pub capability Store
op get(key: Text) -> Text
fails StoreError
handler broken() for Store
op get(key) = fail DeclinedFurther rules:
- Not a value. A handler is installed only with
withorgiven. Binding it withletis U2001. - Worst caller. An operation body is checked for the worst caller its operation allows, the caller that passes the most sensitive data the operation accepts: every parameter is raised to the operation's
acceptslabel (how sensitive its data may be). So a handler of an operation that acceptsinternaldata cannot print it, while a fake store that fails or returns fixed values stays valid. - Its own authority. A handler's
usesmust be held where it is installed. - Host capabilities may have user handlers too, such as a fake
Keysin examples. The host implementations are used only byuna runand by an executable thatuna buildmakes.
Diagnostics
- U2001: a handler used as a value.
- U3008: an operation body that passes a failure of another kind.
- U3009: an operation body that fails outside its operation's error kind.
- U3010:
forthat names no capability, or an operation the capability lacks. - U3011: a handler that misses an operation.
- U5001: an operation body that does not keep the operation's
ensures.
Edition
Handlers are the same in editions 0.1 and 0.2.
Normative source
- spec/05 §5: handlers, rules 1 to 5; spec/05 §4: installing with
with; spec/05 §9 rules 3 and 4: reporting. - spec/02 §4: the grammar.
- spec/08 §2:
givenin examples. - spec/12 §3: obligations of handler operations.
- spec/14 §3: host capabilities.