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

CLI command parsing, lookup, help rendering, dispatch.

The command spec, builder, and global registry now live in com.blockether.vis.internal.extension.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

Terminal output stdout! print a line to the saved original stdout stderr! print a line to the saved original stderr write-stdout! print without a newline (live redraw frames) terminal-width best-effort terminal columns print-table! word-wrapped table (table-width, expand-table-cols)

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

*color-enabled?* clj

Color override: true/false force it, nil (the default) auto-detects per call via [[detect-color?]]. Tests run with System/console returning nil, so colors stay off and substring assertions on render-* output stay stable.

color-enabled? clj

(color-enabled?)

Whether ANSI styling applies to this call.

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}

expand-table-cols clj

(expand-table-cols cols target-width)

Grow table columns to target-width. Columns marked :grow? true share extra width; otherwise the final column grows. This keeps all CLI tables full-width while preserving fixed ID/count/date columns.

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.

print-table! clj

(print-table! cols rows)

Print a formatted table to stdout!. cols is [{:key :k :label "L" :width N :align :left|:right}]. Cells are word-wrapped (not truncated) so long descriptions stay visible across multiple physical lines. Tables expand to terminal width by growing :grow? columns (or the final column by default).

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-agent help). Shows the root doc, then a single COMMANDS block listing every immediate subcommand.

stderr! clj

(stderr! s)

Print a diagnostic to the process's real stderr.

stdout! clj

(stdout! s)

Print to the real terminal via the saved original stdout. Other output (telemere, SLF4J) is redirected to the log file.

table-width clj

(table-width cols)

Visible width of a rendered table with cols: outer padding + cells + separators.

terminal-width clj

(terminal-width)

Best-effort terminal width for CLI tables. zsh/bash often keep COLUMNS as a shell variable instead of exporting it, so also query the controlling terminal via stty. Falls back to 120 for non-interactive runs.

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.

write-stdout! clj

(write-stdout! s)

Write to the real terminal without appending a newline. Used by the live trace renderer for cursor-back/redraw frames.