com.blockether.vis.internal.commandline — com.blockether/vis 0.1.2

CLI command parsing, lookup, help rendering, dispatch.

The command spec, builder, and global registry now live in com.blockether.vis.internal.registry alongside the channel and provider registries. This namespace provides the operations OVER those command maps:

Lookup find-leaf walk the tree consuming tokens until a match find-named same, but ignoring the root command's name

Argument parsing parse-args parse residual tokens against :cmd/args validate-args nil on success, error string on missing required

Help rendering render-command detailed help for one command render-tree top-level overview shown on vis with no args color-enabled? dynamic toggle (TTY auto-detect) pad-right width-padding helper pad-left width-padding helper

Dispatch dispatch! resolve, parse, validate, invoke :cmd/run-fn

The registry surface (command, register-cmd!, deregister-cmd!, registered-commands, registered-under, resolve-subcommands) is reachable through com.blockether.vis.internal.registry.

*color-enabled?* clj

Color output toggle. Auto-detects: TTY attached + no NO_COLOR env

• TERM not dumb. Override with binding. Tests run with System/console returning nil, so colors are off by default and substring assertions on render-* output stay stable.

dispatch! clj

(dispatch! root args)

(dispatch! root args {:keys [print-fn]})

Resolve the command for args against root, parse the residual tokens against the resolved command's :cmd/args spec, and call its :cmd/run-fn with [parsed-args residual].

When the command lacks :cmd/run-fn and has subcommands, prints help for that level via render-command. When --help/-h is in the residual, also prints help.

Returns: {:status :ok :command cmd :result <whatever run-fn returned>} {:status :help :command cmd :help-text <string>} {:status :no-match :args args}

find-leaf clj

(find-leaf root args)

Walk the tree from root consuming tokens until either:

• a child matches and has no further subcommands
• or no child matches the next token

Returns {:command resolved-cmd :path [name...] :residual [token...]}, or nil when even the root's name doesn't match args[0]. The residual is everything LEFT after the resolved command name.

find-named clj

(find-named root args)

Like find-leaf, but matches against the bare arg vector ignoring the root command's name (the way cli/-main typically gets called). Useful when the root is implicit and you just want the resolved subcommand for the given args.

pad-left clj

(pad-left s w)

pad-right clj

(pad-right s w)

parse-args clj

(parse-args arg-specs raw-args)

Parse raw-args against arg-specs. Returns a map of {arg-name value}. Positional specs are matched in order; flag specs by --name; boolean flags need no value. Unknown flags are silently dropped so commands can layer their own loose flags.

render-command clj

(render-command cmd path)

Render multi-section help for a single command: USAGE / DESCRIPTION / SUBCOMMANDS / ARGUMENTS / FLAGS / EXAMPLES.

Empty sections are omitted. path is the command-name chain leading up to and including this command - used for the USAGE line when :cmd/usage isn't set.

render-tree clj

(render-tree root)

Top-level overview rendered when the binary is invoked with no arguments (or via vis help). Shows the root doc, then a single COMMANDS block listing every immediate subcommand.

unknown-flags clj

(unknown-flags arg-specs raw-args)

Return a vector of --flag tokens in raw-args that are NOT declared in arg-specs. Walks the args the same way parse-args does so that a string-typed flag's VALUE (e.g. bar in --out bar) is never misclassified as an unknown flag. Boolean flags don't consume their next token. Universal --help / -h are always considered known.

Used by dispatch! to refuse unknown flags and surface the list of accepted flags via render-command. Pure; no side effects.

Unknown flags are reported only by their leading token; we don't know whether the user intended them to take a value, so the walker conservatively advances by one token after each unknown.

validate-args clj

(validate-args arg-specs parsed)

Validate parsed args against spec. Returns nil on success, or an error string describing the missing required arguments.