Home / Learn / 1 Hello, Una
1.2 Modules
Page 3 of 11
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 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:
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")module opening. The module line: the keywordmoduleand 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.-- The notices of the store's front door.A comment: a note for people, whichunaskips. It starts with--and runs to the end of its line.--- 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), should have one.pub main() -> Unit… The first declaration, the functionmain.-- One line, for the sign on the door.A comment may also stand inside a function, on a line of its own.pub closing() -> Unit… A second declaration, the functionclosing, after a blank line.
Its package is made as in Making the package, with entry = "opening" in una.toml. una run . prints:
The store opens at 9:00Only 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 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 // 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:
[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:
[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
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) |
| 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:
module OpeningDoes una check . pass?
Show the answer
No:
[U0101] Error: unexpected `Opening`, expected a module pathA 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.