output

package
v0.21.1 Latest Latest
Warning

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

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

Documentation

Overview

Package output renders command results in one of four user-selected formats: a human-friendly table, JSON, YAML, or tab-separated text.

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 FormatText = "text"

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

Variables

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
}

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.

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.

Jump to

Keyboard shortcuts

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