Home / Learn / 1 Hello, Una

Release v0.4.0Edition 0.2

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:

src/signs.unacheckrununa
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 covers grants, and the other ways a run gets the console.

una run . prints:

Output
--------------------
The café opens at 10:00
--------------------

1.5.4 How printing behaves

Diagnostic
[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

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?

src/signs.unauna
--- Prints a rule, twice.
pub frame() -> Unit
=
  rule()
  rule()
Show the answer

No:

Diagnostic
[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.

Next:1.6 Day-to-day: morning notices