Skip to content

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.

d2 diagram

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.