Home / Learn / 6 Functions and their results

Release v0.4.0Edition 0.2

6.3 What a header says: pub, private functions and inferred headers

Page 4 of 9

6.3.1 What pub means

A program can have many modules, and one module can call the functions of another, as chapter 11 shows. pub, short for public, decides which functions it may call:

Think of a shop. The counter is public: customers walk up and ask for what is on the menu. The back room is private: the staff use it to get the work done, and no customer goes in. A module's public functions are its counter, and its private functions are its back room.

6.3.2 Why a public header must say everything

The caller of a public function may live in another module, written by someone else, years later. That caller sees the header, not the body. So the header of a pub function states everything a caller relies on:

If a public header could leave out its uses, a function that looks like a pure computation could print, write files or send data, and nothing at the call would show it. So a pub function that prints without a uses line does not check. A private function is different: every one of its callers is in the same file, in view of whoever changes it. So Una lets a private function leave out its uses line, and works it out from the body.

6.3.3 How to write a public and a private function

pub goes first, before the function's name: pub to_order(on_hand: Int, target: Int) -> Int. A private function leaves it out: show(sku: Text, units: Int) -> Unit. Everything else in the header is written as for any function. pub goes on kinds too, with the same meaning: a public kind may be used by other modules.

main must be public: una run . starts it from outside its module, and refuses a module without pub main() -> Unit (section 1.3).

6.3.4 A private function's inferred uses

The module restock prints a restock list. It has a public function that computes, and a private function that prints, without a uses line:

src/restock.unacheckrununa
module restock

--- How many units to order so that the shelf holds `target` again, and none when it already
--- does.
pub to_order(on_hand: Int, target: Int) -> Int = if on_hand >= target then 0 else target - on_hand

-- Prints one line of the restock list. It is private and has no `uses` line: the checker
-- infers it from the body.
show(sku: Text, units: Int) -> Unit = @console.print("{sku}: order {units}")

--- Prints the restock list of two SKUs.
pub main() -> Unit
  uses @console: Console[print]
=
  show("LAMP-01", units: to_order(3, target: 10))
  show("RUG-07", units: to_order(12, target: 10))
  1. to_order. A public function with no uses line: it is pure, as section 1.5 says, so it may only compute. It never orders fewer than none.
  2. show(sku: Text, units: Int) -> Unit = @console.print(…). A private function that prints, with no uses line in its header, written in the short form.
  3. main calls show. main declares the console, so show, called from it, can be given the console too.

una run . prints:

Output
LAMP-01: order 7
RUG-07: order 0

The checker has filled in what show left out. It sees that the body uses @console.print, and that every caller of show holds the console. Working out a missing part from the code around it is called inference, and the header it gives is the inferred header. The same holds for fails: a private function may leave it out, and the checker infers it, as chapter 7 shows.

6.3.5 Reading a whole header: una contract

una contract prints a function's whole header, as a caller may rely on it. You name the function by its module and its name, joined by a dot:

sh
una contract restock.show
Output
show(sku: Text, units: Int) -> Unit
  uses @console: Console[print] -- inferred

The part the checker inferred is marked -- inferred, so a reviewer sees that show prints, even though its source does not say so. una contract also prints a function's doc comment, the --- lines above it:

sh
una contract restock.to_order
Output
--- How many units to order so that the shelf holds `target` again, and none when it already
--- does.
pub to_order(on_hand: Int, target: Int) -> Int

This is what an editor, a reviewer or an agent sees of the function without reading its body: what it is for, what it takes and what it gives back. That is why every public function in this book has a doc comment.

6.3.6 Authority in the build report

What a function may do outside the program is its authority. The build report, una report ., lists the authority of every function of the package, declared or inferred, in its authority: part:

Output
authority:
  restock.main (pub): @console: Console[print]
  restock.show (private, inferred): @console: Console[print]

restock.main is public and declares the console. restock.show is private, and its console is inferred. to_order is not listed: it has no authority, and can only compute. A reviewer reads the effects of a whole package in one place, without opening a body.

6.3.7 How inference behaves

6.3.7.1 Inference follows the callers

A private function's uses come from its body, and its callers must have them to give. Here a public function, print_list, calls show but declares no uses:

diff
--- a/src/restock.una
+++ b/src/restock.una
@@ -11,2 +11,8 @@
 --- Prints the restock list of two SKUs.
