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

func (f DelimitedFormatter) Group() Group

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

	// Group reports the kind of reader this rendering serves. See [Group].
	Group() Group
}

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 Group ¶

type Group string

Group is the kind of reader a rendering serves.

Nine names in one alphabetical list answer "what exists" and never "which one do I want". Five groups answer the second question, and the grouping is load-bearing rather than decorative: the pager pages what a person reads and nothing else, and it asks the formatter its group rather than keeping a list of names that would drift the first time a rendering was added.

The values are the display names, because they are shown as headings in `--output`'s help and in the generated man pages.

const (

	// GroupComposed is for renderings whose shape the caller chose: `template=BODY` and `value`. The filter
	// stage built the shape and this stage prints it, so paging or decorating it would be this suite second-
	// guessing a shape it was handed.
	GroupComposed Group = "Composed"

	// GroupDocument is for renderings that produce a document: `markdown` and `terminal`. They differ in
	// whether the markup is rendered.
	GroupDocument Group = "Document"

	// GroupNothing is for `none`, which emits nothing at all: the exit code and the side effects are the
	// result.
	GroupNothing Group = "Nothing"

	// GroupRecords is for records laid out for a person: `list` and `table`. They differ in whether the
	// records share one schema -- `table` derives one column set and leaves holes, `list` gives each record
	// its own keys (§8).
	GroupRecords Group = "Records"

	// GroupSerialized is for the lossless renderings a library reads back: `csv`, `json` and `yaml`. That
	// yaml is pleasanter to read than json is a property of yaml, not a different job -- nobody hand-writes a
	// `writ status` result.
	GroupSerialized Group = "Serialized"
)

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

func (JSONFormatter) Group() Group

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

func (ListFormatter) Group() Group

type MarkdownFormatter ¶

type MarkdownFormatter struct{}

MarkdownFormatter renders a value as a markdown document.

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

Two rules decide the shape, and between them they answer §8's eight:

• **A scalar string passes through verbatim.** A command whose result is prose returns the document itself, and a document is not a datum to be laid out. `star docs starlark` is one.
• **Otherwise: a GFM table where the inference yields headers, a bullet list where it does not.** GitHub-flavored markdown has no headerless table -- the delimiter row is required -- and synthesizing column names would name fields the data does not have.

Headers keep the case the JSON gives them, unlike TableFormatter, which upper-cases. These are the names the `json:` tags declare and the names the Starlark surface shows a customer; a markdown document is read by people and by GitHub, and neither wants them shouted.

A non-scalar cell renders as compact JSON, at any depth, never truncated -- the rule §8 states for every presentation that lays data out.

func NewMarkdownFormatter() MarkdownFormatter

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

func (MarkdownFormatter) Group() Group

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

func (NoneFormatter) Group() Group

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

func (TableFormatter) Group() Group

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

func (*TemplateFormatter) Group() Group

type TerminalFormatter ¶

type TerminalFormatter struct {

	// WordWrap is the column text wraps at. Zero means [terminalWordWrap]. Fixed rather than read from the
	// terminal, since reading it would be a probe.
	WordWrap int

	// NoColor drops every color and keeps every attribute. [NewTerminalFormatter] sets it from `NO_COLOR`.
	NoColor bool
	// contains filtered or unexported fields
}

TerminalFormatter renders a value as a document laid out for a terminal: bold, italic, color, word wrap, and box-drawn tables.

It is the second link of a chain. MarkdownFormatter turns the normalized JSON into a markdown document, and this formatter hands that document to glamour: goldmark parses it, glamour's renderer walks the tree, and [terminalStyle] decides what each element becomes.

Every marker is consumed and re-emitted as an attribute -- a heading loses its `#`, `**` becomes bold, `*` becomes italic, a code span loses its backticks. That is what separates this from glamour's own `notty` style, which keeps every marker, and from `markdown`, which is the source.

Nothing is probed. glamour's color profile defaults to TrueColor rather than asking the terminal, and the style is fixed rather than glamour's `auto`, which reads the terminal's background. So the bytes are the same piped, redirected, or on a TTY -- §7's rule that a rendering does not change when it is observed. A caller who wants no escape codes asks for `markdown`.

`NO_COLOR` is honored, because it is an input rather than a probe. Set and not empty, it drops every color and keeps every attribute: no-color.org's rule suppresses color, not bold, italic, or underline. §10 of the specification records why the suite honors a convention no standards body stands behind.

func NewTerminalFormatter() TerminalFormatter

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

func (TerminalFormatter) Group() Group

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)

func (YAMLFormatter) Group() Group