21 Modules — hidden by default

21.1 One file, one module#

One source file is one module. A module writes its name on the first line, and the module name need not match the file name.

module geom .

export struct point do
  x i64 .
  y i64 .
end

export fn manhattan input a point . input b point . output i64 .
  requires ge (field a x) -1000000 .
  requires le (field a x) 1000000 .
  requires ge (field b x) -1000000 .
  requires le (field b x) 1000000 .
  requires ge (field a y) -1000000 .
  requires le (field a y) 1000000 .
  requires ge (field b y) -1000000 .
  requires le (field b y) 1000000 .
do
  return add (abs (sub (field b x) (field a x))) (abs (sub (field b y) (field a y))) .
end

fn helper input v i64 . output i64 .
do
  return v .
end

$ lowentc --check geom.low
== check: ok ==

The geom module exports the point struct and the manhattan op with export. helper has no export, so it can be used only inside this module.

          module geom (geom.low)                            module app
  ┌────────────────────────────────────┐
  │ export struct point      ─────────┼──▶ door ──▶ geom.point       ✔ visible
  │ export fn manhattan      ─────────┼──▶ door ──▶ geom.manhattan   ✔ visible
  │ fn helper   (no export)            │            geom.helper      ✘ E-VISIBILITY
  └────────────────────────────────────┘
      what is inside the wall leaves only through a door made by export

Hidden is the default. What is visible from outside is a promise, and hiding something by mistake is easier to fix than promising something by mistake. When emitting native code, too, only exported ops become symbols callable from C; everything else is static.

21.2 Importing#

use <module> from "<place>" . imports a module from the file at that place. The place is a path relative to the file that declares it.

module app .
rem run: distance 3 4

use geom from "geom.low" .

fn distance input dx i64 . input dy i64 . output i64 .
  requires ge dx -1000 .
  requires le dx 1000 .
  requires ge dy -1000 .
  requires le dy 1000 .
do
  let a geom.point be make geom.point do x 0 . y 0 . end .
  let b geom.point be make geom.point do x dx . y dy . end .
  return geom.manhattan a b .
end

$ lowentc --run distance app.low 3 4
distance(3, 4) = 7

Imported names are called qualified by the module name — geom.point, geom.manhattan. The attached dot is not an operation on a value but a path to a declared name (chapter 3).

Qualification does not reach hidden names.

module hidden .
rem expect: E-VISIBILITY

use geom from "geom.low" .

fn peek input v i64 . output i64 .
do
  return geom.helper v .
end

$ lowentc --check hidden.low
hidden.low:8:0 E-VISIBILITY: this name belongs to ANOTHER module and is not `export`ed — qualifying it does not open the door. A module that cannot keep anything private is not a module, it is a prefix. Mark it `export`, or stop reaching in (RFC-0011 §6.2)

In the words of the diagnostic, “a module that cannot keep anything private is not a module, it is a prefix”.

21.3 What can be exported, and how to shorten a name#

export goes on most named declarations. Some do not take it.

When a module name is long, or two modules share a name, shorten it with as.

module alias .
rem run: distance 3 4

rem call the imported module by the short name g
use geom from "geom.low" as g .

fn distance input dx i64 . input dy i64 . output i64 .
  requires ge dx -1000 .
  requires le dx 1000 .
  requires ge dy -1000 .
  requires le dy 1000 .
do
  let a g.point be make g.point do x 0 . y 0 . end .
  let b g.point be make g.point do x dx . y dy . end .
  return g.manhattan a b .
end

$ lowentc --run distance alias.low 3 4
distance(3, 4) = 7

After use geom from "geom.low" as g . you call g.point and g.manhattan. The alias is a name used only inside this file; the module’s real name (geom) does not change. Inside this file, though, the original name no longer stands — writing geom.point is E-USE-ALIASED. An alias is a rename, not a second name: if a module could be called by two spellings, a reader would have to check that they mean the same thing. Importing the same name twice gives E-NAME-COLLISION, and the remedy that diagnostic suggests is this alias.

module mistake_aliasold .
rem expect: E-USE-ALIASED

use geom from "geom.low" as g .

