---
title: "12.1 Declaring what a function may do: uses in full"
url: https://una-lang.org/en/learn/capabilities/declaring-what-a-function-may-do-uses-in-full/
release: v0.4.0
edition: "0.2"
---

# 12.1 Declaring what a function may do: uses in full

## 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](https://una-lang.org/en/learn/hello/printing-the-console-print-and-uses/#s1-5) 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. `Console` and `Clock` are capabilities.
- An **operation** is one thing a capability can do: `print` is an operation of `Console`, and `now` is an operation of `Clock`.
- 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 **`uses` clause** 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](https://una-lang.org/en/learn/numbers/values-types-and-names-let/#each-step-is-a-package) explains, and the manifest of a step that prints grants the console, as [section 12.2](https://una-lang.org/en/learn/capabilities/the-hosts-capabilities-and-grants/#s12-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:

```una include="steps/01-hidden-effect/src/slips.una" title="steps/01-hidden-effect/src/slips.una"
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:

```text include="steps/01-hidden-effect/expected/rendered.txt"
[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](https://una-lang.org/en/learn/hello/printing-the-console-print-and-uses/#s1-5) and [section 6.3](https://una-lang.org/en/learn/functions/what-a-header-says-pub-private-functions-and-inferred-headers/#s6-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]`:

1. **`uses`** starts the clause.
2. **`@files`** is the binding: the name the body uses for the capability. You choose it. `@files` is the usual name for `Files`, and a name such as `@audit` can say what a capability is for.
3. **`: Files`** is the capability.
4. **`[read, write]`** lists the operations the function may perform, separated by commas.

A function written in the long form ([section 6.2](https://una-lang.org/en/learn/functions/the-result-of-a-function-return-types-the-last-line-unused-values/#s6-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](https://una-lang.org/en/learn/capabilities/the-hosts-capabilities-and-grants/#s12-2) explains:

```toml include="steps/02-uses-forms/una.toml" title="steps/02-uses-forms/una.toml"
[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.

```una include="steps/02-uses-forms/src/backroom.una#shelf_tag" title="steps/02-uses-forms/src/backroom.una"
--- 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:

```una include="steps/02-uses-forms/src/backroom.una#announce" title="steps/02-uses-forms/src/backroom.una"
--- 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`:

```una include="steps/02-uses-forms/src/backroom.una#copy_count" title="steps/02-uses-forms/src/backroom.una"
--- 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 pass
```

Both 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](https://una-lang.org/en/learn/failure/handling-a-failure-the-clauses/#s7-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:

```una include="steps/02-uses-forms/src/backroom.una#announce_all" title="steps/02-uses-forms/src/backroom.una"
--- 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:

```una include="steps/02-uses-forms/src/backroom.una#save_and_say" title="steps/02-uses-forms/src/backroom.una"
--- 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](https://una-lang.org/en/learn/functions/what-a-header-says-pub-private-functions-and-inferred-headers/#s6-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:

```una include="steps/02-uses-forms/src/backroom.una#main" title="steps/02-uses-forms/src/backroom.una"
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 unit
```

`una run .` prints:

```text include="steps/02-uses-forms/expected/output.txt"
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-07
```

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

:::steps
```una include="steps/03-uses/src/slips.una" title="steps/03-uses/src/slips.una" verified="check, run"
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)
```

1. **`slip_line(sku: Text, quantity: Int) -> Text`.** No `uses`, so the body may not perform any operation. It builds a text and returns it.
2. **`uses @console: Console[print]`.** This line gives `print_line` a binding named `@console`, of the host capability `Console`, with the one operation `print`.
3. **`@console.print(slip_line(sku, quantity: quantity))`.** The operation, with the pure function's result as its argument.
4. **`print_line("LAMP-01", quantity: 2)` in `main`.** `main` holds `@console`, and `print_line` needs `@console`, so the call passes it on by name. Nothing else is written at the call.
:::

`una run .` prints:

```text include="steps/03-uses/expected/output.txt"
Packing slip for order A-1001
2 x LAMP-01
1 x DESK-02
```

## 12.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](https://una-lang.org/en/learn/capabilities/passing-authority-with-rebinding-and-narrowing/#s12-4) shows how to hand a binding over under another name, and [forgetting to hand over a binding](https://una-lang.org/en/learn/capabilities/common-mistakes/#forgetting-to-hand-over-a-binding-u3001) 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](https://una-lang.org/en/learn/capabilities/common-mistakes/#using-an-operation-the-header-does-not-list-u3002) 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

:::decide
**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`:

```una include="steps/02-uses-forms/src/backroom.una#close_shelf" title="steps/02-uses-forms/src/backroom.una"
--- 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 pass
```

Which `uses` and which `fails` does the checker infer for it?

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

```text include="steps/02-uses-forms/expected/commands/contract.txt"
$ 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 -- inferred
```

`read` 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?

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