result

type DelimitedFormatter ¶

type DelimitedFormatter struct {

	// Separator is the field delimiter. The zero value is a comma.
	Separator rune

	// SuppressHeadings omits the header row. A spreadsheet wants it; a shell pipeline does not, since awk
	// and cut would each have to skip it.
	SuppressHeadings bool

	// Raw disables RFC 4180 quoting. Set for a renderer whose job is to print what it was given.
	Raw bool
}

DelimitedFormatter renders values as delimiter-separated lines.

One formatter, three attributes, two presets. gcloud reached the same shape: its `csv` and `value` are one renderer differing in separator, heading, and quoting, with `value` documented as "CSV with no heading and <TAB> separator instead of <COMMA>".

• NewCSVFormatter -- comma, heading, quoted. RFC 4180, for a spreadsheet.
• NewValueFormatter -- tab, no heading, raw. For text `--jq` already built.

Quoting is what separates them, and it is what the two names promise. A machine-parseable format must quote a field containing its own delimiter or the row loses a boundary; a raw renderer must not, or the text a caller composed comes back wearing quotes it did not write.

Shape drives column inference:

• If value implements HasHeaders, its Headers() result is the column order.
• Otherwise, if value is a slice/array of structs, the struct fields (in declaration order, with `csv:"name"` overrides and `csv:"-"` skips) are the columns.
• Otherwise, if value is a slice/array of maps, the union of map keys (sorted alphabetically) is the columns.
• Otherwise the elements are scalars: one column, no header, since a scalar has no field to name.

A value that is not a slice or array at all is one row. That is the shape `--jq '.count'` produces, and erroring on it would make the filter stage incomplete.

Cell values render via fmt.Sprint, which honors fmt.Stringer and produces reasonable defaults for numbers, bools, time.Time, and nil. Empty input renders no bytes.

func NewCSVFormatter() DelimitedFormatter

func NewValueFormatter() DelimitedFormatter

func (f DelimitedFormatter) Format(value any, w io.Writer) error

type FieldFilter ¶

type FieldFilter struct {
	// contains filtered or unexported fields
}

FieldFilter narrows a slice of structs/maps to those whose named field matches a target value. The expression form is `field=value`, mirroring `gh`'s `--filter` flag and `kubectl`'s field selectors. Multiple expressions AND together — every expression must match for a row to pass.

Comparison is done after rendering both sides through fmt.Sprint, so primitives, fmt.Stringer implementations, and time.Time values all compare correctly. Numeric strings ("42") and numeric values (42) compare equal — the expression dialect is string-typed.

Construct via NewFieldFilter; surface parse errors directly to the user.

func NewFieldFilter(exprs ...string) (*FieldFilter, error)

func (f *FieldFilter) Apply(value any) (any, error)

type Filter ¶

type Filter interface {

	// Apply returns a (possibly modified) value, or an error if the filter expression is invalid
	// for the input shape.
	Apply(value any) (any, error)
}

Filter is the selection stage of the result pipeline. Implementations narrow, transform, or pass-through the value before it reaches the formatter.

func FilterByExprs(fieldExprs []string, jqExpr string) (Filter, error)

type Formatter ¶

type Formatter interface {

	// Format renders value to w in the implementation's format (JSON, YAML, CSV, template, etc.).
	Format(value any, w io.Writer) error
}

Formatter is the rendering stage of the result pipeline. Implementations encode the (filtered) value as bytes on the writer.

The writer parameter is typed as io.Writer rather than sink.Sink because formatters operate on a byte stream — they don't need TTY-awareness, Close lifecycle, or any other Sink-specific concerns. Pipeline.Emit passes its sink.Sink (which is an io.Writer) to Format directly; stdlib encoders (encoding/json, gopkg.in/yaml.v3, etc.) plug in without adapter shims.

func FormatterByName(spec string) (Formatter, error)

type HasHeaders ¶

type HasHeaders interface {

	// Headers returns the column order to use when rendering the receiver as CSV.
	Headers() []string
}

HasHeaders is the opt-in interface that overrides automatic header inference. Implementations are typically named-slice types whose row shape doesn't lend itself to reflection (e.g., heterogeneous row content keyed by symbolic names).

type JQFilter ¶

type JQFilter struct {
	// contains filtered or unexported fields
}

JQFilter applies a jq expression to the value via github.com/itchyny/gojq.

The input is normalized to gojq's native shape (map[string]any / []any / primitives) by round-tripping through encoding/json. This costs a serialization pass per Apply but lets callers hand any JSON-serializable Go value to the filter without first converting it.

