output

package
v0.27.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

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

View Source
const (
	FormatTable = "table"
	FormatJSON  = "json"
	FormatYAML  = "yaml"
)

Format names. Kept as strings so the cobra flag can use them directly.

View Source
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.

View Source
const FormatText = "text"

FormatText is tab-separated values without headers, one record per line, for cut, awk and shell loops.

Variables

View Source
var ErrNoID = errors.New("this result has no id: use -o json or -o text")

ErrNoID says the result has no id to print.

View Source
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

func CompileQuery(expr string) error

CompileQuery checks a JMESPath expression, so a typo fails before any request is made.

func IsInteractive

func IsInteractive(w io.Writer) bool

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

func Print(w io.Writer, format string, value any) error

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

func PrintPaged(w io.Writer, format string, disabled bool, value any) error

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

func When(t time.Time) string

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

func WhenSeconds(t time.Time) string

WhenSeconds is When to the second.

func WhenString added in v0.16.0

func WhenString(s string) string

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

func WhenStringSeconds(s string) string

WhenStringSeconds is WhenString to the second.

Types

type Done added in v0.16.0

type Done struct {
	Message string
	Value   any
	Fields  []Field
}

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 Field added in v0.16.0

type Field struct {
	Name  string
	Value string
}

Field is one line of an Object's table view.

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.

func Query added in v0.16.0

func Query(value any, expr string) (Generic, error)

Query applies a JMESPath expression to what -o json would print for value and returns the result, ready for any format.

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.

type View added in v0.22.0

type View[T any] struct {
	Value any
	Table Table[T]
}

View is a document whose JSON and YAML shape (Value, which --query also sees) is richer than what a person wants to read: the table shows Table and text prints Table's rows, while json and yaml encode Value whole.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL