output

Documentation

Overview

Package output renders command results either as a styled table/summary for humans or as indented JSON for machines (--json).

Index

• Variables
• func Emit(w io.Writer, asYAML bool, v any) error
• func Errorf(w io.Writer, format string, a ...any)
• func Hintf(w io.Writer, format string, a ...any)
• func HumanBlankLine(w io.Writer) error
• func Infof(w io.Writer, format string, a ...any)
• func JSON(w io.Writer, v any) error
• func KeyValues(w io.Writer, pairs [][2]string) error
• func PlainField(s string) string
• func Progressf(w io.Writer, format string, a ...any)
• func SanitizeField(s string) string
• func Successf(w io.Writer, format string, a ...any)
• func Table(w io.Writer, headers []string, rows [][]string) error
• func Title(w io.Writer, s string)
• func YAML(w io.Writer, v any) error

Variables

var (
	// Quiet suppresses incidental success/info lines (-q/--quiet).
	Quiet bool
	// Plain renders tables as tab-separated, unstyled rows (--plain).
	Plain bool
	// Interactive is true when stdout is a terminal. When false (piped or
	// redirected), Table drops its box-drawing frame so the rows stay
	// grep/awk-friendly, mirroring how color is stripped for non-TTY output.
	Interactive bool
)

Output mode toggles set from global flags before commands run.

Functions

func Emit

func Emit(w io.Writer, asYAML bool, v any) error

Emit writes v as YAML when asYAML is set, otherwise as JSON. Commands that support --json also support the parallel --output yaml (or -o yaml) via this helper, so the two structured formats never need separate branches.

func Errorf

func Errorf(w io.Writer, format string, a ...any)

Errorf prints an error line with a red dot. Unlike Successf/Infof it is never suppressed by Quiet — errors must always reach the user.

func Hintf

func Hintf(w io.Writer, format string, a ...any)

Hintf writes a faint, indented follow-up line (e.g. a "try this next" hint after an error). Rendered on stderr by callers; not suppressed by --quiet so remediation guidance always shows.

func HumanBlankLine

func HumanBlankLine(w io.Writer) error

HumanBlankLine preserves a visual separator in human output without introducing an empty record in --plain output.

func Infof

func Infof(w io.Writer, format string, a ...any)

Infof prints a muted informational line with a primary-colored dot (suppressed in Quiet/Plain).

func JSON

func JSON(w io.Writer, v any) error

JSON writes v as indented JSON to w. A typed nil slice (e.g. `var x []T` with zero rows) marshals to `null`, which breaks scripts doing `… --json | jq '.[]'` or length checks on empty result sets, so it is coerced to an empty slice and serialized as [].

func KeyValues

func KeyValues(w io.Writer, pairs [][2]string) error

KeyValues renders an aligned key/value block (used for "get" style output).

func PlainField

func PlainField(s string) string

PlainField makes one value safe to embed in a tab-separated, newline-delimited plain-output record without changing structured JSON or YAML data.

func Progressf

func Progressf(w io.Writer, format string, a ...any)

Progressf prints transient progress only for an interactive human session, keeping redirected and machine-readable command output quiet.

func SanitizeField

func SanitizeField(s string) string

SanitizeField removes terminal control characters from untrusted values before they are embedded in human-readable output. Structured output must keep the original data, so callers apply this only at terminal render sites.

func Successf

func Successf(w io.Writer, format string, a ...any)

Successf prints a success line with a green dot (suppressed in Quiet/Plain).

func Table

func Table(w io.Writer, headers []string, rows [][]string) error

Table renders a simple, aligned table with a styled header. Columns are sized to their widest cell. It is intentionally dependency-light so it can be used from any command. In Plain mode it emits tab-separated, unstyled rows for grep/awk pipelines.

func Title

func Title(w io.Writer, s string)

Title prints a bold violet title line.

func YAML

func YAML(w io.Writer, v any) error

YAML writes v as YAML to w. v is round-tripped through JSON first so field names and shapes match --json exactly (Go struct field names, json tags, and the same nil-slice-to-[] coercion as JSON), rather than diverging to yaml.v3's own default field-naming rules.