The standard library
10 modules under lib/, 146 public declarations between them. A module arrives by name through import; nothing in it is ambient, and nothing is in scope that was not imported.
What counts as the standard library
Three tiers, distinguished by WHY a piece of code is where it is rather than by what it does. The distinction decides where a contributor puts something new, so it is stated here and not left to precedent.
| tier | what | where | how it arrives |
|---|---|---|---|
| 1 | the pinned prelude | ++prelude in lib/jock.hoon | ambient — no import, frozen; see the ABI |
| 2 | a library module written in Jock | lib/*.jock — this page | import <name>; with the directory on --data-dir |
| 3 | a curated Hoon core, jammed | pkgs/*.jam via tools/pkg.sh | import <name>; against a built jam |
Tier 1 is what a program cannot reasonably be written without, and an addition to it is an ABI event. Tier 2 is what is expressible in Jock without a new ABI arm and that two unrelated programs would both want. Tier 3 is for where substantial tested Hoon already exists and a Jock version would be a rewrite rather than a port — nothing in a tier 3 package is jetted, which is the argument for keeping the tier small.
The modules
| module | what it is | types | arms | pinned |
|---|---|---|---|---|
hof | higher-order functions over closures and List | 0 | 18 | 18/18 |
http | the NockApp http driver, from the Jock side | 3 | 19 | 13/22 |
interval | interval arithmetic over exact rationals | 1 | 3 | 3/4 |
nockapp | the NockApp host's own effect vocabulary | 1 | 0 | 1/1 |
parser | parser combinators | 7 | 31 | 33/38 |
rand | deterministic pseudo-random numbers | 1 | 11 | 10/12 |
rational | exact rational arithmetic over Int | 0 | 9 | 9/9 |
time | civil dates, ISO 8601, and the Urbit @da | 10 | 22 | 23/32 |
twoc | two's-complement signed integers at arbitrary bit width | 1 | 7 | 7/8 |
urbit | Urbit-native conversions, in Jock | 0 | 2 | 2/2 |
How an arm is pinned
An arm is pinned when an example in examples/ names it. 7 modules have an examples/<name>-arms.jock — a sheet whose every line asserts one arm, which fails the lane if the arm stops doing what the line says. That is the strongest pin a reference can cite, and each arm page quotes the line.
one line of examples/hof-arms.jock
assert hof.compose(inc, dbl)(10) == 21;
An arm named only by an ordinary program is marked a use: the call shape is demonstrated but no assertion fixes the result. An arm named by nothing is marked — and listed on its module page, because a reference that quietly omitted it would read as though the coverage were complete.
What no lane pins
27 of 146 public declarations are named by no example — DIRECTLY; an arm reached only through a pinned caller is not counted. The gap is not spread evenly: 7 modules have an arms sheet and http, nockapp, urbit do not.
http— 13 of 22 pinned, no arms sheetinterval— 3 of 4 pinnedparser— 33 of 38 pinnedrand— 10 of 12 pinnedtime— 23 of 32 pinnedtwoc— 7 of 8 pinned
What is in the library and not on this site
4 modules are not documented here, and they are left out on purpose rather than pending. Each targets nockchain, and each one’s interface is half of a contract with a driver this project does not own — documenting an arm publishes a surface, and a surface nobody upstream has committed to is one these pages would be promising on someone else’s behalf.
chainkey— the nockchain key family (11 declarations)chainrand— the nockchain generator (8 declarations)chaintx— the nockchain transaction molds and hashes (64 declarations)wallet— the wallet driver effects, which only the signer kernel emits (1 declaration)
They compile and they are built by tools/modules.sh on every push, so this is a documentation boundary and not a support one. A reader who needs them has the source.
What generates this
tools/stdlib.py parses every top-level declaration in crates/jockc/hoon/lib/*.jock for its kind, name, generic binders and signature, together with the comment block above it, and joins that against the examples that import the module. tools/refgen.py --check regenerates and fails on a diff, so a module that gains an arm reddens a lane until the page is rewritten.
The prose on each arm is the comment in the module source, reproduced and not paraphrased. A paraphrase would be a second copy to maintain, and it is the copy a reader of the source would never see go stale.