Documentation
¶
Overview ¶
Package textout holds the command-agnostic human-output toolkit: the table, key/value and number-formatting primitives the cli's human-readable mode is built from, plus the TextFormatter seam a command's result type implements to render itself.
It lives apart from internal/cli so a command subpackage can build its own human output without importing cli (which it cannot), and apart from internal/output, which owns the generic JSON/text/error wire contract and stays free of presentation logic. Money/quantity values arrive as decimal STRINGS and are for DISPLAY ONLY — Num groups thousands on a display copy; the wire path never sees this package.
Index ¶
- func AsArray(raw json.RawMessage) ([]json.RawMessage, bool)
- func AsObject(raw json.RawMessage) (map[string]json.RawMessage, bool)
- func IndentLines(s, prefix string) string
- func Jstr(m map[string]json.RawMessage, key string) string
- func KVBlock(rows [][2]string) string
- func ListView(raw json.RawMessage) (rows json.RawMessage, note string, ok bool)
- func Num(s string) string
- func OneLine(s string, max int) string
- func OrNone(s string) string
- func OrderedKV(raw json.RawMessage) ([][2]string, bool)
- func PadLeftRune(s string, width int) string
- func PadRune(s string, width int) string
- func RawJSON(value any) json.RawMessage
- func Table(headers []string, rows [][]string, align []bool) string
- func WithTruncationNote(text, note string) string
- func YesNo(b bool) string
- type TextFormatter
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AsArray ¶
func AsArray(raw json.RawMessage) ([]json.RawMessage, bool)
AsArray decodes raw into a slice of element messages. ok=false if not an array.
func AsObject ¶
func AsObject(raw json.RawMessage) (map[string]json.RawMessage, bool)
AsObject decodes raw into an order-agnostic field map (formatters read fields by name). ok=false if raw isn't a JSON object.
func IndentLines ¶
IndentLines prefixes every line of s with prefix.
func Jstr ¶
func Jstr(m map[string]json.RawMessage, key string) string
Jstr returns the string at key from m, or "" if absent/non-string. Numbers are rendered via json.Number so a numeric field (e.g. a timestamp) still prints.
func ListView ¶
func ListView(raw json.RawMessage) (rows json.RawMessage, note string, ok bool)
ListView unwraps a possibly-truncated list payload for a formatter: the bare array for a complete result, or the {"data":[...],"truncated":true,"note":...} envelope (see wrapTruncated in cli/endpoint.go) for an incomplete one. It returns the row array plus the optional truncation note so the formatter can append it to the human table. ok=false only when an object payload isn't that envelope.
func Num ¶
Num formats a decimal-string value with thousand separators for readability. The value arrives as a decimal STRING and is for DISPLAY ONLY — the wire path never sees this copy. If the string isn't a clean integer-ish/decimal number, it is returned verbatim (never guess).
func OneLine ¶
OneLine collapses whitespace runs in s to single spaces and truncates to max runes (with an ellipsis) — for previewing a user-supplied script/predicate in a plan without letting a multi-line value wreck the layout.
func OrNone ¶
OrNone returns s, or "(none)" when s is empty — for fields where absence is meaningful to show rather than hide.
func OrderedKV ¶
func OrderedKV(raw json.RawMessage) ([][2]string, bool)
OrderedKV reads a JSON object preserving its field order, with each value as a display string (a JSON string unquoted; anything else verbatim). ok=false if raw isn't a JSON object. Used where insertion order is meaningful (the dry-run request params are sent in this order).
func PadLeftRune ¶
PadLeftRune right-justifies s into a rune-measured field width (for numeric columns).
func PadRune ¶
PadRune left-justifies s into a field width measured in runes (not bytes), so non-ASCII values still align.
func RawJSON ¶
func RawJSON(value any) json.RawMessage
RawJSON renders value to compact JSON bytes for a keyed formatter to read: a json.RawMessage passes through verbatim; anything else is marshalled with HTML escaping off (matching the output package). Returns nil on a marshal error.
func Table ¶
Table renders rows under headers with each column sized to its widest cell. Numeric columns are right-aligned; the rest left-aligned. align[i]==true means right-align column i.
func WithTruncationNote ¶
WithTruncationNote appends the truncation note (when present) to a rendered human table, so a stdout-only reader sees the result is incomplete.
Types ¶
type TextFormatter ¶
type TextFormatter interface {
// FormatText writes the result as human-readable text to w, without a
// trailing newline (the output sink adds one). Build the text with the
// helpers in this package.
FormatText(w io.Writer)
}
TextFormatter is implemented by a local/command-package command's result type to render itself as human-readable output. The command returns its typed result; the emitter marshals it verbatim in --json mode and, in human mode, calls FormatText so the command writes its own text from typed fields — no command-key lookup and no JSON round-trip. The catalog-driven endpoint commands do NOT use this: they emit verbatim API bytes whose shape varies per endpoint and render through the cli's keyed per-command formatter table.
Source Files