---
title: "6.3 What a header says: pub, private functions and inferred headers"
url: https://una-lang.org/en/learn/functions/what-a-header-says-pub-private-functions-and-inferred-headers/
release: v0.4.0
edition: "0.2"
---

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

## 6.3.1 What `pub` means

A program can have many modules, and one module can call the functions of another, as [chapter 11](https://una-lang.org/en/learn/packages/pub-and-import/#s11-2) shows. `pub`, short for public, decides which functions it may call:

- A function that starts with `pub` is **public**: any module may call it.
- A function without `pub` is **private**: only the functions of its own module may call it.

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:

- the type of every parameter and of the result, as every header does;
- what the function may do outside the program, with `uses`, such as print;
- the ways it can fail, with `fails`, which [chapter 7](https://una-lang.org/en/learn/failure/declaring-a-failure-fails-and-fail/#s7-2) covers.

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](https://una-lang.org/en/learn/hello/the-main-function/#s1-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:

:::steps
```una include="steps/20-inferred/src/restock.una" title="src/restock.una" verified="check, run"
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](https://una-lang.org/en/learn/hello/printing-the-console-print-and-uses/#s1-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:

```text include="steps/20-inferred/expected/output.txt"
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](https://una-lang.org/en/learn/failure/declaring-a-failure-fails-and-fail/#s7-2) 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
```

```text include="steps/20-inferred/expected/commands/contract-show.txt#L2-L3"
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
```

```text include="steps/20-inferred/expected/commands/contract-to-order.txt#L2-L4"
--- 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:

```text include="steps/20-inferred/expected/commands/report.txt#L8-L10"
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 include="steps/20-inferred..steps/21-public-caller:src/restock.una" context="1"
--- 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()
```

```text include="steps/21-public-caller/expected/rendered.txt#L1-L8"
[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:

```text include="steps/22-public-show/expected/rendered.txt#L1-L6"
[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:

```text include="steps/23-no-result-type/expected/rendered.txt#L1"
[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](https://una-lang.org/en/learn/testing/examples-do-and-expect/#s14-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](https://una-lang.org/en/learn/numbers/day-to-day-a-packing-slip/#s2-4) has that shape: pure functions build the lines, and `main` prints them.

## 6.3.9 Public or private

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

```una include="steps/24-heading/src/restock.una" title="src/restock.una"
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?

:::answer Show the answer
```text include="steps/24-heading/expected/commands/report.txt#L8-L11"
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.
:::
