Home / Learn / 1 Hello, Una
1.5 Printing: the console, print and uses
Page 6 of 11
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 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); 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:
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()uses. The keyword that starts the line.@console. The name the body uses for the console. A name that starts with@always stands for a capability.: Console. The capability: the console.[print]. The operations the function may use, in brackets: here onlyprint.@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.rule().maincallsrule, which prints. A function that calls a function that prints also prints, somainhas its ownusesline 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 covers grants, and the other ways a run gets the console.
una run . prints:
--------------------
The café opens at 10:00
--------------------1.5.4 How printing behaves
- One line per call. Each call of
printwrites 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
mainand the functions it calls run them. - Exactly the text.
printwrites the text as it is, spaces and every character included, such asé.print("")writes an empty line. - Only text.
printtakes one value, a text. Chapter 2 shows how to print a number. - No
uses, no printing. A public function that prints must have ausesline. Take it away fromrule, anduna check .reports:
[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 pureThe 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
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 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?
--- Prints a rule, twice.
pub frame() -> Unit
=
rule()
rule()Show the answer
No:
[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 headerThere 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.