PatLang Standard Library & Host Function Reference

For new readers

A "host function" is a built-in function implemented in the underlying Rust runtime rather than written in PatLang itself — things like list_push or vfs_read below. This page is an alphabetised-by-topic catalogue of that surface, grouped into "chunks" (explained in the section just below — essentially a bundling/dead-code-elimination mechanism, not something you need to think about to just call the functions). Use this page for lookup once you know roughly what you're after; the Paradigms Guide is a better starting point if you're still building a mental model of what PatLang can do.

Most of what PatLang can do lives behind function calls rather than grammar — see the Grammar & Syntax page for what's actually parsed. This page catalogues that surface at two levels: the built-in host functions implemented directly in the Rust runtime and organised into named chunks, and the PatLang-level library — real .patlang source files under self_hosting/lib/ that build on those hosts.

The chunk system

Host functions are grouped into named chunks (ChunkId values), each contributing a fixed slice of Rust prelude text to a compiled program. A program only pulls in the chunks it actually uses — this is PatLang's dead-code elimination, and it currently operates at whole-chunk granularity, not per-function. Two chunks cross-depend on each other structurally: math pulls in numeric_tower, and oo pulls in logic (because send's relation-inference dispatch reads state declared by the logic chunk). numeric_tower itself is a real chunk with no named entry point — it's selected whenever an operation actually needs the full numeric tower, not called directly.

core

list_get, list_len, list_push, list_set, type_of. Note: list_push/list_set clone the whole backing list on every call unless the caller is the sole owner — see Best Practices for when to reach for the handle-based vec_* builders below instead.

Bitfield helpers

bit_get, bit_set, bit_slice, bit_set_slice — read/write individual bits or bit ranges of an integer. See the Grammar reference for the word-form bitwise operators (band/bor/bxor/shl/shr) these helpers complement, and the bitwise demo for both in a worked example.

Virtual filesystem

vfs_read, vfs_write, vfs_append, vfs_exists, vfs_list, vfs_delete — an in-memory filesystem available on every target including WASM, unlike read_file/write_file (real, native-only disk I/O). vfs_append pushes onto the existing stored string directly — true O(new content) amortized, not a read-modify-write of everything already there. A separate, explicit, native-only vfs_flush_to_disk write-throughs to real files, gated by an allowed-root check. See the VFS demo for a full worked example.

strings_ext

char_code, substr, chr, to_num, hash_string.

collections_handles

A parallel, handle-based collection API alongside the plain-list functions in core: vec_new, vec_push, vec_set, vec_get, vec_len, vec_to_list, plus string-builder helpers sb_new, sb_push, sb_str, and interned-string helpers str_intern, sc_len, sc_code, sc_char. See Idioms & Patterns for when to reach for a handle-based vec_* over a plain list_*.

files

read_file, write_file, touch_file, file_exists. Note the Windows gotcha documented in the PatLang repo's own CLAUDE.md: exec_capture-style process launches need a path separator in the executable name (./patc1.exe, not bare patc1.exe) — CreateProcess's SafeProcessSearchMode excludes the working directory when searching for a bare filename, even though file_exists correctly reports the file present.

io_misc

now_ms, byte_length, read_line, argv, print, plus a set of small arithmetic/utility helpers that predate the dedicated math chunk: sed, add, multiply, subtract, max, min, calculate, calculate_result, get_value, process, validate, len.

oo

new, set_var, get, send — the plain object-store primitives — plus class_def, the host function the real class NAME [inherits PARENT] { ... } grammar (see the Grammar reference) lowers to: registers a class's field defaults, methods, and composed traits once, so a later new(class, id) can resolve them. See the Paradigms Guide for the full object-orientation surface, plain and class-based alike.

logic

fact, query, goal, infer_type_for — direct fact lookup, no rule-based inference. Real rule-based inference with backtracking lives in this same chunk's rule_add/solve/goal_def/action_add/action_bind/action_lookup/action_label_args/plan/pursue — see the Rule Declarations grammar section for the real rule/goal declarative syntax these back, and the goal-oriented demo for a full worked example of the planner.

contracts

One function, contract_check, backing all of require/ensure/assert — see the contracts section of the Paradigms Guide.

networking

tcp_listen, tcp_connect, tcp_accept, tcp_accept_timeout, tcp_read, tcp_write, tcp_close, sleep_ms. Raw sockets, no HTTP framing built in — the Ollama client and the echo server both hand-roll HTTP/1.1 on top of these.

codegen_bootstrap

