Home / Learn / 1 Hello, Una

Release v0.4.0Edition 0.2

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:

src/opening.unacheckrununa
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), 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, with entry = "opening" in una.toml. una run . prints:

Output
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 shows how one function calls another.

1.2.4 Comments, line by line

Una has two kinds of comment, and no other:

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:

Diagnostic
[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:

Diagnostic
[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:

una
module Opening

Does una check . pass?

Show the answer

No:

Diagnostic
[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.

Next:1.3 The main function