---
title: "1.5 Printing: the console, print and uses"
url: https://una-lang.org/en/learn/hello/printing-the-console-print-and-uses/
release: v0.4.0
edition: "0.2"
---

# 1.5 Printing: the console, print and uses

## 1.5.1 What the console is

The **console** is the channel of text between a program and the person who runs it. In a terminal, it is the window itself: what the program prints appears there, line after line, under the command that started it. Printing is the simplest way a program shows its results.

In Una the console is a **capability**: something outside the program that a function may use, with a set of **operations**, the actions it offers. The console's capability is `Console`, and its operation `print` writes one line of text. A function that may print says so in its header, with a `uses` line. This section shows that line in its simplest form; [chapter 12](https://una-lang.org/en/learn/capabilities/declaring-what-a-function-may-do-uses-in-full/#s12-1) covers capabilities in full.

## 1.5.2 Why a function says that it prints

Printing changes the world outside the program: a line appears on someone's screen. A function that only gives back a text changes nothing; you may call it as often as you like. Una keeps the two apart, in the header, where a reader looks first. A public function that prints says so with a `uses` line, and Una refuses a public function that prints without one. So a public function's header without `uses` promises that the function does nothing outside the program. A private function may leave its `uses` line out, and Una then works it out from the body ([section 6.3](https://una-lang.org/en/learn/functions/what-a-header-says-pub-private-functions-and-inferred-headers/#s6-3)); this book always writes it, so that every header says what its function does.

## 1.5.3 How to write `uses`

A `uses` line goes under the header, indented two spaces, before `=`. Here it is on two functions:

:::steps
```una include="steps/17-printing/src/signs.una" title="src/signs.una" verified="check, run"
module signs

--- Prints a line of dashes, to separate the parts of a sign.
pub rule() -> Unit
  uses @console: Console[print]
=
  @console.print("--------------------")

--- Prints the sign of the café, between two rules.
pub main() -> Unit
  uses @console: Console[print]
=
  rule()
  @console.print("The café opens at 10:00")
  rule()
```

1. **`uses`.** The keyword that starts the line.
2. **`@console`.** The name the body uses for the console. A name that starts with `@` always stands for a capability.
3. **`: Console`.** The capability: the console.
4. **`[print]`.** The operations the function may use, in brackets: here only `print`.
5. **`@console.print("The café opens at 10:00")`.** A call of the operation: the capability's name, a dot, the operation, and its argument in parentheses. The argument is the text to print.
6. **`rule()`.** `main` calls `rule`, which prints. A function that calls a function that prints also prints, so `main` has its own `uses` line too.
:::

A `uses` line is the code asking for the console. The run gets it when the package's manifest allows it: the line `grants = ["console"]` in `una.toml`, which every package of this chapter has. [Chapter 12](https://una-lang.org/en/learn/capabilities/the-hosts-capabilities-and-grants/#s12-2) covers grants, and the other ways a run gets the console.

`una run .` prints:

```text include="steps/17-printing/expected/output.txt"
--------------------
The café opens at 10:00
--------------------
```

## 1.5.4 How printing behaves

- **One line per call.** Each call of `print` writes one line, and ends it, so the next call starts a new line.
- **In the order the steps run.** The lines appear in the order of the calls, as `main` and the functions it calls run them.
- **Exactly the text.** `print` writes the text as it is, spaces and every character included, such as `é`. `print("")` writes an empty line.
- **Only text.** `print` takes one value, a text. [Chapter 2](https://una-lang.org/en/learn/numbers/values-types-and-names-let/#s2-1) shows how to print a number.
- **No `uses`, no printing.** A public function that prints must have a `uses` line. Take it away from `rule`, and `una check .` reports:

```text include="steps/18-no-uses/expected/rendered.txt#L1-L6"
[U3004] Error: `@console` is used here, but this code declares no `uses`, so it is pure
   ╭─[ src/signs.una:4:22 ]
   │
 4 │ pub rule() -> Unit = @console.print("--------------------")
   │                      ────┬───
   │                          ╰───── `@console` is used here, but this code declares no `uses`, so it is pure
```

The function is **pure**: without `uses`, it may do nothing outside the program. The marks point at `@console`, the use that the header does not allow.

## 1.5.5 When to print, and when to give back a text

:::decide
**Which to use:**

| You want to… | Use |
| --- | --- |
| Make a text the program shows | a function without `uses` that gives back a `Text` |
| Show a line to the person running the program | `@console.print(...)` in a function with `uses @console: Console[print]` |
| Print the same few lines from several places | a function with `uses` and a `Unit` result, such as `rule` |
| Let the run print | `grants = ["console"]` in `una.toml` |
:::

A function that gives back a text can be tested on its own, as [Testing it](https://una-lang.org/en/learn/hello/testing-it/#s1-7) shows, so the work of a program goes into such functions, and a few functions with `uses`, `main` first, print what they give back.

## 1.5.6 Check yourself: printing

In this version, the public function `frame` calls `rule` twice. Does `una check .` pass?

```una include="steps/19-caller-no-uses/src/signs.una#frame" title="src/signs.una"
--- Prints a rule, twice.
pub frame() -> Unit
=
  rule()
  rule()
```

:::answer Show the answer
No:

```text include="steps/19-caller-no-uses/expected/rendered.txt#L1-L6"
[U3003] Error: `rule` uses `@console: Console[print]`, but this code declares no `uses`, so its effects would exceed its header
    ╭─[ src/signs.una:12:3 ]
    │
 12 │   rule()
    │   ───┬──
    │      ╰──── `rule` uses `@console: Console[print]`, but this code declares no `uses`, so its effects would exceed its header
```

There are two diagnostics, the same one for each call of `rule`; the first is shown. `rule` prints, so a call of it prints too. `frame` is public and has no `uses` line, so it may not print, and each call of `rule` in its body is `U3003`. The repair: give `frame` the line that `rule` has, `uses @console: Console[print]`, under its header. Then `frame` may print, and so must every function that calls it.
:::