+pub print_list() -> Unit
+=
+  show("LAMP-01", units: to_order(3, target: 10))
+  show("RUG-07", units: to_order(12, target: 10))
+
+--- Prints the restock list.
 pub main() -> Unit
@@ -14,3 +20,2 @@
 =
-  show("LAMP-01", units: to_order(3, target: 10))
-  show("RUG-07", units: to_order(12, target: 10))
+  print_list()
Diagnostic
[U3001] Error: no caller of `show` binds `@console`, so its capability cannot be inferred
   ╭─[ src/restock.una:9:39 ]
   │
 9 │ show(sku: Text, units: Int) -> Unit = @console.print("{sku}: order {units}")
   │                                       ────┬───
   │                                           ╰───── no caller of `show` binds `@console`, so its capability cannot be inferred
   │
   │ Help: repair 1: declare `uses @console: <capability>[print]` in the header; this states authority its callers are already charged for

The error is at the use of @console in show: no caller of show holds the console, so the checker has none to give it. The repair that fits is to give print_list, the public function that prints through show, the line uses @console: Console[print].

6.3.7.2 Nothing is inferred for a public function

A pub function writes its uses itself. Make show public, and it no longer checks:

Diagnostic
[U3004] Error: `@console` is used here, but this code declares no `uses`, so it is pure
   ╭─[ src/restock.una:8:43 ]
   │
 8 │ pub show(sku: Text, units: Int) -> Unit = @console.print("{sku}: order {units}")
   │                                           ────┬───
   │                                               ╰───── `@console` is used here, but this code declares no `uses`, so it is pure

"This code declares no uses, so it is pure": a public header without uses promises a pure function, and the body breaks the promise. So inference saves lines inside a module, where every caller is in view, and never hides an effect from another module.

6.3.7.3 Types are never inferred

Inference covers uses and fails, and never a type. Every parameter and every result of every function, public or private, has its type written. Leave out the result type, and the header does not parse:

Diagnostic
[U0101] Error: unexpected `=`, expected `->` and the result type

6.3.8 When a function should print

Most functions should not print: they take values and give back a value. Such a pure function does the same thing every time you call it with the same arguments, so an example can test it (section 14.1). Print in main, or in a few small functions whose only job is to print, and give each of them its uses line. The packing slip of chapter 2 has that shape: pure functions build the lines, and main prints them.

6.3.9 Public or private

Which to use:

The function… Make it
Is part of what the module offers other modules pub, with a doc comment and its whole header
Is called by una run pub: main must be public
Is a helper used only inside its module private
Is private and prints private, with its uses written, as this book does, or left to inference

Start private, and make a function pub when another module needs it. A private function can change freely, since all its callers are in view. A public one is a promise: a change to its header can break callers you cannot see. This book writes the uses line on every function that prints, private ones included, so that every header says what its function does; the inferred header is there for the helpers where you choose to leave it out.

6.3.10 Check yourself: authority

You make to_order private, and add a private function that prints a heading, with no uses line, which main calls first:

src/restock.unauna
module restock

-- How many units to order so that the shelf holds `target` again, and none when it already
-- does.
to_order(on_hand: Int, target: Int) -> Int = if on_hand >= target then 0 else target - on_hand

-- Prints the heading of the list.
heading() -> Unit = @console.print("Restock list")

-- Prints one line of the restock list. It is private and has no `uses` line: the checker
-- infers it from the body.
show(sku: Text, units: Int) -> Unit = @console.print("{sku}: order {units}")

--- Prints the restock list of two SKUs.
pub main() -> Unit
  uses @console: Console[print]
=
  heading()
  show("LAMP-01", units: to_order(3, target: 10))
  show("RUG-07", units: to_order(12, target: 10))

Which functions does the authority: part of una report . list now, and how is each marked?

Show the answer
Output
authority:
  restock.heading (private, inferred): @console: Console[print]
  restock.main (pub): @console: Console[print]
  restock.show (private, inferred): @console: Console[print]

Three functions print: heading, main and show. main is public and declares its console. heading and show are private and leave their uses out, so theirs are inferred from main, which calls both. to_order is private now, but it still only computes, so it has no authority and is not listed.

Next:6.4 Day-to-day: shipping quotes