Skip to content

index.md

Latest commit

 

History

History
191 lines (155 loc) · 13.3 KB

index.md

File metadata and controls

191 lines (155 loc) · 13.3 KB
created 2026-05-05
last_modified 2026-05-10
revisions 6
doc_type
REFERENCE

m-stdlib modules

Regenerated at the v0.4.0 release (2026-05-08). One row per shipped module. The canonical "what's done / in flight / proposed" view lives in docs/module-tracker.md; this file is the released-module catalogue.

Machine-readable surface

Beyond the human-readable tables below, the released stdlib also ships a structured surface that downstream tools (m-cli m doc, the planned VS Code extension, the planned AI skill) read at runtime. Source: docs/plans/discoverability-and-tooling-plan.md.

Artefact Path Purpose
Manifest dist/stdlib-manifest.json Canonical index of every public module + label — signatures, source file:line, synopsis, description, and tag-derived fields (@param / @returns / @raises / @example / @since / @stable / @see). Generated from src/STD*.m by tools/gen-manifest.py.
Errors registry dist/errors.json Inverted index U-STD* → {module, labels[]}. Populated from @raises tags; empty until the WA2 backfill lands (per discoverability tracker).
Doc-comment grammar docs/guides/m-doc-grammar.md Normative spec for the structured ; doc: tags the manifest is generated from. Read this before editing any ; doc: block in src/STD*.m.
Per-module YAML frontmatter this folder's std*.md files Each per-module markdown carries machine-readable metadata as YAML frontmatter (module / tag / phase / stable / since / synopsis / labels / errors / conformance / see_also). Generated by tools/write-module-frontmatter.py.

