Docs / Standard library

Standard library direction

What ships today, how operations are named, and the proposed example-driven growth plan.

Browse documentation
On this page

Zhex ships a small host library for text, typed collections, JSON, files, buffers, console input/output, errors, and temporal values. The complete current inventory and research lists all 119 registered host names and their test/reference evidence. Constructors, operators, bracket access, and REPL commands are separate facilities.

A dot identifies an operation’s owner or domain: text.trim, list.length, file.read. Compound names use hyphens. Flows pass their value as the first argument. Conversions are explicit, as in int.to-string.

Text positions count Unicode code points. Collections have shared identity and guard active traversal against mutation. Ordinary computations return ordinary values; external input and parsing failures use explicit Results. See the text, collections, files, results, and temporal references for implemented behavior.

Proposed next work

The research compares Go, Ruby, Python, Gleam, Elm, and Haskell. Its recommendation is to validate a few additions through a line-filter/report program, then grow reusable collection composition:

  1. Literal text split/join and prefix/suffix checks (#57), then writing a report to a file (#58).
  2. Collection map/filter/fold using existing function values, with explicit callback order and aliasing rules (#60).
  3. Short-circuit search (#61) and stable copied sorting (#62); fallible traversal is a separate design step.
  4. Paths, environment configuration, and other host capabilities only when a concrete program needs them.

These additions are proposals, not available APIs — except #57’s literal text operations (text.split, text.join, text.starts-with, text.ends-with), which shipped into the text reference, and #58’s file.write(contents, path, append = false), which shipped into the files reference with built-in trailing constant defaults; and #60/#61’s list callback words (list.map, list.filter, list.fold, list.find, list.any, list.all), which shipped into the collections reference with ordinary function-value callbacks; and #62’s list sorting words (list.sort, list.sort-by), which shipped into the collections reference as stable ascending copies over List<Int>/List<String> values or Int/String keys; and #73’s file inspect words (file.list, file.exists, file.size, file.free-space), which shipped into the files reference from the #69 folder-operations research; and #74’s lexical path words (file.join, file.base, file.extension, file.directory-of), which shipped into the files reference as pure String operations with no filesystem access; and #75’s destructive file words (file.make-folder, file.delete, file.delete-folder, file.move), which shipped into the files reference from the same research with built-in trailing mode defaults; and #76’s json.parse(raw), which shipped into the json reference as a Result<Json, Error> over the host-predeclared Json tree type, with json.encode accepting trees; and #79’s xml.decode(text, defaults), which shipped into the xml reference as a schema-directed Result<T, Error> over the stdlib encoding/xml tokenizer with attribute fields, repeated-element lists, and xml-* codes in the common Error family; and #70’s select-by-predicate words (list.select, array.select), which shipped into the collections reference keeping the elements a predicate accepts, unmodified; and #64’s environment words (env.get, env.load), which shipped into the environment reference as the total Option lookup and the first-assignment-wins .env loader with env-read/env-parse codes (its path words had shipped as #74). The research and draft stories record proposed signatures, dependencies, error policies, tests, and deferred capabilities. The owner approved filing stories #57–64 for one-by-one review; they were initially filed in Inbox and then moved to Todo at the owner’s request, and #57, #58, #60, #61, #62, #64’s environment half, #70, #73, #74, #75, #76, and #79 have since shipped, in the owner’s approved order (S9 → S11 → S10, then the JSON tree, predicate select, XML decode, and #64’s environment half). The existing Game of Life and edit-distance examples already run; they do not depend on these proposals.

The current module system loads sibling files. This plan does not add installed standard modules, generic user words, implicit conversions, or a package manager. Track discussion in issue #30.