Home / Learn

Release v0.4.0

11 Packages and modules

Page 1 of 9

A program of one file is easy to read until it grows. Then the price rules, the catalog and the invoice text sit side by side, any function can call any other, and a reader cannot tell which functions other parts of the program are meant to use. In Una a package is split into modules, one file each. A module shares only what it marks pub, and every other module names what it takes with import. This chapter splits a store's invoice into modules, shows how a module shares a function and how another takes it, and walks through the two files at the root of every package, una.toml and verification.lock.

What you'll build

An invoice for a small store, split into five modules: one for money, one for the catalog, one for prices, one for the invoice lines, and one that runs it all. Each module has its own examples, and una test runs them together. The invoice reads:

Output
2 x Desk lamp at 19.90 (members 17.91): 39.80
1 x Oak desk at 249.00 (members 224.10): 249.00
CHAIR-09: not in the catalog

You will learn to:

  • lay out a package: one module per file, named after its path under src/;
  • decide what a module shares with pub, and take it elsewhere with import;
  • read and write una.toml, and know what verification.lock pins;
  • keep the imports of a package free of cycles, and in the order una fmt writes them;
  • test a package of several modules with one command.

Download this chapter's packages: each step is a package under steps/, and the chapter's program is day-to-day/; run una check . and una run . in one.

Why it works this way

In many languages, a file can see a great deal it never asked for: every public name of every file in the project, globals, and whatever an import brings in with it. Splitting a program into files does not, by itself, say which parts are the interface of a file and which are its details. A dependency added by one line in a manifest can bring in code that reads files or opens connections, and nothing in the caller's code shows it. A package that una.toml describes has no dependencies on other packages (section 11.3).

Una keeps the structure small and visible:

  1. One file is one module, and its path is its name. src/store/money.una holds the module store.money, and nothing else.
  2. Private by default. A declaration is visible outside its module only when it says pub. A pub function's header is its contract with the rest of the package, so it declares its uses and fails, as section 6.3 and section 7.2 showed.
  3. Every import is named. import store.money (format) takes one declaration, by name. There is no import of everything.
  4. The manifest is checked. una.toml holds a fixed set of tables, and a table or key that una does not know is an error, not a setting that is silently ignored.
Key idea

A module's pub declarations are its interface, and its imports say exactly what it uses of other modules. Both are in the source, where a reviewer reads them.

View the Markdown

Next:11.1 Packages and modules