Documentation
¶
Index ¶
- func FormatValue(v any) string
- func IsMachineRendered(format Format) bool
- func IsTerminal(fd uintptr) bool
- func RendersStructureVerbatim(format string) bool
- func ResolveFormat(flagChanged bool, current, configDefault string, isTTY, hasOutFile bool) string
- type Format
- type Formatter
- func (f *Formatter) Format() string
- func (f *Formatter) PaginationProgress() *progress.Reporter
- func (f *Formatter) Print(data any) error
- func (f *Formatter) PrintBytes(data []byte) error
- func (f *Formatter) PrintError(err error, code string, details map[string]any)
- func (f *Formatter) PrintRaw(data []byte) error
- func (f *Formatter) SetExplicitNoColor(v bool)
- func (f *Formatter) SetNoHints(v bool)
- func (f *Formatter) SetProjector(p Projector)
- func (f *Formatter) SetQuiet(q bool)
- func (f *Formatter) SetWriter(w io.Writer)
- func (f *Formatter) WithFormat(format string) *Formatter
- func (f *Formatter) Writer() io.Writer
- type Projector
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FormatValue ¶
FormatValue converts a value to its string representation for table/csv/plain output.
func IsMachineRendered ¶ added in v1.29.0
IsMachineRendered reports whether Print renders format with a non-table renderer whose output a parser reads, so a section banner must not be written above it.
It sits beside Print's own switch, because the answer follows that switch. Print has no case for FormatXML or FormatRaw, so both reach printTable through the default arm and both take a banner.
FormatPlain counts as machine-rendered here. It has no header row, so a banner between runs of it is data a reader cannot separate from a record.
func IsTerminal ¶ added in v1.19.0
IsTerminal reports whether the given file descriptor is a character device. Used to choose human (table) vs machine (json) defaults and to gate color.
func RendersStructureVerbatim ¶ added in v1.29.0
RendersStructureVerbatim reports whether a format renders a value's own structure rather than projecting it into columns.
It exists so a command that narrows its row type for the column formats can name the formats that keep the wide shape, instead of naming the column ones and returning the wide shape for everything else. That polarity matters because the format string is never normalised: New takes the --output value verbatim and ResolveFormat returns it untouched, so "Table" is not FormatTable, and Print's own switch has no case for it and renders a table through the default arm. A command matching "table" exactly therefore handed its wide shape to a table renderer, which is how `config list -o Table` came to drop a column `config list -o table` shows (issue 353). Anything unrecognised renders as a table, so the narrow shape is the matching one.
FormatJSONMulti is deliberately absent: it means JSON on the wire and a table on the screen (internal/commands/multi.go sets it as the capture format, and Print has no case for it either), so keeping the wide shape for it would put that shape back on a terminal by way of `jamf-cli multi`. The generated selectTableColumns excludes it from its own keep-set for the same reason, and this function is that set.
func ResolveFormat ¶ added in v1.19.0
ResolveFormat decides the effective output format. Precedence: explicit --output flag > config default_output > auto (TTY -> table, otherwise json). Writing to a file is treated as non-interactive.
Types ¶
type Format ¶
type Format string
Format represents an output format
const ( FormatTable Format = "table" FormatJSON Format = "json" FormatJSONMulti Format = "json-multi" // internal: like json but triggers column selection in selectTableColumns FormatCSV Format = "csv" FormatYAML Format = "yaml" FormatPlain Format = "plain" FormatXML Format = "xml" // Classic API native format — pretty-printed XML FormatRaw Format = "raw" // Exact wire bytes, no conversion or formatting FormatNDJSON Format = "ndjson" // newline-delimited JSON: one compact object per line, no array )
type Formatter ¶
type Formatter struct {
// contains filtered or unexported fields
}
Formatter handles output formatting
func (*Formatter) PaginationProgress ¶ added in v1.22.0
PaginationProgress builds a progress reporter for an --all pagination loop, choosing the rendering mode from the formatter's state: silent when quiet, an in-place count line on an interactive color terminal, NDJSON page_fetch events otherwise.
func (*Formatter) PrintBytes ¶
PrintBytes writes bytes to the output. XML is pretty-printed unless the format is FormatRaw, which writes exact wire bytes. Used by Classic API commands to emit XML when no structured format is requested.
func (*Formatter) PrintError ¶
PrintError outputs an error in the appropriate format
func (*Formatter) PrintRaw ¶
PrintRaw outputs raw bytes (usually JSON from the API). XML responses (from Classic API) are converted to JSON before formatting, unless the format is FormatXML (pretty-printed) or FormatRaw (exact wire bytes).
func (*Formatter) SetExplicitNoColor ¶ added in v1.22.0
SetExplicitNoColor records whether the user explicitly disabled color (--no-color or NO_COLOR), as distinct from color being auto-disabled because stdout is piped. Pagination progress uses this so a piped stdout still shows the in-place stderr counter when stderr is a terminal.
func (*Formatter) SetNoHints ¶ added in v1.18.0
SetNoHints suppresses advisory hints (e.g. the list-size hint) written to stderr. Unlike SetQuiet it leaves the spinner and progress output alone — a narrower opt-out. Errors and primary output on stdout are unaffected.
func (*Formatter) SetProjector ¶ added in v1.17.0
SetProjector configures field-level projection (e.g. --compact) applied before format-specific rendering. A zero-value projector is a no-op.
func (*Formatter) SetQuiet ¶ added in v1.17.0
SetQuiet suppresses advisory output written to stderr (e.g. the list-size hint). Errors and primary output on stdout are unaffected.
func (*Formatter) WithFormat ¶ added in v1.29.0
WithFormat returns a copy of f rendering in format, keeping the writer, the projector and the advisory settings. A command whose own argument names the format uses it so --out-file, --select and --compact still apply.
The copy is shallow, which is safe only while every field is a value or an immutable reference: Select's backing array is never mutated after SetProjector, and writer is an interface the clone shares deliberately. formatterFor clones once per report section, so a future pointer, map or buffer field would alias mutable state across every section.
type Projector ¶ added in v1.17.0
Projector applies field-level projection to flattened rows before format-specific rendering. Compact keeps only scalar fields after flattening, dropping arrays and nested remnants. Select keeps only the listed dot paths. When both are set, Select wins. The projector is shared by every output format (json, table, csv, yaml, plain) so projection behaves consistently.
func (Projector) Apply ¶ added in v1.17.0
Apply returns rows projected per the configured rules. Always flattens nested objects to dot keys so projection sees a flat shape. Empty rows pass through unchanged.
Select uses flattenRowsRaw (no common-prefix stripping) so user-supplied dot paths like "general.name" still match on single-section responses where stripCommonPrefix would otherwise rewrite "general.name" → "name" and silently produce empty projections.
func (Projector) IsZero ¶ added in v1.17.0
IsZero reports whether the projector has no rules configured.
Select is measured after trimming, because projectSelect drops a blank path and returns the rows unprojected when none survives. Reading the raw length made `--select " "` render wider than --wide.
func (Projector) RendersNothing ¶ added in v1.29.0
RendersNothing reports whether the projector leaves every row with no fields, which is when a renderer produces no output for them.
It does not filter rows. Dropping the emptied rows instead left the survivors heterogeneous, which moved the defect into the column set and then into every per-format contract. The renderers decline an empty column set themselves, so a caller decides only its own banner.
Source Files