Appendix C: Standard Library Reference

This document lists every module in the ZuzuScript standard library.

javascript

Bridge to host JavaScript evaluation. This module is implemented by zuzu-js; other runtimes should treat it as implementation-specific.

Exports: JS, JSResult.

perl

Bridge to the host Perl interpreter, allowing controlled evaluation of Perl code and wrapping returned Perl values. It is primarily used for interop and data exchange from ZuzuScript. You should not expect this to work in alternative implementations of ZuzuScript, so it should be used sparingly.

Exports: Perl, PerlResult.

std/archive

Provides a small archive/compression API for reading and writing common container and compressed formats. It focuses on a portable archive dict shape containing file entries as binary payloads.

Exports: Archive.

std/cache/lru

Provides a small in-memory least-recently-used cache abstraction with bounded capacity. It is useful for memoization and for caching expensive computed values.

Exports: Cache.

std/clib

Provides dynamic C library loading and scalar FFI calls through explicit function signatures. Support is runtime-dependent and intended for carefully controlled native interop.

Exports: CLib.

std/colour

Provides colour parsing helpers. It normalizes three- and six-digit hexadecimal colours and CSS3 extended colour keywords to lowercase #rrggbb strings.

Exports: parse_colour.

std/config

Provides a high-level configuration framework for loading, merging, querying, and saving app config data. It supports format auto-detection, deep dictionary overlays, flat env-style key overlays, and direct path queries using @, @@, and @?.

Exports: Config.

std/data/cbor

Implements CBOR (Concise Binary Object Representation) encoding/decoding utilities in the standard library. It also includes a tagged-value wrapper for CBOR tags.

Exports: CBOR, TaggedValue.

std/data/csv

Provides CSV-style parsing and writing with configurable delimiters, quoting, and streaming file iteration. It also includes convenience helpers for importing/exporting database tables through std/db.

Exports: CSV, CSVReader.

std/data/ini

Implements INI text parsing and serialization with configurable formatting options. It is intended for config-file style key/value and section data.

Exports: INI.

std/data/json

Provides JSON parsing and serialization with optional pretty/canonical/UTF-8 behaviours. It is the standard JSON codec for structured Zuzu values.

Exports: JSON.

std/data/toml

Provides TOML parsing and serialization for dictionary-like configuration data. It includes helpers for loading from and dumping to paths.

Exports: TOML.

std/data/toon

Implements the TOON data format parser/encoder used by ZuzuScript tests and tooling. It supports options for strictness, indentation, and key/path expansion behaviour.

Exports: TOON.

std/data/xml

Provides XML parsing, loading/dumping helpers, and object wrappers for documents and nodes. It supports traversal, querying, and mutation of XML trees.

Exports: XML, XMLDocument, XMLNode, DOMNode, DOMDocument, DOMElement, DOMComment, DOMText.

std/data/xml/escape

Provides lightweight XML entity escaping and unescaping helpers for plain text values. It supports named entities and numeric entities (decimal and hexadecimal).

Exports: escape_xml, unescape_xml.

std/data/yaml

Implements YAML parsing and serialization with formatting controls for typical data-exchange workflows. It includes file load/dump convenience methods.

Exports: YAML.

std/db

Provides database connectivity and statement execution helpers over the runtime DB backend. It exposes connection and prepared-statement handle abstractions.

Exports: DB, DatabaseHandle, StatementHandle.

std/defer

Defines a guard object used to model deferred cleanup behaviour. The guard can be enabled/disabled and runs its callback during teardown.

Exports: Guard.

std/digest/crc32

Provides CRC-32 digest functions returning numeric, hexadecimal, or base64 forms. It is intended for checksums rather than cryptographic hashing.

Exports: crc32, crc32_b64, crc32_hex

std/digest/md5

Provides MD5 digest helpers for raw bytes and text encodings. It includes raw binary, hex, and base64 output forms.

Exports: md5, md5_b64, md5_hex.

std/digest/sha

Provides SHA-family hashing functions and HMAC helpers across several bit widths. It supports raw binary, hex, and base64 result encodings.

Exports: sha1, sha1_b64, sha1_hex, sha224, sha224_b64, sha224_hex, sha256, sha256_b64, sha256_hex, sha384, sha384_b64, sha384_hex, sha512, sha512_b64, sha512_hex, hmac_sha1, hmac_sha1_b64, hmac_sha1_hex, hmac_sha224, hmac_sha224_b64, hmac_sha224_hex, hmac_sha256, hmac_sha256_b64, hmac_sha256_hex, hmac_sha384, hmac_sha384_b64, hmac_sha384_hex, hmac_sha512, hmac_sha512_b64, hmac_sha512_hex.