Regenerating. make manifest (writes dist/), make frontmatter (re-syncs frontmatter on every per-module markdown), make manifest-check (CI gate — fails on drift between src//docs/ and the committed dist/).

Phase 1 (v0.1.0)

Module Tag Purpose Per-module doc
STDASSERT v0.0.1 Assertion library — 9 extrinsics + silent toggle, ^TESTRUN-compatible output protocol so m test accepts STDASSERT-driven suites unchanged. stdassert.md
STDUUID v0.0.1 RFC-4122 v4 + RFC-9562 v7 UUIDs. v7 timestamp-prefix sorts in generation order. stduuid.md
STDB64 v0.0.2 RFC-4648 Base64 — standard + URL-safe alphabets, RFC §10 vectors as conformance corpus. stdb64.md
STDHEX v0.0.2 RFC-4648 §8 hex — lowercase default, uppercase variant, case-insensitive decode. stdhex.md
STDFMT v0.0.3 Printf-style formatter — subset of Python str.format: fill / align / width / precision / type (s d f x X o b), {{/}} escapes. stdfmt.md
STDLOG v0.0.4 Structured key=value logger — five levels, four sinks, $$now^STDDATE() timestamp. stdlog.md
STDDATE v0.0.5 ISO-8601 datetime + duration arithmetic — now / fromh / toh / strftime / strptime / add / diff over proleptic Gregorian. stddate.md
STDCSV v0.0.6 RFC-4180 CSV parser/writer — every §2 clause, optional file I/O, RFC §2 conformance corpus. stdcsv.md
STDARGS v0.0.7 argparse — long/short/grouped flags, positionals, sub-commands, -- terminator, four actions (store_true / store / count / append). stdargs.md

Phase 1 totals: 9 modules; 527/527 assertions green; per-module coverage ≥ 95% (most at 100%); 0 lint errors.

Phase 1b (v0.1.1 – v0.1.3)

Module Tag Purpose Per-module doc
STDFIX v0.1.1 Fixture lifecycle — with / invoke one-shot transactional scopes; powers per-test tstart / trollback isolation. stdfix.md
STDMOCK v0.1.2 Test-time call interception — register / invoke / $$resolve / $$called / $$args. stdmock.md
STDSEED v0.1.3 Declarative TSV manifest loader for FileMan record fixtures + pluggable filer hook (fileViaDie default). stdseed.md

Phase 2 (v0.2.0)

Module Tag Purpose Per-module doc
STDJSON v0.2.0 RFC 8259 JSON parser + serialiser — one M-tree node per JSON value (o / a / s: / n: / t / f / z). stdjson.md
STDREGEX v0.2.0 Thompson-NFA regex on YDB — full v0.2.0 subset (literals, classes, groups, alternation, greedy quantifiers, capture, replace, split). 102/102 assertions; 100% per-module label coverage. stdregex.md
STDCOLL v0.2.0 Collections — Set / Map / Stack / Queue / Deque / Heap / OrderedDict over caller-owned arrays. stdcoll.md
STDURL v0.2.0 RFC 3986 URI parse / build / encode / decode / valid / normalize / resolve. stdurl.md

v0.2.0 add-ons (no new modules):

  • STDLOG FORMAT(kv|json) — JSON-line output via $$encode^STDJSON (consumes L11). kv remains the default.
  • STDSEED loadJson — JSON-array manifest loader via $$parse^STDJSON. Replaces the v0.1.3 U-STDSEED-NOT-IMPLEMENTED stub.

Phase 2 totals: 4 new modules + 2 add-ons; ~600 new assertions across STDJSON, STDREGEX, STDCOLL, STDURL; per-module label coverage ≥ 95% (most at 100%); 0 lint errors.

P4 wave (v0.3.0)

Eleven pure-M promotions out of the proposal pipeline (was the old "Table 2" in docs/tracking/module-tracker.md; now lives in docs/plans/future-modules-plan.md), plus the toolchain hardening that unblocked them. All shipped under the v0.3.0 release tag (commit 363b990, 2026-05-07).

Module Tag Purpose Per-module doc
STDCSPRNG v0.3.0 Crypto random — bytes / hex / base64 / token / int / uuid4 over kernel CSPRNG (/dev/urandom; v0.4.0 adds optional $ZF → getrandom(2) callout). stdcsprng.md
STDFS v0.3.0 File-system primitives — read/write/append/exists/remove/size + basename/dirname/join (text I/O via YDB SEQ stream mode; v0.4.0 adds byte-faithful I/O via libc callout). stdfs.md
STDOS v0.3.0 Process / env / cmdline helpers — env / pid / cmdline / argc / arg / argv / splitArgs / cwd / user / hostname / exit. YDB-only v1. stdos.md
STDSEMVER v0.3.0 SemVer 2.0.0 — valid / parse / compare / matches plus major/minor/patch/prerelease/build accessors; range syntax (> / < / >= / <= / = / ^ / ~). stdsemver.md
STDSTR v0.3.0 String helpers — pad / trim / replaceAll / split / startsWith / endsWith / toLowerASCII / toUpperASCII / repeat. ASCII-only by design. stdstr.md
STDTOML v0.3.0 TOML 1.0 subset — top-level pairs + [section] tables; string / integer / float / bool scalars; # comments. stdtoml.md
STDCACHE v0.3.0 LRU + TTL cache over caller-owned array — new / put / get / has / remove / clear / size / capacity. stdcache.md
STDPROF v0.3.0 Wall-clock profiler — start / stop / count / total / mean / min / max / percentile / tags / clear. $ZHOROLOG-microsecond-resolution. stdprof.md
STDSNAP v0.3.0 Snapshot testing — serialize / save / matches / asserts; canonical line-per-leaf dump via $QUERY walk. stdsnap.md
STDENV v0.3.0 .env loader + typed accessors — parse / parseFile / valid / has / get / getInt / getBool / getFloat. stdenv.md
STDXML v0.3.0 XML 1.0 parser + XPath 1.0 subset (paths / [N] predicates / descendant axis // / element-level + attribute-level namespaces / comments / PI / xml-decl / CDATA / numeric char refs). v0.4.0 extends with wildcards + attribute axis + functions + DOCTYPE/<!ENTITY>. stdxml.md

P4-wave m-cli companion tracks (v0.3.0):

  • m test --timings — subprocess-level wall-clock per suite via Python time.perf_counter(); STDPROF is the in-process API for finer-grained intra-suite timing.
  • m test --update-snapshots — sets ^STDLIB($JOB,"stdsnap","update")=1 so asserts^STDSNAP rewrites baselines instead of comparing.
  • m test --env PATH — repeatable; loads each .env via parseFile^STDENV and merges into ^STDLIB($JOB,"env",KEY).

P4-wave totals: 11 new modules; ~700 new assertions; per-module label coverage ≥ 91% (most at 100%; STDOS at 91.7%, STDENV at 93.3%); 0 lint errors.

Phase 3 + post-P4 wave (v0.4.0)

The three Phase 3 $ZF-bound modules (STDCRYPTO H1, STDCOMPRESS H2, STDHTTP H3) all green on engine, plus two more pure-M promotions out of the proposal pipeline (STDMATH L26, STDXFRM L27) and significant feature work on STDXML and STDFS.

Module Tag Purpose Per-module doc
STDMATH v0.4.0 Numeric helpers — clamp / min / max / sum / count / mean over caller-owned arrays. stdmath.md
STDXFRM v0.4.0 Higher-order array transforms — map / filter / reduce via XECUTE-evaluated lambdas (value / key / acc locals). stdxfrm.md
STDCRYPTO v0.4.0 SHA-256/384/512 + HMAC-SHA-256/384/512 via $&stdcrypto.fn → libcrypto (OpenSSL EVP_Digest + HMAC). stdcrypto.md
STDCOMPRESS v0.4.0 gzip / gunzip / deflate / inflate / zstdCompress / zstdDecompress via $&stdcompress.fn → libz + libzstd. stdcompress.md
STDHTTP v0.4.0 HTTP/1.1 client — pure-M wire-format helpers (parseStatusLine / parseHeader / parseResponse / buildRequest / formatHeaders) + libcurl-backed $$get / $$post / $$request / $$available. stdhttp.md

v0.4.0 add-ons (extending v0.3.0 modules):

  • STDXML T26 + T27a + T27b — DOCTYPE + internal subset + <!ENTITY> custom entities (T26); XPath wildcards (*, @*) + attribute axis @attrName (T27a); XPath comparison predicates
    • functions position() / last() / name() / text() / count() / string-length() / normalize-space() / contains() / starts-with() / not() / string() / number() (T27b). Closes the 12-16d envelope; STDXMLTST 209/209.
  • STDFS byte-faithful I/O — readBytes / writeBytes / appendBytes / available via $ZF → libc open/read/write/close (T13 + T14). Atomic O_APPEND; no CR/LF normalisation.
  • STDCSPRNG $ZF → getrandom(2) callout backend — optional perf-only swap (T12); pure-M /dev/urandom fallback unchanged.

v0.4.0 deployment harness:

  • scripts/seed-callouts.sh — builds Phase 3 .c sources inside the vista-meta container against the runtime YDB headers, stages .so + .xc artefacts under ~/export/seed/m-stdlib/{lib/<plat>,xc}/, and idempotently injects a marker block into /etc/profile.d/ydb_env.sh exporting STDLIB_LIB + per-package ydb_xc_<pkg>. make seed invokes it automatically when src/callouts/*.c is present.

v0.4.0 totals: 5 new modules (STDMATH, STDXFRM, STDCRYPTO, STDCOMPRESS, STDHTTP); 3 module add-ons (STDXML T26+T27a+T27b, STDFS byte-I/O, STDCSPRNG callout). Aggregate engine gate: 32 suites, 2483/2483 assertions green; 0E lint; fmt clean.

Conformance corpora

Path Vectors Used by
tests/conformance/b64/ RFC-4648 §10 (standard + URL-safe) STDB64
tests/conformance/csv/ RFC-4180 §2 + excel-quirks + LF-only + UTF-8 BOM STDCSV
tests/conformance/json/ Curated subset of JSONTestSuite (23 y_, 15 n_, 8 i_ files) mapped to RFC 8259 clauses STDJSON
tests/conformance/url/ RFC 3986 §5.4 normal + abnormal reference-resolution vectors STDURL
tests/conformance/uuid/ RFC-4122 / RFC-9562 vectors (every version 1–8, all four variants, 8 malformed-input rejections) STDUUID

Cross-module dependencies (runtime)

Per parallel-tracks.md §2:

  • STDLOG → STDDATE — $$now^STDDATE() for line-leading timestamp.
  • STDLOG FORMAT="json" → STDJSON — $$encode^STDJSON for JSON-line emission (v0.2.0 add-on).
  • STDSEED loadJson → STDJSON — $$parse^STDJSON for JSON manifest parsing (v0.2.0 add-on).
  • STDCSPRNG → STDB64 / STDHEX / STDUUID — $$urlencode^STDB64, $$encode^STDHEX, $$valid^STDUUID (test-only) consumed by bytes / hex / base64 / token / uuid4 extrinsics.
  • STDSNAP → STDFS / STDASSERT — file I/O via STDFS; assertion integration via asserts^STDSNAP.
  • STDENV → STDFS — parseFile^STDENV reads via STDFS.
  • STDHTTP → STDURL — parse^STDURL extracts host/path/port for request-line and Host-header construction in $$buildRequest.

All other modules are runtime-independent.