---
title: "1.2 Modules"
url: https://una-lang.org/en/learn/hello/modules/
release: v0.4.0
edition: "0.2"
---

# 1.2 Modules

## 1.2.1 What a module is

A **module** is one file of Una code, with a name. Think of the chapters of a binder of store procedures: each chapter has a title on its first page, and holds the procedures on one subject. A module's first line is its title, and what follows are its **declarations**: each one gives a name to something, such as a function, a named list of steps. In this chapter, every declaration is a function.

A small program is one module. A larger one is several, each on one subject, such as prices or shipping; [chapter 11](https://una-lang.org/en/learn/packages/) shows how modules use each other.

## 1.2.2 Why code lives in named modules

A program of one file without names would work, for a while. But a reader looking for the opening hours of the store would have to read all of it, and two people changing it at once would change the same file. Modules give each subject its own file, and their names let `una` find a module from its file, and a file from its module. That is why the name of the file and the first line of the module must agree: `una` checks that they do.

## 1.2.3 How to write a module

A module is a file `src/<name>.una` in the package. Here is the module `opening`, in the file `src/opening.una`:

:::steps
```una include="steps/04-opening/src/opening.una" title="src/opening.una" verified="check, run"
module opening

-- The notices of the store's front door.

--- Prints when the store opens.
pub main() -> Unit
  uses @console: Console[print]
=
  -- One line, for the sign on the door.
  @console.print("The store opens at 9:00")

--- Prints when the store closes.
pub closing() -> Unit
  uses @console: Console[print]
=
  @console.print("The store closes at 18:00")
```

1. **`module opening`.** The module line: the keyword `module` and the module's name. A **keyword** is a word with a fixed meaning in the language. The name must be the file's name without `.una`, written in small letters, digits and `_`, starting with a letter.
2. **`-- The notices of the store's front door.`** A **comment**: a note for people, which `una` skips. It starts with `--` and runs to the end of its line.
3. **`--- Prints when the store opens.`** A **doc comment**: three dashes, right above a declaration. It belongs to that declaration and documents it; tools print it with the declaration's header. Every public declaration, one that other modules may use ([section 1.3](https://una-lang.org/en/learn/hello/the-main-function/#s1-3)), should have one.
4. **`pub main() -> Unit` …** The first declaration, the function `main`.
5. **`-- One line, for the sign on the door.`** A comment may also stand inside a function, on a line of its own.
6. **`pub closing() -> Unit` …** A second declaration, the function `closing`, after a blank line.
:::

Its package is made as in [Making the package](https://una-lang.org/en/learn/hello/your-first-program-hello-world/#making-the-package), with `entry = "opening"` in `una.toml`. `una run .` prints:

```text include="steps/04-opening/expected/output.txt"
The store opens at 9:00
```

Only one line: `una run .` runs `main`, and `main` does not call `closing`. A declaration is not a step of the program; it only gives a name to something that a step can use. [Section 1.4](https://una-lang.org/en/learn/hello/writing-a-function/#s1-4) shows how one function calls another.

## 1.2.4 Comments, line by line

Una has two kinds of comment, and no other:

- `--` starts a comment for the reader of the code. It may stand on a line of its own, at the top of the module or inside a body.
- `---` starts a doc comment, which documents the declaration right under it.

Una has no comment that spans several lines on its own: a note of several lines repeats `--` or `---` on each. A comment written another way is not a comment, and `una check` reports the line, as [A comment with `//`](https://una-lang.org/en/learn/hello/common-mistakes/#a-comment-with-u0101) shows.

## 1.2.5 How a module behaves

`una check .` holds every module to three rules.

### 1.2.5.1 The module line matches the file

Change the first line of `src/opening.una` to `module door`, and `una check .` reports:

```text include="steps/05-module-name/expected/rendered.txt#L1-L11"
[U1008] Error: module `door` is in `src/opening.una`, which must hold module `opening`
   ╭─[ src/opening.una:1:8 ]
   │
 1 │ module door
   │        ──┬─
   │          ╰─── module `door` is in `src/opening.una`, which must hold module `opening`
   │
   │ Help: repair 1: declare `module opening`, or move the file to match `door`; edit src/opening.una:1:8..1:12 to "opening"
   │
   │ Note: run `una explain U1008` for an explanation
───╯
```

The message says both names: the module's, `door`, and the one its file asks for, `opening`. The `Help` line offers both repairs: change the name, or move the file. A second diagnostic, `U7002`, follows: `entry` in `una.toml` names the module `opening`, which the package no longer has. Fix the first line, and both go away.

### 1.2.5.2 Each name is declared once

Rename `closing` to `main`, so that the module declares `main` twice:

```text include="steps/06-twice/expected/rendered.txt"
[U1002] Error: `main` is defined twice in this module, both times as a function
    ╭─[ src/opening.una:13:5 ]
    │
  6 │ pub main() -> Unit
    │     ──┬─
    │       ╰─── first defined here
    │
 13 │ pub main() -> Unit
    │     ──┬─
    │       ╰─── `main` is defined twice in this module, both times as a function
    │
    │ Note: run `una explain U1002` for an explanation
────╯
```

Two declarations with one name would leave `una run .` unable to tell which `main` to start, so a module gives each name once. The diagnostic points at both: where the name was first given, and where it is given again.

### 1.2.5.3 The order of declarations does not matter

The declarations of a module may come in any order. `closing` could come before `main`, and the program would print the same line. Most modules put the small pieces first and `main` last, so that a reader meets each piece before the code that uses it.

## 1.2.6 When to start a new module

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

| You want to… | Use |
| --- | --- |
| Write a small program, as in this chapter | one module, named after what it does |
| Keep code on another subject apart, such as prices | a module of its own ([chapter 11](https://una-lang.org/en/learn/packages/)) |
| Leave a note for the reader of the code | a comment, `--` |
| Document what a declaration is for | a doc comment, `---`, right above it |
:::

## 1.2.7 Check yourself: modules

The file `src/opening.una` starts with this line instead:

```una include="steps/07-capital/src/opening.una#L1"
module Opening
```

Does `una check .` pass?

:::answer Show the answer
No:

```text include="steps/07-capital/expected/rendered.txt#L1"
[U0101] Error: unexpected `Opening`, expected a module path
```

A module's name is written in small letters, so `Opening`, with a capital letter, is not a name a module line accepts: `una` expected "a module path", a module's name. Write `module opening`, the file's name.
:::
