format_help(cmd) -> help

Generate markdown-formatted help text for a command

Returns a markdown string with the following sections:

1. # <command> — name heading

2. Summary and description (when set)

3. ## Usage — generated usage line

4. ## Options — pipe table with name, default, forms, and note columns

5. ## Arguments — pipe table with name, arity, default, and note columns

6. ## Subcommands — pipe table (when present)

Inline code spans carry semantic classes for themed rendering:

• type classes: .bool, .num, .str, .file, .dir

• role classes: .opt, .arg, .flag, .meta

• state classes: .req, .def, .multi, .neg

command(name, opts) -> cmd

Create a new command parser with options, arguments, and subcommands

Returns a command object with chainable builder methods:

• cmd:summary(text) — set one-line summary

• cmd:description(text) — set longer description

• cmd:option(name, spec) — add a named option (see option spec below)

• cmd:argument(name, spec) — add a positional argument (see argument spec below)

• cmd:command(name, spec) — add a subcommand (spec is a function or table with summary/description)

• cmd:build() — finalize configuration

• cmd:parse(argv) — parse an argument list

The opts table accepts default_subcommand (string) and subcommand_required (boolean, defaults to true).

Option spec

Fields for the spec table passed to cmd:option(name, spec):

• short — one-char short alias (e.g. "v" for -v)

• long — explicit long name (default: name with _ → -)

• type or kind — "boolean", "string", "number", "file", "dir" (aliases: "bool", "str", "num")

• default — default value

• required — require option presence (default: false)

• repeatable — collect repeated values into an array (default: false)

• negatable — allow/disallow auto --no-<long> for bools (default: true)

• choices — allowed values list

• metavar — help placeholder for the value

• note or help — help text

Argument spec

Fields for the spec table passed to cmd:argument(name, spec):

• type or kind — same type system as options

• nargs — one of "1", "?", "*", "+" (default: "1")

• default — default when omitted

• required — explicit requirement (inferred from nargs when not set)

• note or help — help text

Parse return

On success, cmd:parse(argv) returns (parsed, nil) where parsed is a table keyed by option/argument names. When subcommands are used, parsed also contains subcommand (name) and args (sub-parsed table).

On failure or help, returns (nil, err) where err is a table:

• kind — "help" or "parse_error"

• code — stable error code: help, unknown_option, missing_value, invalid_value, invalid_negation, missing_option, missing_argument, invalid_argument, unknown_subcommand, missing_subcommand

• message — human-readable message

• usage — generated usage string

• suggestions — optional list of Levenshtein-based alternatives

format_error(err) -> message

Format a parse error into a human-readable string

Formats the error table returned by cmd:parse() into a displayable string. Combines usage line, error message, and suggestions (when present). For err.kind == "help", returns the markdown help directly.