Skip to content

How names resolve

When a program writes lower("ABC"), the checker must find the one declaration lower refers to. It may be the program's own function, or a function a from statement bound, the prelude's included. The rules are fixed, so a name always resolves to the same declaration, whatever order things are written in.

Every module is an import unit: one scope in which its imports apply and its names resolve. A program is an import unit of its own, the program module. An import makes a module visible in the unit that imports it, and nowhere else.

d2 diagram

Imports are per unit

A module's imports are its own. A module that imports math sees math, and a program that imports the module does not see math through it. The prelude, too, is the implicit import list of each unit separately.

A unit's own names win

A declaration the unit writes itself wins over an imported declaration of the same name, in every spelling: an unqualified call, a pipeline step and a receiver call. The imported one stays reachable through its module. This program declares its own lower:

fn lower(s: String) : String = "mine"
[lower("ABC"), "ABC" | lower, string.lower("ABC")]
["mine", "mine", "abc"]

The program's lower takes no self, so the receiver spelling reaches nothing, and the prelude's lower is not reached in its place:

fn lower(s: String) : String = "mine"
"ABC".lower()
check error[unknown-name]: `lower` is this unit's own function, which takes no `self`, so `value.lower(…)` does not reach it and no import's `lower` over String is reached in its place; write `lower(value, …)`, or qualify the import's
 --> <expression>:2:1
  |
2 | "ABC".lower()
  | ^^^^^^^^^^^^^

Because the unit's own declaration always wins, adding a function to an imported module never changes what an existing program calls. The order in which declarations are written does not matter either.

Two imports, one name

When two imports bind the same name to two declarations and the unit declares none, the name is ambiguous, and a call that uses it is a check error. Write the module name to choose one, titles.initials(s) or string.split(s, ","), or bind one of them under another name with as. Where the two declarations take inputs of different types, the input's type chooses, and the call is not ambiguous. The order of the imports never decides.

A module is a closure

A name in a module resolves through the module's own declarations and its own imports, and nothing else. A module never sees the program that imports it. The bindings hql provides to a program, such as vault, cards, stdin and stdout, are not bound in a module. What a module needs from a program must be passed in, as a parameter:

module club.shelf

fn books(cards: Seq<Card>) : Seq<Card> = cards | filter(c => c.metadata.category == "book")

A program calls it with its own cards, shelf.books(cards). A module written this way is checked once, and behaves the same in every program that imports it.

Imports form no cycle

Imports cannot form a cycle. An import that would close one is an error, and the error names the modules in the cycle. Two modules that need each other are fixed by moving the shared part into a third module that both import.

Module names form a tree, but the tree is not a dependency graph: club and club.reading see nothing of each other unless one imports the other. A child may import its parent. A parent that imports its child gets a warning.