This library is in flux. APIs may change without notice. Generated from source with koruc 0.1.7 on 11/17/2026.
Guide
import std/guideguide.kz — std/guide: attach teaching surfaces to tors/edges as dead
guide.kz · 5 tors
guide.kz — std/guide: attach teaching surfaces to tors/edges as dead · 19 more lines
guide.kz — std/guide: attach teaching surfaces to tors/edges as dead
AST data, looked up by key at runtime.
The module is deliberately dumb: it stores (key -> template) pairs
harvested from the program AST at compile time and answers key lookups.
It does not know what a template IS — rendering is the caller's job
(Liquid engine or whatever the smart tool chooses).
Attach (write side, comptime|norun — dead data, never executed):
std/guide:add(my-thing) { ...template... }
std/guide:add(book-flight | error) { ...lesson... }
Read (evaluated expression, dynamic key):
std/guide:lookup(table, key: guide:key("book-flight", branch))
| guide template |> ...render/inject...
| not-found |> ...silence is default...
The key contract: BOTH sides build keys through guide:key so the
attach-time name and the query-time string can never drift.
// ADD — attach a teaching surface. Comptime-harvested, never run.
// `target` is the Expression naming what this attaches to (a tor, or
// `tor | branch` for an edge); `source` is the template body.
//
// Target syntax follows the std/taps transition idiom — `source -> dest`
// parsed from the Expression text, with glob wildcards:
// std/guide:add(book-flight -> error) { ... } // one edge
// std/guide:add(book-flight -> *) { ... } // every edge of a tor
// std/guide:add(* -> error) { ... } // that edge, any tor
// std/guide:add(book-flight) { ... } // tor-level (no arrow)
//
// `add` IS the transform: each guide:add(...) invocation is intercepted by
// the transform runner (import std/guide puts it in the AST; the runner
// finds it — no pass wiring, no import magic). The proc harvests the
// entry; table delivery is the remaining piece.
~[comptime|transform] pub tor add {
expr: Expression,
source: Source,
invocation: *const Invocation,
item: std/compiler:*const Item,
program: std/compiler:*const Program,
allocator: std.mem.Allocator
} -> SiteResult// KEY — the attach/query contract. One builder, both sides.
// Canonical form mirrors the taps `src -> dest` idiom:
// "<tor>-><branch>"; tor-level attaches use the bare tor name
// (branch "" yields just the tor).
~pub tor key { tor: string, branch: string } -> stringdefault
koru_std/guide.kz:116// DEFAULT — the read side, invoked as `std/guide(key)`. Module-as-tor:
// the table is module-internal compiled data (transform harvest), not a
// caller param. `guide` binds the template; `not-found` is the silent
// default until harvest lands — an empty table truthfully finds nothing.
~pub tor default { expr: Expression }
| guide string
| not-foundlookup
koru_std/guide.kz:156// Evaluated-key entry point: `key: string` goes through the emitter's normal
// expression path, so callers compose keys with guide:key(...) or build them
// dynamically — interpolation, concatenation, whatever the language gives.
// The `tor -> branch` transition sugar stays on `default`; both share
// lookupTemplate, so wildcard semantics can never drift between them.
~pub tor lookup { key: string }
| guide string
| not-found~[comptime] pub tor collect {
ctx: koru_compiler_types.CompilerContext,
output_path: string
} -> koru_compiler_types.CompilerContext~part match koru_std/guide.match.kz
guide.match.kz — the table read + match half of std/guide: the row lookup every entry point shares (exact key first, then best wildcard specificity). Split out of guide.kz when the pub match API grew the file past its pin; joined via `~part match`. A matched table row: the PATTERN key that fired (which may be the query key itself, or a wildcard row like `*->error`) and its template. Both slices are owned by the caller's allocator.