Home / Learn / 11 Packages and modules
11.1 Packages and modules
Page 2 of 9
11.1.1 What a package and a module are
Think of a store's binder of procedures. The binder holds everything the staff need, and tabbed sections divide it: one for the till, one for deliveries, one for returns. A clerk looking for the refund rules opens one section, not the whole binder.
A package is the binder: one program, kept in one directory with everything una needs to check and run it. A module is one section: a single file of Una code under the package's src/ directory. Chapter 1 made packages of one module each. A program grows by adding modules, and each module holds the code about one subject.
A few words name the parts, and the rest of the chapter uses them:
- A path is where a file sits, written as the directories that lead to it:
src/store/money.unais the filemoney.unain the directorystore, insidesrc. - A module path is a module's name, built from its file's path: drop
src/and.una, and write.for each/. Sosrc/store/money.unaholds the modulestore.money. Each part between dots is a segment. In chapter 1, every module path had one segment, such asmorning. - A declaration is a top-level item of a module: a function, a kind, a predicate and the like, each starting at the left edge of the file.
- The entry is the module that
una runstarts, the one withpub main.
Each example of this chapter is a package of its own, a step, made as chapter 2 explains; the chapter's download, 11-packages.tar.gz, holds every one of them.
11.1.2 Why a program is split into modules
Every module has its own set of names, so one module cannot declare two things with the same name. Here is a store's program kept in one module. It formats an amount of money, and it also formats a tax rate, and both functions are called format:
module store
--- An amount in cents as a person reads it: 1990 is "19.90".
format(cents: Int) -> Text
=
let rest = cents mod 100
if rest < 10 then "{cents / 100}.0{rest}" else "{cents / 100}.{rest}"
--- A tax rate as a person reads it: 8 is "8%".
format(percent: Int) -> Text = "{percent}%"
pub main() -> Unit
uses @console: Console[print]
=
@console.print("a lamp costs {format(1990)}, with tax at {format(8)}")una check . reports:
[U1002] Error: `format` is defined twice in this module, both times as a function
╭─[ src/store.una:10:1 ]
│
4 │ format(cents: Int) -> Text
│ ───┬──
│ ╰──── first defined here
│
10 │ format(percent: Int) -> Text = "{percent}%"
│ ───┬──
│ ╰──── `format` is defined twice in this module, both times as a function
│
│ Note: run `una explain U1002` for an explanation
────╯The first line names the problem: format is defined twice. The two marks point at both declarations, so you see which one came first. Inside one module, a name means one thing, and the checker refuses to guess which format a call means.
In one file, every new function has to find a name that no other function of the whole program uses, and every function can call every other. As the file grows, so do both problems: names get longer to stay apart, and a change to any helper can affect any line of the program. Modules solve both. Each module has its own names, so the money module and the tax module can each have a format of their own. And each module decides which of its declarations other modules may use, which section 11.2 covers.
11.1.3 How to write a module
The next step splits a store's program into two modules. store.money formats an amount, and store.app prints with it:
module store.money
--- An amount in cents as a person reads it: 1990 is "19.90".
pub format(cents: Int) -> Text
=
let rest = cents mod 100
if rest < 10 then "{cents / 100}.0{rest}" else "{cents / 100}.{rest}"module store.app
import store.money (format)
pub main() -> Unit
uses @console: Console[print]
=
@console.print("a lamp costs {format(1990)}, a desk {format(24905)}")una run . prints:
a lamp costs 19.90, a desk 249.05A module file has three parts, always in this order:
- The
moduleline. The first line of the file names the module:module store.money. It must be the module path of the file's own path. - The imports. Zero or more
importlines, each naming a module of the package and the declarations it takes:import store.money (format). Section 11.2 covers imports. - The declarations. The functions, kinds and other declarations of the module, in any order, separated by blank lines. All of them see each other: a function can call one declared further down.
Two smaller things in this step. pub before format, the word section 6.3 introduced, is what lets the module store.app call it; section 11.2 shows how one module takes a function from another. cents mod 100 is the remainder of dividing cents by 100, as / is the quotient: 1990 divided by 100 is 19, remainder 90 (section 2.2 covers both).
11.1.3.1 The entry module in una.toml
una check . checks every module, but una run . must know where to start. The manifest, una.toml, says so: [run] entry is a module path, here store.app, and that module has the pub main.
[package]
name = "store"
version = "0.1.0"
edition = "0.2"
[run]
entry = "store.app"
grants = ["console"]Section 11.3 explains every line of this file.
11.1.4 Modules at every depth
A module path has as many segments as its file has directories under src/, plus one for the file. This step has three modules at three depths:
| File | Module |
|---|---|
src/app.una |
app |
src/store/money.una |
store.money |
src/store/tax/rates.una |
store.tax.rates |
The tax module knows the store's sales tax, and has a format of its own, for percentages:
module store.tax.rates
--- The store's sales tax, in percent.
pub rate() -> Int = 8
--- The tax on an amount, in cents, rounded down.
pub tax_cents(cents: Int) -> Int = cents * rate() / 100
--- The rate as a person reads it: 8 is "8%".
pub rate_text() -> Text = format(rate())
--- A percentage as a person reads it.
format(percent: Int) -> Text = "{percent}%"The entry is app, a module of one segment, directly under src/:
module app
import store.money (format)
import store.tax.rates (rate_text, tax_cents)
pub main() -> Unit
uses @console: Console[print]
=
let cents = 1990
@console.print("a lamp costs {format(cents)}, and tax at {rate_text()} adds {format(tax_cents(cents))}")[package]
name = "store"
version = "0.1.0"
edition = "0.2"
[run]
entry = "app"
grants = ["console"]una run . prints:
a lamp costs 19.90, and tax at 8% adds 1.59Two functions called format now live in one package without a clash: store.money has one, and store.tax.rates has another. app imports only the money one, and calls the tax module's rate_text, which uses its own format inside.
11.1.5 How una finds and checks the modules
11.1.5.1 Every file under src/ is a module
There is no list of modules to keep up to date. una check . reads every .una file under src/, checks all of them together, and reports each diagnostic with its file. A new file is part of the package as soon as it exists, and a deleted file is gone from it. Hidden entries, whose names start with a dot, are skipped.
A directory under src/ only groups modules: it is not a module itself, and it needs no file of its own. src/store/ holds store.money, but there is no module store.
11.1.5.2 The module line must match the path
A file whose module line does not match its path is U1008, at that line, with a repair that writes the right path. A module header that does not match its path shows one.
11.1.5.3 The rules for a module path
Each segment is a lower-case name, as a function's name is: a lower-case letter, then lower-case letters, digits and underscores, such as store, tax_rates or v2. It may not contain __ or end with _ (U1005), and it may not be a keyword.
Paths that start with std or prelude belong to the standard library. Add a file src/std/money.una to the package of the last step, and una check . reports:
[U1009] Error: module `std.money` starts with `std`, a segment that only the standard library may use
╭─[ src/std/money.una:1:1 ]
│
1 │ module std.money
│ ────────┬───────
│ ╰───────── module `std.money` starts with `std`, a segment that only the standard library may use
│
│ Note: run `una explain U1009` for an explanation
───╯The standard library has its own modules there, such as std.host, so a package may not add any. Choose another first segment, such as store.
11.1.5.4 Where checking and running start
una check . and una test . take every module. una run . starts at main in the entry module, and runs only what main calls. A module that nothing calls is still checked, and its examples still run under una test ..
11.1.6 Grouping and moving modules
Group modules by what they are about, not by what kind of declaration they hold: store.money keeps the type of an amount, its formatting and its tests together. A reader who wants to know how amounts are printed then opens one file.
A module path follows the file system, so moving a file renames its module. The checker then reports the header that no longer matches, and every import of the old name, so nothing is left pointing at a module that is gone.
Which to use:
| You have… | Use |
|---|---|
| A small program, a few functions about one subject | One module, such as src/app.una |
| Code about two subjects, such as money and the catalog | One module per subject |
| Several modules about one area | A directory for the area: src/store/money.una, src/store/catalog.una |
| A helper that two modules need | Its own module, or the module that owns its subject, imported by both |
11.1.7 Check yourself: module paths
The file src/store/tax/rates.una of Modules at every depth now starts with a shorter line:
--- a/src/store/tax/rates.una
+++ b/src/store/tax/rates.una
@@ -1 +1 @@
-module store.tax.rates
+module tax.ratesThe rest of the package is unchanged, and app still imports store.tax.rates. What does una check . report? Count the diagnostics before you open the answer.
Show the answer
Four diagnostics, three of them in app:
error U1001 at src/app.una:4:8: module `store.tax.rates` is not a module of this package; the standard modules that can be imported are `std.host` and `std.testing`
error U1001 at src/app.una:10:61: cannot find name `rate_text` in this module, its imports or the prelude
error U1001 at src/app.una:10:87: cannot find name `tax_cents` in this module, its imports or the prelude
error U1008 at src/store/tax/rates.una:1:8: module `tax.rates` is in `src/store/tax/rates.una`, which must hold module `store.tax.rates`The file still sits at src/store/tax/rates.una, so its module must be store.tax.rates (U1008, with a repair that writes it). And since no file now holds store.tax.rates, the import in app names a module that does not exist (U1001), and the two names it imported cannot be found. Fix the module line, and all four go away: when several diagnostics appear at once, look first for the one the others follow from.
Next:11.2 pub and import