fn origin_x output i64 .
do
  rem ✘ an alias was written, yet the original name is used --- the same module would be called by two spellings
  let p geom.point be make geom.point do x 7 . y 0 . end .
  return field p x .
end

$ lowentc --check mistake_aliasold.low
mistake_aliasold.low:9:9 E-USE-ALIASED: this unit renamed that module with `as`, so its name here is `g` — the original name no longer stands. One thing, one spelling: if both names worked, a reader would have to check that they mean the same module. Write the member under `g.`
mistake_aliasold.low:9:28 E-USE-ALIASED: this unit renamed that module with `as`, so its name here is `g` — the original name no longer stands. One thing, one spelling: if both names worked, a reader would have to check that they mean the same module. Write the member under `g.`

21.4 There is no search path#

Many languages fetch a module from somewhere on a search path when you write just its name. Then what the program depends on becomes knowledge outside the source, and the same source can bring in different files on different machines. Importing in Lowent is one of three things.

• Write the place: use geom from "geom.low" .
• Pass it in the same compilation unit: lowentc --check app.low geom.low
• Use a reserved standard-library name: use allocs .

The principle is the same when a package manifest (pkg.low) lists external dependencies. Dependencies are pinned with their content hash, and if the bytes change the build is refused (chapter 31).

21.5 When names collide#

A module cannot declare the same name twice.

module dup .
rem expect: E-NAME-DUP

fn answer output u32 . do return 1 . end
fn answer output u32 . do return 2 . end

$ lowentc --check dup.low
dup.low:5:4 E-NAME-DUP: `answer` (op) is declared twice in module `dup` — a qualifier cannot tell the two apart (both are `<module>.<name>`), so the second does not hide the first: it silently makes one of them unreachable

The second does not hide the first; rather, one of the two silently becomes unreachable, so it is rejected. When imported names collide, the call site names the module explicitly. Importing never overwrites a name that already exists (E-NAME-COLLISION).

21.6 Top-level order does not matter#

Top-level declarations in a module are independent of order. An op declared later can be called earlier, and ops can call each other.

module order .
rem run: is_even 10
rem run: is_even 7

fn is_even input n u32 . output bool .
  requires le n 1000 .
do
  if eq n 0 . do return true . end
  return is_odd (sub n 1) .
end

fn is_odd input n u32 . output bool .
  requires le n 1000 .
do
  if eq n 0 . do return false . end
  return is_even (sub n 1) .
end

$ lowentc --run is_even order.low 10
is_even(10) = 1
$ lowentc --run is_even order.low 7
is_even(7) = 0

is_even calls is_odd, declared after it, and is_odd calls is_even back. Local names inside an op body, on the other hand, must be declared before use. A file as a whole is skimmed, but a body is read top to bottom.

21.7 Common mistakes#

module mistake_bare .
rem expect: E-VISIBILITY

use geom from "geom.low" .

fn origin_x output i64 .
do
  rem ✘ an imported name is used without its module name
  let a point be make point do x 0 . y 0 . end .
  return field a x .
end

$ lowentc --check mistake_bare.low
mistake_bare.low:9:0 E-VISIBILITY: this name is another module's export, reached BARE — a cross-module name must be QUALIFIED: write `<module>.<name>` (RFC-0011 qualified-by-default; there is no glob import)
mistake_bare.low:9:0 E-VISIBILITY: this name is another module's export, reached BARE — a cross-module name must be QUALIFIED: write `<module>.<name>` (RFC-0011 qualified-by-default; there is no glob import)

module mistake_noext .
rem expect: E-DEP-MISSING

rem ✘ the place is the exact file name --- include `.low`
use geom from "geom" .

fn same input v i64 . output i64 .
do
  return v .
end

$ lowentc --check mistake_noext.low
E-DEP-MISSING: `use geom from "geom"` — cannot read that source. A dependency the tool cannot see is a dependency nobody checked

module mistake_filename .
rem expect: E-IR-UNDEF

rem ✘ the file is `lib/str.low`, but the module inside it is named `strings`
use str .

fn same input a slice u8 . input b slice u8 . output bool .
do
  return str.eq_str a b .
end

