output

package
v1.9.5 Latest Latest
Warning

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

Go to latest
Published: Mar 31, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package output provides structured output formatting for CLI commands. It supports text (default) and JSON output modes, allowing commands to produce machine-readable output for CI/CD pipelines and scripting.

Index

Constants

View Source
const (
	StatusSuccess = "success"
	StatusError   = "error"
	StatusWarning = "warning"
)

Status constants for the Response envelope.

Variables

This section is empty.

Functions

func Emit added in v1.7.0

func Emit(cmd *cobra.Command, resp Response) error

Emit writes a Response to cmd.OutOrStdout() when --output is "json". It is a no-op when the output format is text or the flag is absent.

func EmitError added in v1.7.0

func EmitError(cmd *cobra.Command, commandName string, err error) error

EmitError builds an error Response envelope and emits it via Emit.

func IsJSONOutput added in v1.7.0

func IsJSONOutput(cmd *cobra.Command) bool

IsJSONOutput returns true if the --output flag on the command is set to "json".

func RenderMarkdown added in v1.7.0

func RenderMarkdown(content string) string

RenderMarkdown renders markdown content to styled ANSI terminal output via glamour. It detects the terminal width automatically, falling back to 80 columns. If glamour fails for any reason, the original content is returned unchanged.

Types

type Column added in v1.8.0

type Column struct {
	// Header is the display name shown in the table header row.
	Header string
	// Field is the struct field name or map key to extract the value from.
	Field string
	// Width is the fixed column width. Zero means auto-sized to content.
	Width int
	// Sortable indicates this column can be used as a sort key.
	Sortable bool
	// Formatter is an optional function to format the cell value.
	Formatter func(any) string
}

Column defines a single table column.

type Format

type Format string

Format represents the output format for commands.

const (
	// FormatText is the default human-readable output format.
	FormatText Format = "text"
	// FormatJSON produces machine-readable JSON output.
	FormatJSON Format = "json"
	// FormatYAML produces machine-readable YAML output.
	FormatYAML Format = "yaml"
	// FormatCSV produces comma-separated values output.
	FormatCSV Format = "csv"
	// FormatMarkdown produces a pipe-delimited markdown table with header separators.
	FormatMarkdown Format = "markdown"
	// FormatTSV produces tab-separated values output for shell pipelines.
	FormatTSV Format = "tsv"
)

type Response added in v1.7.0

type Response struct {
	Status  string `json:"status"`
	Command string `json:"command"`
	Data    any    `json:"data,omitempty"`
	Error   string `json:"error,omitempty"`
}

Response is the standard JSON envelope for all command output.

type TableOption added in v1.8.0

type TableOption func(*tableConfig)

TableOption configures the TableWriter.

func WithColumns added in v1.8.0

func WithColumns(cols ...Column) TableOption

WithColumns explicitly defines the table columns. When not provided, columns are derived from struct tags on the row data type.

func WithMaxWidth added in v1.8.0

func WithMaxWidth(width int) TableOption

WithMaxWidth overrides automatic terminal width detection.

func WithNoHeader added in v1.8.0

func WithNoHeader() TableOption

WithNoHeader suppresses the header row in text table output.

func WithNoTruncation added in v1.8.0

func WithNoTruncation() TableOption

WithNoTruncation disables terminal-width truncation. Useful when output is piped to a file or another process.

func WithSortBy added in v1.8.0

func WithSortBy(field string) TableOption

WithSortBy sets the column to sort rows by. The column must be marked Sortable.

func WithSortDescending added in v1.8.0

func WithSortDescending() TableOption

WithSortDescending reverses the sort order.

type TableWriter added in v1.8.0

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

TableWriter renders structured data as an aligned table or machine-readable format.

func NewTableWriter added in v1.8.0

func NewTableWriter(w io.Writer, format Format, opts ...TableOption) *TableWriter

NewTableWriter creates a TableWriter that writes to the given io.Writer.

func (*TableWriter) WriteRows added in v1.8.0

func (t *TableWriter) WriteRows(rows any) error

WriteRows renders the provided slice as a table. The input must be a slice of structs (for tag-based columns) or []map[string]any. For JSON/YAML formats, the raw data is marshalled directly. For CSV format, columns are used as the header row. For text format, an aligned table with padding is produced.

type Writer

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

Writer handles formatted output based on the configured format.

func NewWriter

func NewWriter(w io.Writer, format Format) *Writer

NewWriter creates an output writer for the given format.

func (*Writer) IsJSON

func (o *Writer) IsJSON() bool

IsJSON returns true if the writer is configured for JSON output.

func (*Writer) Render added in v1.7.0

func (o *Writer) Render(markdown string) error

Render writes markdown to the Writer using glamour styling in text mode. In JSON mode it is a no-op — callers should use Write for JSON output.

func (*Writer) Write

func (o *Writer) Write(data any, textFunc func(io.Writer)) error

Write outputs data in the configured format. For JSON format, data is marshalled to indented JSON. For text format, the textFunc is called to produce human-readable output.

Jump to

Keyboard shortcuts

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