Home / Learn / 12 Capabilities
12.1 Declaring what a function may do: uses in full
Page 2 of 10
12.1.1 What an effect is
Most of what a program does happens inside it: adding prices, building a line of text, choosing a branch. Some of what it does reaches outside: it prints a line on the screen, writes a file, asks the clock for the time, or sends a message to another computer. Each of these is an effect: something the program does to, or learns from, the world outside it. A function with no effects can only compute its result. Call it twice with the same arguments and it gives the same answer, and nothing else in the world changes.
Una treats effects as authority that must be handed out, the way a store hands out keys. A cashier's keycard opens the till and the front door, and not the stockroom or the office safe. Anyone can read on the card what it opens, and nobody gets in anywhere without one. Chapter 1 used one such card, the console. This chapter names every part, and uses these words throughout:
- A capability is the authority to do one kind of thing outside the program, such as printing to the console or reading the clock.
ConsoleandClockare capabilities. - An operation is one thing a capability can do:
printis an operation ofConsole, andnowis an operation ofClock. - A binding is the name a function uses for a capability it holds. It always starts with
@, as in@console. You perform an operation on a binding:@console.print("…"). - A
usesclause is a line of a function's header that names a binding, its capability, and the operations the function may perform with it:uses @console: Console[print].
The uses clauses of a header are the function's keycard: the complete list of what it may do outside the program. Each step of this chapter is a package, made as chapter 2 explains, and the manifest of a step that prints grants the console, as section 12.2 explains.
12.1.2 Why a header lists effects
In most languages any function may print, write a file or open a network connection, and nothing in its header says so. To learn what a function does outside the program, you read its body, and the body of every function it calls, and theirs. A helper that only formats a line today can start sending data somewhere tomorrow, and the change shows nowhere but in that one body.
Here is that change in Una. slip_line builds one line of a packing slip, and its header promises a text and nothing else. Someone adds a line that prints, to see what the function is doing:
module slips
--- One line of a packing slip. Its header promises a text, and nothing else.
pub slip_line(sku: Text, quantity: Int) -> Text
=
@console.print("building the line for {sku}")
"{quantity} x {sku}"
pub main() -> Unit
uses @console: Console[print]
=
@console.print(slip_line("LAMP-01", quantity: 2))una check . refuses it:
[U3004] Error: `@console` is used here, but this code declares no `uses`, so it is pure
╭─[ src/slips.una:6:3 ]
│
6 │ @console.print("building the line for {sku}")
│ ────┬───
│ ╰───── `@console` is used here, but this code declares no `uses`, so it is pure
│
│ Help: repair 1 (widens authority: the function then holds this authority, and every caller must hold it too: check that the operation belongs to this function's job): declare `uses @console: ...` in the header, with the capability and the operations used
│
│ Note: run `una explain U3004` for an explanation
───╯You met U3004 in section 1.5 and section 6.3. Read it now as a reviewer would. The message names the binding, @console, and the reason: the function "declares no uses, so it is pure". The mark points at @console in the body. The help line is the repair: declare a uses line in the header. It is marked "widens authority", because the repair gives the function more power, and every caller must then hold that power too. Whether the function should print is a decision for its author, so the checker does not make it.
So a header that says nothing about effects is a promise: the function has none. A header that lists uses @console: Console[print] is a promise too: the function may print, and do nothing else outside the program. The checker holds every body to its header, so a reviewer learns what a function may do from the header alone.
12.1.3 How to write uses
12.1.3.1 The parts of a uses line
A uses clause sits under the header, with the other clauses, before =. Take uses @files: Files[read, write]:
usesstarts the clause.@filesis the binding: the name the body uses for the capability. You choose it.@filesis the usual name forFiles, and a name such as@auditcan say what a capability is for.: Filesis the capability.[read, write]lists the operations the function may perform, separated by commas.
A function written in the long form (section 6.2) has its clauses on their own lines, each indented two spaces. When a function has several kinds of clause, they go in this order: requires, ensures, uses, fails, then derived from.
The step of this part shows every form. It is a small back room of a store: it announces restocked items, and it saves a count to a file. Its manifest grants the console and the files of src/, which section 12.2 explains:
[package]
name = "backroom"
version = "0.1.0"
edition = "0.2"
[run]
entry = "backroom"
grants = ["console", "files:src:read,write"]12.1.3.2 No uses: a pure function
A function without uses is pure: it can only compute its result.
--- No `uses`: a pure function. It can only compute its result.
shelf_tag(sku: Text) -> Text = "[{sku}]"12.1.3.3 One operation
The brackets hold one operation. announce may print, and nothing else:
--- One operation of one capability: it may print, and nothing else.
announce(sku: Text) -> Unit
uses @console: Console[print]
=
@console.print("restocked {shelf_tag(sku)}")@console.print(…) performs the operation on the binding. A call of a pure function, shelf_tag(sku), may stand inside its arguments.
12.1.3.4 Several operations of one capability
List them in one pair of brackets. copy_count reads a file and writes another, so it needs both operations of Files:
--- Two operations of one capability, in one pair of brackets.
copy_count(source: Text, to: Text) -> Unit
uses @files: Files[read, write]
fails FileError
=
let count = @files.read(source)
if error pass
@files.write(to, content: count)
if error passBoth operations of Files can fail, with FileError, so copy_count declares fails FileError and passes each failure on with if error pass, as section 7.3 shows.
12.1.3.5 Every operation: no brackets
Without brackets, the function may perform every operation of the capability, including any the capability gains later:
--- No brackets: every operation of the capability, now and later.
announce_all(skus: List[Text]) -> Unit
uses @console: Console
=
for sku in skus
@console.print("restocked {shelf_tag(sku)}")Console has one operation today, print, so Console and Console[print] allow the same thing now. They differ when the capability grows: the first header would allow the new operation at once, and the second would not.
12.1.3.6 Several capabilities
Write one uses line per binding. save_and_say writes a file and prints:
--- Two capabilities, one `uses` line each.
save_and_say(sku: Text, units: Int) -> Unit
uses @files: Files[write]
uses @console: Console[print]
fails FileError
=
@files.write("count.txt", content: "{sku},{units}")
if error pass
@console.print("saved the count of {sku}")12.1.3.7 No uses line on a private function
A private function may leave its uses out, and the checker infers them, as section 6.3 shows: the fewest that cover its body and the functions it calls. The back room has one such function, close_shelf, which the check-yourself question of this section asks about.
12.1.3.8 Running the forms
main holds @console and @files, and calls each function:
pub main() -> Unit
uses @console: Console[print]
uses @files: Files[read, write]
=
announce("LAMP-01")
announce_all(["DESK-02", "RUG-07"])
save_and_say("LAMP-01", units: 4)
if error use unit
copy_count("count.txt", to: "count-copy.txt")
if error use unit
@console.print("copied the count")
close_shelf("RUG-07", units: 9)
if error use unituna run . prints:
restocked [LAMP-01]
restocked [DESK-02]
restocked [RUG-07]
saved the count of LAMP-01
copied the count
restocked [RUG-07]
saved the count of RUG-07The count and its copy land in src/count.txt and src/count-copy.txt. main passes each failure of a file to if error use unit, which goes on as if the line had done nothing: a back room that cannot save a count still announces its stock.
12.1.4 A packing slip
Now the clauses at work on a packing slip. A packing slip has a title and one line per item. Building a line is pure computation. Printing it is an effect, and the header says so:
module slips
--- One line of a packing slip. Pure: it has no `uses`, so all it can do is compute a value.
slip_line(sku: Text, quantity: Int) -> Text = "{quantity} x {sku}"
--- Prints one line of a packing slip. It may print, and nothing else.
print_line(sku: Text, quantity: Int) -> Unit
uses @console: Console[print]
=
@console.print(slip_line(sku, quantity: quantity))
pub main() -> Unit
uses @console: Console[print]
=
@console.print("Packing slip for order A-1001")
print_line("LAMP-01", quantity: 2)
print_line("DESK-02", quantity: 1)slip_line(sku: Text, quantity: Int) -> Text. Nouses, so the body may not perform any operation. It builds a text and returns it.uses @console: Console[print]. This line givesprint_linea binding named@console, of the host capabilityConsole, with the one operationprint.@console.print(slip_line(sku, quantity: quantity)). The operation, with the pure function's result as its argument.print_line("LAMP-01", quantity: 2)inmain.mainholds@console, andprint_lineneeds@console, so the call passes it on by name. Nothing else is written at the call.
una run . prints:
Packing slip for order A-1001
2 x LAMP-01
1 x DESK-0212.1.5 How uses behaves
12.1.5.1 Bindings are found by name
A call hands the callee the bindings its header asks for, by name, never by type. If print_line asked for @out: Console[print], the call in main would not check: main holds a @console, not an @out. Section 12.4 shows how to hand a binding over under another name, and forgetting to hand over a binding shows the diagnostic, U3001.
12.1.5.2 A caller holds at least what its callees use
A caller must hold every binding its callees need, with at least the operations they list. main may call print_line because it holds @console with print. A function that holds Customers[find] cannot call one that needs Customers[forget]: that is U3002, which using an operation the header does not list shows. So the effects of a function include the effects of every function it calls, and its header covers them all.
12.1.5.3 Written or inferred, the header is exact
A pub function writes every uses itself, and one with no uses is pure. A private function with no uses line gets the inferred ones, and may do exactly that much. A private function that writes at least one uses line has exactly the ones it writes: nothing more is inferred for it. This book writes uses on private functions too whenever their effects are part of what a reader should know.
12.1.6 How many operations to allow
Which to use:
| You want… | Write |
|---|---|
| A function that only computes | No uses |
| One operation of a capability | uses @x: C[op] |
| Several operations | uses @x: C[op1, op2] |
| Every operation, now and when the capability gains more | uses @x: C, without brackets |
| A private helper whose effects are obvious from its body | No uses line; let the checker infer it |
List the operations you need. A header with brackets also tells the reader what the function does not do, and it keeps saying so when the capability gains an operation.
12.1.7 Check yourself: uses
close_shelf, in the back room's step, writes no uses and is private. It calls announce, then save_and_say:
--- Closes a shelf for the night. It writes no `uses`, so una infers them.
close_shelf(sku: Text, units: Int) -> Unit
=
announce(sku)
save_and_say(sku, units: units)
if error passWhich uses and which fails does the checker infer for it?
Show the answer
The union of what its callees need: @console with print, which both callees use, and @files with write, from save_and_say. save_and_say can fail with FileError, and if error pass passes that failure on, so fails FileError is inferred too:
$ una contract backroom.close_shelf
--- Closes a shelf for the night. It writes no `uses`, so una infers them.
close_shelf(sku: Text, units: Int) -> Unit
uses @console: Console[print] -- inferred
uses @files: Files[write] -- inferred
fails FileError -- inferredread is not in the list: no callee of close_shelf reads a file.
A second one: may announce_all call copy_count, without changing its header?
Show the answer
No. copy_count needs @files with read and write, and announce_all holds only @console. A caller must hold every binding its callees use, so una check . reports U3001 at the call: copy_count needs @files, "which is not in scope here". To make the call, announce_all would have to declare uses @files: Files[read, write] too, and handle or declare the FileError of the call, and every caller of announce_all would then need them as well.