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