Skip to main content
Version: latest

ext-cli

ext-cli is the canonical package for deterministic CLI parsing, help generation, and completion.

It consumes specrows (x07cli.specrows@0.1.0) and an argv_v1 byte encoding (see CLI apps).

See also:

Exports (module: ext.cli)​

  • Parsing
    • ext.cli.parse_specrows(spec_json, argv_v1) -> bytes
    • ext.cli.parse_specrows_v2(spec_json, argv_v1, env_v1) -> bytes (env defaults)
    • ext.cli.parse_compiled(specbin_v1, argv_v1) -> bytes
    • ext.cli.parse_compiled_v2(specbin_v1, argv_v1, env_v1) -> bytes
  • Matches (on OK docs)
    • ext.cli.matches_cmd(doc) -> bytes (scope path: "root", "pkg", "pkg.add", …)
    • ext.cli.matches_get(doc, key, kind) -> option_bytes
  • Errors (on ERR docs)
    • ext.cli.err_code(doc) -> i32
    • ext.cli.err_msg(doc) -> bytes
    • ext.cli.err_hint(doc) -> bytes
    • ext.cli.err_usage(doc) -> bytes
    • ext.cli.err_arg(doc) -> bytes (optional)
    • ext.cli.err_scope(doc) -> bytes (optional)
    • ext.cli.err_doc_v2(doc) -> bytes (ext.data_model map with stable fields)
  • Help
    • ext.cli.render_help(spec_json_or_specbin, scope) -> bytes

Specrows helpers (module: ext.cli.specrows)​

  • ext.cli.specrows.compile(spec_json) -> result_bytes
    • Returns a compiled doc that parse_compiled* and render_help accept.
    • Inserts implied --help (all scopes) and --version (root) rows if missing.
  • ext.cli.specrows.validate(spec_json) -> result_i32

matches_get kinds and encodings​

ext.cli.matches_get(doc, key, kind) queries the parse result for a specific key and kind:

  • kind=1: flags (presence)
  • kind=2: option/arg values (typed encoding)

Typed encodings for kind=2:

  • STR / PATH / BYTES / ENUM: raw token bytes
  • U32: 4-byte little-endian
  • I32: 4-byte little-endian two’s complement
  • BOOL: 1 byte (0 or 1)
  • BYTES_HEX: decoded bytes

Repeated options (meta.multiple=true) use a multi encoding stored under kind=2:

  • u32_le(count)
  • then count items of u32_le(len) + len bytes of the per-item typed encoding

Canonical error map (err_doc_v2)​

ext.cli.err_doc_v2(doc) returns an ext.data_model document representing:

  • { code, message, hint, usage, arg?, scope? }

This is intended for stable machine handling (JSON rendering, structured logs, etc) without needing to parse human-formatted text.