The expression is parsed and compiled at construction; parse errors surface there. Execution errors from gojq propagate through Apply. Single-result expressions return the unwrapped value; multi-result expressions (jq's `,` operator, `..` recursive descent, etc.) collect into a slice.

func NewJQFilter(expression string) (*JQFilter, error)

func (f *JQFilter) Apply(value any) (any, error)

type JSONFormatter ¶

type JSONFormatter struct{}

JSONFormatter renders the value as indented JSON. Two-space indentation; no HTML escaping concerns (the stream is for tooling consumption, not browser embedding).

func (JSONFormatter) Format(value any, w io.Writer) error

type ListFormatter ¶

type ListFormatter struct{}

ListFormatter renders each record as one field per line, keys aligned within the record.

This is the rendering for a result that is wide, heterogeneous, or both -- where `table` is unreadable and `json` is punctuation a reader has to see past:

name  : x
state : active

name     : y
runs     : 3
findings : ["a","b"]

It shares key derivation with DelimitedFormatter and TableFormatter -- `csv:"name"` tags, struct declaration order, sorted map keys -- and diverges on one point: the delimited formats derive ONE column set as the union across every record, where this gives each record its own keys. That is what makes it right for a heterogeneous stream, where a union renders mostly holes.

Keys are padded within a record rather than across the stream, so a heterogeneous stream does not pay for its widest key everywhere. The separator is " : " with the colon aligned, deliberately not "key: value", which reads as YAML when `-o yaml` is one flag away and means something else.

func NewListFormatter() ListFormatter

func (f ListFormatter) Format(value any, w io.Writer) error

type NoOpFilter ¶

type NoOpFilter struct{}

NoOpFilter is the pass-through Filter; Apply returns its argument unchanged.

func (NoOpFilter) Apply(value any) (any, error)

type NoneFormatter ¶

type NoneFormatter struct{}

NoneFormatter renders nothing at all.

This is not the same as redirecting to the null device. Redirection renders the value and then discards the bytes; this never renders it. The distinction matters where no shell exists to redirect -- a config file or an environment variable can select a rendering, and "no result" has to be one of them.

`aws` ships the same value as `off`; `az` and `gcloud` spell it `none`.

func (NoneFormatter) Format(_ any, _ io.Writer) error

type Pipeline ¶

type Pipeline struct {
	// contains filtered or unexported fields
}

Pipeline composes a Filter and a Formatter against a sink.Sink. Callers Emit values; the Pipeline applies the filter, hands the result to the formatter, and the formatter writes through the sink.

All fields are unexported and set at construction by NewPipeline; the value is immutable from the caller's perspective. To suppress all output, construct with sink.Discard as the sink.

func NewPipeline(filter Filter, formatter Formatter, s sink.Sink) *Pipeline

func (p *Pipeline) Emit(value any) error

type TableFormatter ¶

type TableFormatter struct {

	// MinPadding is the space between the longest cell of a column and the next column. Zero means two.
	MinPadding int
}

TableFormatter renders a slice of rows as aligned columns for a human to read.

It shares its column inference with the delimited formats -- HasHeaders, `csv:"name"` tag overrides, and the map-key union -- so one value renders the same columns whether it is asked for as `table`, `csv`, or `value`. Only the presentation differs: commas, tabs, or padding.

Alignment is text/tabwriter's, which measures cell widths in runes rather than bytes. A hand-rolled `%-30s` counts bytes and so misaligns every row containing a multi-byte character -- the defect #741 records against lore's search table.

Headers are upper-cased, matching `aws`, `kubectl`, and star's own table.

This is the human rendering. A spreadsheet wants `csv`; a shell pipeline wants `value`.

func NewTableFormatter() TableFormatter

func (f TableFormatter) Format(value any, w io.Writer) error

type TemplateFormatter ¶

type TemplateFormatter struct {
	// contains filtered or unexported fields
}

TemplateFormatter renders a value through a text/template.Template.

Reached as `--output template=<body>`, never as a separate flag: the format value carries its own argument, so there is no pairing to get wrong and no state where a body is supplied and ignored.

The value passed to [Format] is the template's `.` binding. The template is parsed once at construction, so a malformed body fails when the pipeline is built rather than per emission.

Most reshaping belongs in the filter stage instead. `--jq` selects, maps, and interpolates, and composes with every format; a template earns its place only for text layout a query cannot express.

func NewTemplateFormatter(body string) (*TemplateFormatter, error)

func (t *TemplateFormatter) Format(value any, w io.Writer) error

type YAMLFormatter ¶

type YAMLFormatter struct{}

YAMLFormatter renders the value as indented YAML. Two-space indentation; latest stable yaml.v3 from go-yaml.

func (YAMLFormatter) Format(value any, w io.Writer) (err error)