5. Modules¶
A program of a few lines can keep everything in one file. Once several programs need the same functions, or a team shares them, the functions need a home of their own. A module is that home: a named file of declarations (functions, types, traits and bindings) that programs import.
A module is also a contract. Its public declarations, with their types, are
what every importer relies on. The rest is marked private and can change
without breaking anyone. The checker checks every use of a module against
that contract before the program runs: a call to a function the module does
not export, or with the wrong arguments, is a check error.
A program reaches a module's functions in one of two ways. import m binds
the module's name, and calls are written through it, reading.days(412, 40).
from m import f binds the function's own name, days(412, 40). The rules
are the same for every module, whether a program's own or one of the
standard library: "Dune".upper() calls a function of the module string,
which every program starts with imported.
A module is a file under a module root¶
A project module is an HQL file under a module root. Its name is its
path under the root: lib/club/reading.hql is the module club.reading, and
lib/club/mod.hql would be club. The roots come from .hql/config.toml:
[modules]
roots = ["lib"]
or from --modules lib on the command line. The reading club's project
uses lib/ as its root, and keeps the book's modules there. Roots that apply
outside any project come from ~/.hql/modules/, from [modules] roots in
~/.hql/config.toml, and from $HQL_PATH. The
execution context lists them
all. A module found under two roots is an error.
Every module file starts with its name, and the checker compares the name
with the file's path under its root. This is lib/club/reading.hql:
/// Reading plans: how long a book takes at a number of pages a day.
module club.reading
private fn rounded_up(n: Int, d: Int) : Int = (n + d - 1) / d
/// Days to read `pages` at `per_day` pages a day; a part day counts as one.
fn days(pages: Int, per_day: Int) : Int = rounded_up(pages, per_day)
/// Days to read every book of `shelf`, one after another.
fn days_for_all(shelf: List<Int>, per_day: Int) : Int {
each = shelf | map(pages => days(pages, per_day))
each | sum
}
A /// line is a doc string. It documents the declaration after it, and
hql help club.reading prints it. private keeps rounded_up inside the
module; Visibility covers this.
Importing a module¶
import club.reading makes the module visible under its last segment,
reading, and its functions are called through that name:
import club.reading
[reading.days(412, 40), reading.days(280, 40), reading.days_for_all([412, 280, 310], 40)]
[11, 7, 26]
import a.b as c makes it visible under c instead:
import club.reading as plan
plan.days(412, 40)
11
A module's function is a value like any other, and can be partially applied:
import club.reading
[412, 280] | map(reading.days(_, 40))
[11, 7]
from club.reading import days binds the function itself, and
Calling a module's functions covers that statement:
from club.reading import days
days(412, 40)
11
Imports come first in a file, before its declarations and expressions. Two imports cannot use the same local name:
import club.reading
import club.titles as reading
1
check error[unknown-name]: `reading` already names the module `club.reading` here; import `club.titles` under another name with `as`
--> <expression>:2:1
|
2 | import club.titles as reading
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A module that is not imported cannot be used:
reading.days(412, 40)
check error[unknown-name]: `reading` is not bound
--> <expression>:1:1
|
1 | reading.days(412, 40)
| ^^^^^^^
The standard modules¶
The standard library is made of modules of the same kind. The prelude is
the list of import statements every program starts with. It imports
string, seq, math, option and result, among others, both ways, so
"a,b".split(","), split("a,b", ",") and string.split("a,b", ",") all
call the prelude's string.split. Other standard modules are imported by
name:
import regex
regex.split("a1b22c", "[0-9]+")
["a", "b", "c"]
The reference has a page per standard module.
In this chapter¶
| Page | What it covers |
|---|---|
| Calling a module's functions | import and from, as and except, receivers selected by type, and the prelude |
Which variance? |
one name in two modules, followed through import, from, except and as |
| Receiver modules | module m for T, functions taking self, and value.f() calls |
| Visibility | public and private declarations, and a module's contract |
| How names resolve | import units, a unit's own names, ambiguity, and modules as closures |
| Modules and packages | modules, packages, extensions and libraries; builtin and installable packages |
What is next¶
Chapter 6 uses functions over collections to ask the questions SQL asks: where, order by, group by, and the aggregates.