parse_tiny_source, lower_and_compile, emit_rust_for, copy_file, patc_compile_from_argv, get_argv, rustc_build, run_ir — the primitives the self-hosted compiler pipeline itself is built from. rustc_build_chunked and rustc_build_chunked_texts are the chunk-precompile-and-link alternative to rustc_build's "concatenate everything, recompile from scratch" approach — see Act XXI for the story and the ~5.7× measured win on repeated small-program compiles, and The PatLang Compiler Pipeline for how the lower/emit_rust/emit_x64/emit_wasm/interpret pipeline stages fit together, including the self-hosted meta-circular interpreter.

math

sqrt, pow, sin, cos, tan, asin, acos, atan, atan2, log, exp, floor, ceil, round, trunc, abs, numeric_kind. sqrt promotes a negative real input to Complex but explicitly rejects a Complex input — there is no complex square root.

Outside the chunk system: parallel_map, fibers, and budgeted

parallel_map, the four fiber functions (fiber_new, fiber_resume, fiber_yield, fiber_alive), and the two functions backing budgeted(...) (budgeted_run, budget_check — not normally called directly, emitted by the lowerer wherever budgeted(...) appears in source) are real, working, but genuinely not part of HOST_CHUNK_TABLE — they're special-cased by name directly in the interpreter and Rust codegen rather than routed through the generic chunk-prelude mechanism everything above uses. This is a real structural asymmetry, not an oversight to gloss over: it means the dead-code-elimination and cross-chunk-dependency machinery described above simply doesn't apply to concurrency. All three work across interpreted, natively-compiled, and self-hosted-compiled programs alike — fibers used to be interpreter-only, but compiled-native fiber support has since been ported directly into the generated program's own runtime text (mirrored in self_hosting/lib/runtime_rs.patlang). WASM is now a split, not a flat "no": the ordinary wasm32-wasip1 target still has no real OS-thread support, so all of these still return a clear runtime error there, but a second, opt-in wasm32-wasip1-threads target (nightly toolchain, atomics codegen flags) genuinely runs fibers and budgeted(...), verified both under wasmtime and live in a real browser via a hand-rolled WASI-threads JS shim (see the fiber demo). parallel_map's cfg gate now compiles for the threaded target too, in principle, but that path is unverified/undemoed so far.

The PatLang-level library (self_hosting/lib/*.patlang)

Above the host-function floor sits a real standard library written in PatLang itself:

math.patlang — factorial, is_prime, hypot, gcd, lcm, clamp, sign, mean, built on the host math chunk.
json.patlang — a minimal recursive-descent JSON parser (objects, arrays, escaped strings, numbers, true/false/null) producing tagged-list values.
markdown.patlang — the Markdown-subset renderer this very site's generator uses (headings with TOC IDs, fenced code, bullet lists, tables, inline code/bold/links).
regex.patlang / regex_dsl.patlang — a general-purpose regex engine written in pure PatLang, with a Stage-1-dialect twin restricted to self-hosted-pipeline-available host functions.
report.patlang — a project-report simulator: goal-oriented task dependency resolution, worker roles as objects, QA-gated stages, a virtual clock for animated timeline replay.
maze.patlang — a maze solver combining logic-programming facts, goal-oriented search, and event-driven solved/unsolved reporting.
pos.patlang — a point-of-sale library: events for scan/pay, a product catalogue as objects, a dairy-discount rule as logic.
ollama.patlang — a shared Ollama HTTP client built directly on raw TCP sockets, including chunked-response handling.
test.patlang — a test framework: plain unit assertions plus a Gherkin-style feature runner with text-registered step definitions.
reflect.patlang — reflection: turns source text into its own AST, then into JSON, by reusing the self-hosted lexer and parser as a library.
transpile_ruby.patlang — transpiles the self-hosted AST to idiomatic Ruby, explicitly raising on any construct or host call it can't translate rather than emitting silently-broken output.
template.patlang — the general page/section templating library this site's own PatLang-authored portfolio pages are built with, using a tagged-tuple data model and one recursive dispatch function.
event_loop.patlang — a reusable single-threaded, JS/Node-style event loop built on tcp_accept_timeout and sleep_ms.
html.patlang — an HTML5/JS page builder, used wherever the browser is PatLang's GUI.
syntax_dsl.patlang — the self-hosted-dialect twin of the native CLI's DSL preprocessor, expanding syntax NAME { ... } blocks on raw source before lexing.

Three further files are compiler internals rather than application library, listed here for completeness: lexer.patlang, parser.patlang, and lower.patlang (the self-hosted front end) and codegen.patlang/runtime_rs.patlang (the self-hosted back end and its generated runtime prelude mirror).