Standard Library Reference

Canonical built-in reference aligned with interpreter/builtins_*.go. Karl is expression-based, functions-first, and concurrency-native. Streams/processes are major features, but part of a broader language model.

1. Language Model

These are language forms (not regular built-ins):

• if / match / for are expressions (produce values).
• spawn and & start tasks.
• race and !& race tasks.
• wait awaits <task> and <process>.
• | composes stream sources, stages, and sinks.

2. Runtime Availability

3. Prebound Constants

4. Core Runtime

5. Concurrency Helpers (Built-ins)

6. Program Runtime

7. Collections

Karl has four collection families: Array, Map, Set, ordered tree, and hierarchical ntree.

7.1 Constructors and Core Shapes

7.2 Map and Set Operations

7.3 Ordered Tree: tree(kind?)

Ordered key-value index (sorted by key). Key domain is homogeneous: int, float, string, or char.

let prices = tree("avl")
let seeds = [18, 22, 27, 35, 44, 56, 63, 71, 89]
seeds.forEach(p ->
    prices.set(p, { sku: "p-" + str(p), price: p, })
)
log("floor50:", prices.floor(50))
log("ceil50:", prices.ceil(50))
log("nearest42:", prices.kClosest(42, 3))
log("median:", prices.select(4))
log("rank35:", prices.rank(35))
log("valid:", prices.validate())

7.4 Hierarchical Tree: ntree(rootId, rootValue?)

Explicit parent/children hierarchy for topology navigation.

let topo = ntree("root", { label: "Root", })
topo.append("root", "api", { label: "API", })
topo.append("root", "worker", { label: "Worker", })
topo.append("api", "http", { label: "HTTP", })
topo.append("worker", "jobs", { label: "Jobs", })

log({
    depthJobs: topo.depth("jobs"),
    lca: topo.lca("http", "jobs"),
    path: topo.pathBetween("http", "jobs").map(n -> n.id),
})

8. Sequence Operators

These are overloaded between arrays and streams (where noted).

9. Strings

10. Encoding + Data

11. Time / UUID / Crypto

12. Math + Random

13. Filesystem

14. HTTP

15. SQL

16. Signals

17. Process API

Process members:

p.pid
p.running
p.stdin   // available when stdin: PIPE
p.stdout  // available when stdout: PIPE
p.stderr  // available when stderr: PIPE
p.abort()
p.kill()
p.signal("SIGTERM")

Status objects:

wait p -> { ok, code, signal, timedOut, aborted, durationMs, }
run(...) -> { ok, code, signal, timedOut, aborted, durationMs, output, error, outputTruncated, errorTruncated, }

18. Stream API

18.1 Sources

read(path, opts?)
stdin(opts?)
http(url, opts?)
fromChannel(ch)
merge(a, b, ...) or merge([a, b, ...])
zip(a, b)
join(left, right, leftKeyFn, rightKeyFn)

18.2 Stages

lines()
fromJson()
toJson()
fromUtf8()
toUtf8()
map(fn)
filter(fn)
flatMap(fn)
distinct()
sort([cmp])
take(n)
drop(n)
chunk(size)
window(size, step)
throttle(ms)
debounce(ms)
tee(sink)
spill(path, opts?)

18.3 Sinks

stdout()
write(path, opts?)
collect()
toChannel(ch)
send(ch)
reduce(init, fn)
forEach(fn)
count()
group_count([keyFn])
reduce_by_key(keyFn, init, reducerFn)
top(n[, scoreFn])
partition(selector[, branchKeys])
split(pred)
exec(specOrCommand...)

18.4 Stream Handle Members

// source or plan
s.read()      // [item, eof]
s.close()

// reader
r.read([size]) // [chunk, eof]
r.close()

// writer
w.write(chunk) // bytes written
w.close()

19. Method Sugar

20. Non-Obvious Examples

Overloaded map: constructor, array transform, stream stage

let m = map()
let xs = map([1, 2, 3], x -> x * 2)
let ys = read("items.txt", { type: TEXT, }) | lines() | map(_ + "!") | collect()

partition(selector, keys): branch into named streams

let branches = read("events.ndjson", { type: TEXT, })
    | lines()
    | filter(_ != "")
    | fromJson()
    | partition(e -> e.level, ["ERROR", "WARN", "INFO"])

let errors = branches.ERROR | count()
let warns = branches.WARN | count()
log({ errors, warns, })

join(left, right, leftKeyFn, rightKeyFn)

let users = read("users.ndjson", { type: TEXT, }) | lines() | filter(_ != "") | fromJson()
let orders = read("orders.ndjson", { type: TEXT, }) | lines() | filter(_ != "") | fromJson()

let joined = join(users, orders, u -> u.id, o -> o.user_id) | collect()

run vs proc

let st = run("kubectl", "get", "ns") // blocking capture

let p = proc("kubectl", "logs", "-f", "deploy/api", { stdout: PIPE, stderr: NULL, stdoutType: TEXT, })
let [line, eof] = p.stdout.read()
let final = wait p

HTTP stream + JSON stage

let byTeam = http("https://example.com/events.ndjson", { type: TEXT, })
    | lines()
    | filter(_ != "")
    | fromJson()
    | group_count(_.team)

exec sink: pipe stream output into external command

let st = read("app.log", { type: TEXT, })
    | lines()
    | filter(_.contains("ERROR"))
    | exec("wc", "-l", { maxOutputBytes: 1024, })

log(st.output.trim())

stream cursor semantics

let s = read("events.log", { type: TEXT, }) | lines()
let [a, eofA] = s.read()
let [b, eofB] = s.read()
s.close()
let [c, eofC] = s.read() // [null, true]

21. Compatibility Notes

• Prefer http(url, opts?). Legacy blocking http({ method, url, ... }) remains for compatibility but is not the recommended style.
• Some built-ins are overloaded intentionally (map, split, send). This page lists each valid shape explicitly.