std/dump

Provides a structured dumper that turns Zuzu values into readable, code-like text. It supports pretty-printing, optional color output, and cycle detection safeguards.

Exports: Dumper.

std/eval

Provides dynamic evaluation of Zuzu source strings within the runtime. It is primarily intended for controlled metaprogramming and tooling scenarios.

Exports: eval.

std/getopt

Provides command-line option parsing utilities with both spec-based and schema-based interfaces. It centralizes argv decoding and result shaping.

Exports: Getopt.

std/gui

Provides user-facing GUI constructor helpers, XML layout helpers, and binding utilities over the runtime-supported GUI object model. The Perl runtime uses Prima; zuzu-rust uses GTK4.

Exports: Window, VBox, HBox, Frame, Label, Text, RichText, Image, Input, DatePicker, Checkbox, Radio, RadioGroup, Select, Menu, MenuItem, Button, Separator, Slider, Progress, Tabs, Tab, ListView, TreeView, Widget, Event, ListenerToken, BindingToken, EM, bind, unbind, gui_from_xml, gui_from_xml_file, gui_to_xml, native_file_open, native_file_save, native_directory_open, native_directory_save, native_colour_picker.

std/gui/dialogue

Provides modal dialogue helpers for alerts, confirmations, prompts, file and directory pickers, and colour selection. When GUI access is denied, it falls back to terminal prompts using std/tui.

Exports: alert, alert_window, confirm, confirm_window, prompt, prompt_window, file_open, file_open_window, file_save, file_save_window, directory_open, directory_open_window, directory_save, directory_save_window, colour_picker, colour_picker_window.

std/gui/objects

Provides the runtime-supported GUI object classes and backend-native dialogue hooks used by std/gui. Most user code should import std/gui instead of this lower-level module.

Exports: Widget, Window, VBox, HBox, Frame, Label, Text, RichText, Image, Input, DatePicker, Checkbox, Radio, RadioGroup, Select, Menu, MenuItem, Button, Separator, Slider, Progress, Tabs, Tab, ListView, TreeView, Event, ListenerToken, native_file_open, native_file_save, native_directory_open, native_directory_save, native_colour_picker, meta.

std/internals

Exposes low-level runtime helper functions intended for internal/advanced modules. These helpers cover reflection-ish tasks, object allocation without __build__, and special property access. The API provided by this module should not be considered stable.

Exports: ansi_esc, class_name, getprop, make_instance, object_slots, ref_id, setprop.

std/io

Provides path and filesystem APIs plus standard input/output stream objects. It is the main I/O surface for reading/writing files and traversing directories.

Exports: Path, PathIterator, STDERR, STDIN, STDOUT.

std/io/socks

Provides socket helpers for TCP, UDP, and Unix-domain communication. It includes both listening and client connection entry points.

Exports: bind_udp, connect_tcp, connect_udp, connect_unix, listen_tcp, listen_unix.

std/lingua/en

Provides English-language formatting helpers for lists and numbers. It supports cardinal and ordinal wording with configurable cutoff behaviour.

Exports: english_list, english_number, english_ordinal.

std/log

Provides configurable structured-ish logging with levels and optional timestamps. It offers convenience level methods and a generic log entrypoint.

Exports: Log.

std/marshal

Provides Zuzu Marshal CBOR v1 binary serialization through dump, load, and safe_to_dump. It supports scalars, core collections, Times, Paths, marshalable user functions/classes/traits/objects, shared references, and supported cycles. load may evaluate embedded code records and run __on_load__, so marshal blobs are only appropriate for trusted data. Version 1 preserves weak object slots and weak collection entries using weak storage records; dead or non-strongly-reachable weak references load as weak null records.

Exports: dump, load, safe_to_dump, MarshallingException, UnmarshallingException.

std/math

Provides general math constants and static helpers for trigonometric, exponential, and numeric operations. It serves as the primary standard math namespace.

Exports: Math, π.

std/math/bignum

Provides arbitrary-precision numeric operations via a BigNum class. It supports decimal/hex constructors plus broad arithmetic and conversion methods.

Exports: BigNum.

