32 A map of the standard library

32.1 Three layers — language, leaf, library#

There is one question deciding whether a piece is a leaf — “can this be written in Lowent?” If it can, it is library. Opening a file and receiving an integer handle reaches the kernel, so it is a leaf. Wrapping that handle in an owned value that cannot be forgotten can be written in Lowent, so it is library. A convenience op that reads a whole file is also library. Convenience does not qualify something as a leaf.

The standard library has no privileges. It gets the same rules as code the author writes — contracts, effects, capabilities. Here is the source of strings.starts_with.

export fn starts_with input s str . input prefix str . output bool . do
  guard le (len prefix) (len s) . else return false .
  return eq_str (subslice s 0 (len prefix)) prefix .
end

It reads with only what this book has taught. If there were a hidden passage only the library could use, a program’s guarantees would break the moment it passed through.

32.2 What gets in#

Things enter the library not because they exist but on evidence. The specification’s charter sets six measures.

Every module writes its maturity — experimental (merely written), incubating (has a decision document), standard (documented and named by regression tests) and deprecated (says what to move to). The value of the ladder is in the lower rungs, not the upper. Writing experimental writes “do not trust this yet” in the source. A rung is not a ranking of quality but the size of a promise.

The specification does not list the library’s contents. What exists is authoritatively recounted from the source each time, and a document copying it diverges from the moment it copies. Three APIs that did not actually exist were once read as fact because they were in a table. The tables in this part were also made by looking at this edition’s source, and detailed per-module pages are in Appendix E.

32.3 The map by layer#

The remaining chapters of this part group by use: text and encodings (chapter 33), containers and sorting (chapter 34), storage and handles (chapter 35), input/output, networking and cryptography (chapter 36), and the terminal (chapter 37).

32.4 File names and module names#

What use looks for is the module declaration inside the file. In a few places it differs from the file name.

module names .
rem run: is_get [71,69,84,32,47]
rem run: is_get [80,79,83,84]

use strings .

fn is_get input line slice u8 . output bool .
do
  return strings.starts_with line "GET " .
end

$ lowentc --run is_get names.low [71,69,84,32,47]
is_get([71,69,84,32,47]) = 1
  arg0 (written) = [71,69,84,32,47]
$ lowentc --run is_get names.low [80,79,83,84]
is_get([80,79,83,84]) = 0
  arg0 (written) = [80,79,83,84]

use strings . resolves from the standard module location without from. Imported names are always called qualified by module, as in strings.starts_with. There is no glob import. Importing by file name finds no such module.

module wrong_name .
rem expect: W-USE-EXTERNAL

use str .

fn is_get input line slice u8 . output bool .
do
  return true .
end

$ lowentc --check wrong_name.low
wrong_name.low:4: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)

The diagnostic is a warning rather than an error because there is no search path, so looking at this translation unit alone cannot tell whether the name exists somewhere (chapter 21). The moment the name is actually used, it is rejected.

32.5 Conventions every module follows#

32.6 The list of leaf ops — what lies beneath the modules#

Library modules ultimately call leaf builtin ops provided by the processor. Normally you use the module and do not call the leaves directly — the module dresses them in conventions such as ownership, three-place answers and all-or-nothing. Still, knowing which module stands on what keeps you oriented when reading module documentation or building a new module.

Computation leaves stand only after call_builtin — call_builtin sha256 msg out. The name lives in that position and never becomes a global word: a word a program uses once should not cost every reader a name to remember. The stage names inside pipe and the type slot of cast u8 x already work this way. Leaves that touch the operating system (file_open, net_send, …) are called plainly — their first operand is a capability, so their specialness already shows.

The qualification for a leaf is one question: “can it be written in Lowent?” rng_next and the three hashes are pure computation yet leaves, because the processor fixes their algorithms so that the VM and the native build give bit-identical answers. Every leaf that needs a capability takes it as the first operand (chapter 16).

32.7 Common mistakes#

module mistake_chainnone .
rem run: greet [0,0,0,0,0,0,0,0,0,0,0,0]
rem trap: greet [0,0,0,0,0,0]

use fmt .

proc greet input buf mut slice u8 . output u64 . effects none .
do
  rem ✘ trusts that the previous write succeeded and chains on with `some_value`
  let p u64 be some_value (fmt.put_str buf 0 "hello") .
  let q u64 be some_value (fmt.put_byte buf p 32) .
  return some_value (fmt.put_u64 buf q 42) .
end

$ lowentc --run greet mistake_chainnone.low [0,0,0,0,0,0,0,0,0,0,0,0]
greet([104,101,108,108,111,32,52,50,0,0,0,0]) = 8
  arg0 (written) = [104,101,108,108,111,32,52,50,0,0,0,0]
$ lowentc --run greet mistake_chainnone.low [0,0,0,0,0,0]
== ir diagnostics (1) ==
0:0 E-VM-NONE: some_value of none (panic)

module chainnone_fixed .
rem run: greet [0,0,0,0,0,0,0,0,0,0,0,0]
rem run: greet [0,0,0,0,0,0]

use fmt .

proc greet input buf mut slice u8 . output u64 . effects none .
do
  rem ask at every step --- when short, return 0 to report "could not write"
  let p option u64 be fmt.put_str buf 0 "hello" .
  guard is_some p . else return 0 .
  let q option u64 be fmt.put_byte buf (some_value p) 32 .
  guard is_some q . else return 0 .
  let r option u64 be fmt.put_u64 buf (some_value q) 42 .
  guard is_some r . else return 0 .
  return some_value r .
end

$ lowentc --run greet chainnone_fixed.low [0,0,0,0,0,0,0,0,0,0,0,0]
greet([104,101,108,108,111,32,52,50,0,0,0,0]) = 8
  arg0 (written) = [104,101,108,108,111,32,52,50,0,0,0,0]
$ lowentc --run greet chainnone_fixed.low [0,0,0,0,0,0]
greet([104,101,108,108,111,32]) = 0
  arg0 (written) = [104,101,108,108,111,32]

module all_or_nothing .
rem run: try_put [0,0,0,0]

use fmt .

proc try_put input buf mut slice u8 . output u64 . effects none .
do
  rem six bytes into four slots --- instead of writing the first four, it writes none
  let p option u64 be fmt.put_str buf 0 "Lowent" .
  guard is_some p . else return 99 .
  return some_value p .
end

$ lowentc --run try_put all_or_nothing.low [0,0,0,0]
try_put([0,0,0,0]) = 99
  arg0 (written) = [0,0,0,0]

32.8 This chapter’s syntax at a glance#