Documentation
¶
Overview ¶
Package listfmt — small renderer used by every `clawtool * list` subcommand (bridges, agents, sources, recipes, sandboxes, portals, hooks, …). Repowire pattern: each list command accepts `--format json|tsv|table` (default: table) and the renderer outputs in the requested shape so shell pipes get machine-readable rows without needing `awk` to peel a human-formatted table.
Usage:
listfmt.Render(stdout, "table", listfmt.Cols{
Header: []string{"FAMILY", "STATUS", "DESCRIPTION"},
Rows: [][]string{{"codex", "ready", "..."}, ...},
})
`format` is parsed once by the caller — either via listfmt.Parse(argv) which strips `--format X` from a flag slice, or by the caller's own arg parser. listfmt itself is pure rendering.
Index ¶
Constants ¶
const DefaultFormat = FormatTable
DefaultFormat is what every list command falls back to when no `--format` flag is given. Table is the right default for interactive shell use; pipes / scripts can opt into tsv or json.
Variables ¶
This section is empty.
Functions ¶
func IsKnown ¶
IsKnown reports whether s parses to a Format other than the fallback. Useful when the caller wants to reject `--format xml` with a usage error rather than silently degrading.
func Render ¶
Render writes cols to w in the requested format. Unknown format falls back to the table renderer with a stderr-quality warning — a typo in --format should still produce useful output, not a silent empty pipe.
func RenderOrHint ¶ added in v0.22.40
RenderOrHint codifies the empty-state contract every `clawtool * list` command discovered during the 18aed7e..012abc0 series: when there are no rows to render, table mode emits a human-readable hint (the operator running the command interactively gets an actionable next-step) while JSON / TSV consumers route through Render so pipelines see the structured empty shape (`[]\n` and a header line respectively). Pre-helper, every list command hand-rolled the same `if format == FormatTable { print hint; return } else { Render(empty rows) }` branch; the helper bakes the contract into one place so future list commands inherit it for free.
The hint may contain embedded newlines for multi-line pointers (`skill list` ships a two-line "no skills" + "try `skill new <name>`" pair). A trailing newline is appended automatically — callers should NOT include one themselves.
When cols.Rows is non-empty the hint is ignored and the function delegates to Render unconditionally — same shape as `Render` itself, callable on any list state without a pre-emptive `len(cols.Rows) == 0` guard at the call site.
Types ¶
type Cols ¶
Cols is a small column-row container the renderer takes. Header names should be UPPERCASE for table mode (matches existing clawtool list output convention) and stay UPPERCASE for tsv too — JSON mode lower-cases them to produce idiomatic keys.
type Format ¶
type Format string
Format enumerates the supported output shapes.
func ExtractFlag ¶
ExtractFlag pulls `--format <value>` (or `--format=<value>`) out of argv and returns (format, residual argv, error). Empty argv → (DefaultFormat, argv, nil). Unknown value is preserved verbatim — the caller decides whether to error or degrade.
Repeated `--format` is allowed; the last one wins (matches most CLI conventions where late flags override early ones).
func ParseFormat ¶
ParseFormat normalises a string into a known Format. Empty, unknown values, and the defaults all collapse to FormatTable. Callers that want to reject unknowns can compare against IsKnown() first.
Source Files