std/math/range

Provides helper logic to abbreviate numeric lists into compact range-like representations. It is mainly geared toward reporting and diagnostics output.

Exports: abbreviate.

std/math/roman

Provides conversion of numbers into Roman numeral text. It includes support for integer and fractional twelfths notation.

Exports: roman.

std/net/http

Provides HTTP request/response primitives and user-agent utilities for network calls. It also includes cookie-jar support for request state.

Exports: CookieJar, Request, Response, UserAgent.

std/net/url

Provides URL escaping/unescaping, parsing, and template filling helpers. It is used for URL normalization and query/path manipulation tasks.

Exports: escape, fill_template, parse, unescape.

std/path/simple

Provides a simplified path-expression utility for navigating nested structures with concise selectors. It is a lighter-weight alternative to full ZPath queries.

Exports: SimplePath.

std/path/z

Provides a full ZPath query engine. See L<https://zpath.me>.

Exports: ZPath.

std/path/z/context

Internal support module for std/path/z evaluation contexts. It is documented for maintainers, but normal users should import std/path/z.

Exports: Ctx.

std/path/z/evaluate

Internal evaluator for parsed ZPath expressions.

Exports: Evaluator.

std/path/z/functions

Internal function registry for ZPath evaluation.

Exports: Func, STANDARD_FUNCTIONS.

std/path/z/lexer

Internal lexer for ZPath expressions.

Exports: Lexer.

std/path/z/node

Internal node wrappers used by the ZPath evaluator for arrays, dicts, sets, bags, XML nodes, paths, times, and scalar values.

Exports: Node, SimpleNode, StringNode, NumberNode, BooleanNode, NullNode, ArrayNode, SetNode, BagNode, DictNode, PairListNode, PairNode, XmlNodeNode, TimeNode, PathNode.

std/path/z/operators

Internal operator registry and helper trait for ZPath evaluation.

Exports: EvalHelpers, Operator, STANDARD_OPERATORS.

std/path/z/parser

Internal parser for ZPath expressions.

Exports: Parser.

std/proc

Provides process execution and signal helpers, including pipeline orchestration and environment utilities. It is the standard interface for subprocess control.

Exports: Env, Proc.

std/string

Provides common string manipulation and formatting helpers used across user modules and serializers. It includes substring, search, case conversion, and join/split helpers.

Exports: camel, chomp, index, join, kebab, pad, pattern_to_regexp, replace, rindex, search, snake, split, sprint, substr, title, trim.

std/string/base64

Provides base64 and URL-safe base64 encode/decode helpers. It converts between binary values and textual transport forms.

Exports: decode, decode_urlsafe, encode, encode_urlsafe.

std/task

Provides the task type, cancellation objects, channels, timers, and combinators used with async, await, and spawn.

Exports: Task, Channel, CancellationToken, CancellationSource, CancelledException, ChannelClosedException, TimeoutException, resolved, failed, sleep, yield, all, race, timeout.

std/template/z

Provides a full ZTemplate templating engine. See L<https://zpath.me>.

Exports: ZTemplate.

std/time

Provides time value and parser utilities, including format-driven parsing of date/time strings. It is the standard time abstraction for core scripts.

Exports: Time, TimeParser.

std/tui

Provides terminal UI helpers for ANSI colour, stdout writing, readline, and file/directory completion. It is used by GUI dialogue fallbacks when GUI access is denied.

Exports: ansi_esc, supports_ansi, colour_text, write, write_line, readline, readline_supports_completion, filename_completions, directory_completions.

std/uuid

Provides UUID generation helpers for both textual and binary forms. It is intended for unique identifier generation in app and test contexts.

Exports: create_uuid, create_uuid_binary.

std/worker

Provides isolated workers for shared-nothing parallel work. Worker payloads, return values, and messages are copied through std/marshal; if std/worker imports successfully, workers are available. The module requires the worker runtime capability.

Exports: Worker, WorkerHandle.

test/more

Provides TAP-style assertion helpers for tests, including ok/is/isnt-style checks and subtests. It is the common ergonomic testing layer for Zuzu test scripts.

Exports: BailOutException, bail_out, diag, done_testing, exception, explain, fail, is, isnt, like, ok, pass, plan, subtest, unlike.

test/parser

Provides parsing helpers for TAP-like test output into structured counters and result rows. It is used by the test toolchain to interpret test streams.

Exports: parse, parse_lines.