Documentation
¶
Overview ¶
Package output renders command results in one of the user-selected formats: a human-friendly table, JSON, YAML, tab-separated text, or just the result's id.
Every service command should hand its result to Print so the global --output flag works uniformly. Table rendering is opt-in per command: callers describe the columns they want via Table; for JSON/YAML the value is encoded as-is.
Index ¶
- Constants
- Variables
- func CompileQuery(expr string) error
- func IsInteractive(w io.Writer) bool
- func Print(w io.Writer, format string, value any) error
- func PrintPaged(w io.Writer, format string, disabled bool, value any) error
- func When(t time.Time) string
- func WhenSeconds(t time.Time) string
- func WhenString(s string) string
- func WhenStringSeconds(s string) string
- type Done
- type Field
- type Generic
- type Object
- type QueryError
- type Style
- type Table
- type View
Constants ¶
const ( FormatTable = "table" FormatJSON = "json" FormatYAML = "yaml" )
Format names. Kept as strings so the cobra flag can use them directly.
const FormatID = "id"
FormatID prints only the result's id, one per line for a list, so a script can capture what it just created: id=$(... -o id). A result with nothing in it prints nothing.
const FormatText = "text"
FormatText is tab-separated values without headers, one record per line, for cut, awk and shell loops.
Variables ¶
var ErrNoID = errors.New("this result has no id: use -o json or -o text")
ErrNoID says the result has no id to print.
var NoStyle = Style{StatusColumn: -1}
NoStyle is the zero value Style — no status column. Spelled out for readability at call sites.
Functions ¶
func CompileQuery ¶ added in v0.16.0
CompileQuery checks a JMESPath expression, so a typo fails before any request is made.
func IsInteractive ¶
IsInteractive reports whether w is a real terminal. Exported so command packages can decide whether to emit chatty stderr hints. Non-*os.File writers (test buffers, captured stderr) are treated as non-interactive.
func Print ¶
Print writes value to w in the requested format. For table format, value must be a Table[T]; for JSON/YAML, Table[T] is automatically unwrapped to its Items slice (the Rows function isn't marshallable).
func PrintPaged ¶
PrintPaged behaves like Print, but pipes the output through a pager program when (a) the format is table, (b) w is an interactive terminal, and (c) the user hasn't disabled paging via the flag.
The pager is taken from $NORCUBE_PAGER, then $PAGER, then "less". We set LESS=FRX so less:
- F: prints content inline and exits if it fits in one screen
- R: passes our ANSI color escapes through unmolested
- X: doesn't clear the screen on exit (output stays scrolled-back)
When the pager program can't be started (e.g. less isn't installed) we fall back to direct Print rather than failing the command.
func When ¶ added in v0.16.0
When is a table cell for t, to the minute ("2026-10-28 18:55" in local time). A zero time is the "no value" placeholder.
func WhenSeconds ¶ added in v0.16.0
WhenSeconds is When to the second.
func WhenString ¶ added in v0.16.0
WhenString is When for an RFC 3339 string from an API. An empty string is the placeholder; a value that doesn't parse is shown as it is.
func WhenStringSeconds ¶ added in v0.16.0
WhenStringSeconds is WhenString to the second.
Types ¶
type Done ¶ added in v0.16.0
Done is the result of an action. A table shows Message, the sentence a person expects ("Deleted namespace "web"."); JSON and YAML encode Value, the affected resource; text prints Fields on one line, or Value in its generic text form when there are no Fields.
type Generic ¶ added in v0.16.0
type Generic struct{ V any }
Generic is a value of JSON shape (what --query returns): maps, slices, strings, float64s, bools and nil. Tables and text are derived from its shape since no column layout exists for it.
type Object ¶ added in v0.16.0
type Object struct {
Value any
Fields []Field
// Text, when set, is the record -o text prints instead of the field
// values: for objects whose fields depend on the resource (a monitor's
// settings by type), so the text columns stay fixed.
Text []string
}
Object is a single resource. JSON and YAML encode Value; a table shows Fields as aligned name/value lines; text prints the field values on one tab-separated line, in Fields order, or Text when it is set.
type QueryError ¶ added in v0.16.0
type QueryError struct{ Err error }
QueryError is an invalid --query expression.
func (*QueryError) Error ¶ added in v0.16.0
func (e *QueryError) Error() string
func (*QueryError) Unwrap ¶ added in v0.16.0
func (e *QueryError) Unwrap() error
type Style ¶
type Style struct {
// StatusColumn is the 0-based column index whose values should be
// recognised as success/failed/running etc. and colored. Negative
// means no column is treated as status.
StatusColumn int
}
Style controls how a Table is rendered. Header bold, status colors, and dim placeholders are all conditional on isInteractive(w) and the NO_COLOR environment variable — pipes and CI logs get plain text.
type Table ¶
type Table[T any] struct { Headers []string Rows func(T) []string Items []T MaxWidths []int // MinWidths pads columns to at least these widths (parallel to // Headers). Tables printed one row at a time (a live stream) set it so // their columns line up. MinWidths []int Style Style }
Table describes how to render a slice of items as a table.
output.Print(w, format, output.Table[Foo]{
Headers: []string{"NAME", "ID"},
Rows: func(f Foo) []string { return []string{f.Name, f.ID} },
Items: foos,
MaxWidths: []int{40, 0}, // cap NAME at 40 runes; leave ID full
Style: output.Style{StatusColumn: 1},
})
MaxWidths is parallel to Headers. A zero (or out-of-range) entry means the column is uncapped. Cells longer than the cap are truncated to (max-1) runes and a "…" is appended.
Style controls header-bold, status-color, and dim-placeholder rendering. All styling is no-op'd when output isn't an interactive terminal or when NO_COLOR is set.