$ lowentc --check mistake_filename.low
mistake_filename.low:5:0 W-USE-EXTERNAL: this module is not in the compilation unit — there is no module search path, so nothing here can confirm it exists. Pass the file that declares it and it WILL be checked (several .low files link into one unit)
mistake_filename.low:9:0 E-IR-UNDEF: undefined name `str.eq_str` — `str` is not a module used by this unit (`use str .`) nor an enum

module filename_fixed .
rem run: same [104,105] [104,105]
rem run: same [104,105] [104,111]

use strings .

fn same input a slice u8 . input b slice u8 . output bool .
do
  return strings.eq_str a b .
end

$ lowentc --run same filename_fixed.low [104,105] [104,105]
same([104,105], [104,105]) = 1
  arg0 (written) = [104,105]
  arg1 (written) = [104,105]
$ lowentc --run same filename_fixed.low [104,105] [104,111]
same([104,105], [104,111]) = 0
  arg0 (written) = [104,105]
  arg1 (written) = [104,111]

module secretbox .
rem expect: W-EXPORT-HIDDEN

rem a type without `export` --- its name cannot be written outside this module
struct secret do
  v u64 .
end

rem ✘ an exported op returns the hidden type --- the importing side cannot write that name
export fn make_secret output secret .
do
  return make secret do v 1 . end .
end

$ lowentc --check secretbox.low
secretbox.low:10:0 W-EXPORT-HIDDEN: this op is exported and its signature names a type this module keeps to itself. An importing module cannot write that type, so it has nowhere to put the value and the export cannot be used from outside (§6.10.1). Export the type too, or give the op a signature made of types the other side can name

module mistake_privtype .
rem expect: E-VISIBILITY

use secretbox from "secretbox.low" .

fn peek output u64 .
do
  rem ✘ the type name needed to hold the result is hidden
  let s secretbox.secret be secretbox.make_secret .
  return field s v .
end

$ lowentc --check mistake_privtype.low
mistake_privtype.low:9:0 E-VISIBILITY: this name belongs to ANOTHER module and is not `export`ed — qualifying it does not open the door. A module that cannot keep anything private is not a module, it is a prefix. Mark it `export`, or stop reaching in (RFC-0011 §6.2)
secretbox.low:10:0 W-EXPORT-HIDDEN: this op is exported and its signature names a type this module keeps to itself. An importing module cannot write that type, so it has nowhere to put the value and the export cannot be used from outside (§6.10.1). Export the type too, or give the op a signature made of types the other side can name

module sizes .

rem an enum for other modules to use; its variants carry no value
export enum kind do
  small .
  big .
end

export fn classify input n u64 . output kind . do
  if lt n 100 . do
    return small .
  end
  return big .
end

$ lowentc --check sizes.low
== check: ok ==

module mistake_enumcase .
rem run: describe 5
rem run: describe 500

use sizes from "sizes.low" .

fn describe input n u64 . output u64 . do
  let k sizes.kind be sizes.classify n .
  match k do
    rem ✘ a variant with the module name in front; in this edition it matches any value
    case sizes.small do
      return 1 .
    end
    case sizes.big do
      return 2 .
    end
  end
end

$ lowentc --run describe mistake_enumcase.low 5
describe(5) = 1
$ lowentc --run describe mistake_enumcase.low 500
describe(500) = 2

module enumcase_fixed .
rem run: describe 5
rem run: describe 500

use sizes from "sizes.low" .

fn describe input n u64 . output u64 . do
  let k sizes.kind be sizes.classify n .
  match k do
    rem write only the variant name; the type (sizes.kind) decides which variant it is
    case small do
      return 1 .
    end
    case big do
      return 2 .
    end
  end
end

$ lowentc --run describe enumcase_fixed.low 5
describe(5) = 1
$ lowentc --run describe enumcase_fixed.low 500
describe(500) = 2

module cycle_a .
rem run: fa 3
rem run: fa 4

rem imports `cycle_b`, and `cycle_b` imports this module too
use cycle_b from "cycle_b.low" .

export fn fa input n u32 . output u32 .
  requires le n 10 .
do
  if eq n 0 . do return 0 . end
  return cycle_b.fb (sub n 1) .
end

$ lowentc --run fa cycle_a.low 3
fa(3) = 1
$ lowentc --run fa cycle_a.low 4
fa(4) = 0

21.8 This chapter’s syntax at a glance#