output

Documentation

Overview

Package output renders command results as table or JSON.

Use Format to dispatch on the global -o/--output flag. JSON output goes to stdout (errors included) so it's pipeable to `jq`.

Index

• Constants
• func FormatUnixMillis(ms int64) string
• func JSON(w io.Writer, v any) error
• func PrintErrorJSON(w io.Writer, message string, httpOrExitCode int)
• func Render(w io.Writer, cols []Column, rows [][]string)
• func Truncate(s string, max int) string
• func Validate(format string) error
• type Column
• type ErrorEnvelope

Constants

const (
	FormatTable = "table"
	FormatJSON  = "json"
)

Format names. Use these constants to avoid stringly-typed mistakes.

const EmptyPlaceholder = "-"

EmptyPlaceholder is shown for nil / empty cell values in tables.

const TimeFormat = "2006-01-02 15:04"

TimeFormat is the table-mode timestamp format (local timezone).

Functions

func FormatUnixMillis

func FormatUnixMillis(ms int64) string

FormatUnixMillis renders a millisecond UNIX timestamp in local time. Zero / negative timestamps yield EmptyPlaceholder.

func JSON

func JSON(w io.Writer, v any) error

JSON writes v to w as a JSON document, no trailing newline beyond what encoding/json adds. Errors writing v are non-fatal (we still attempt to emit at least a JSON error envelope).

func PrintErrorJSON

func PrintErrorJSON(w io.Writer, message string, httpOrExitCode int)

PrintErrorJSON writes {"error":{"message":..., "code":...}} to w (stdout). httpOrExitCode is the HTTP status if known, otherwise the exit code.

func Render

func Render(w io.Writer, cols []Column, rows [][]string)

Render writes a table to w. rows[i][j] is the cell value for row i, column j.

func Truncate

func Truncate(s string, max int) string

Truncate trims s so its runewidth is at most max, appending "…" if truncated. Returns s as-is if already short enough or if max < 1.

When max is too small to even fit the ellipsis, the function falls back to ASCII "." or "" so the cell never exceeds max columns.

func Validate

func Validate(format string) error

Validate returns an error if format is not a recognized value.

Types

type Column

type Column struct {
	Header string
	Width  int // display width (runewidth); 0 = auto from header
}

Column describes a single table column.

type ErrorEnvelope

type ErrorEnvelope struct {
	Error errorBody `json:"error"`
}

ErrorEnvelope is the JSON shape for command errors.