Documentation
¶
Overview ¶
Package output renders command results as JSON, YAML, or tables, plus the stable error envelope.
Index ¶
- func IsTerminal(fd uintptr) bool
- func NewTabWriter(w io.Writer) *tabwriter.Writer
- func ParseFieldsFlag(s string) []string
- func RenderError(w io.Writer, mode Mode, env ErrorEnvelope) error
- func RenderJSON(w io.Writer, v any, fields []string) error
- func RenderYAML(w io.Writer, v any, fields []string) error
- func StderrIsTerminal() bool
- func StdoutIsTerminal() bool
- type ErrorEnvelope
- type Mode
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsTerminal ¶
IsTerminal reports whether the given file descriptor is a terminal. Wraps golang.org/x/term so callers don't import it directly.
func NewTabWriter ¶
NewTabWriter returns a *text/tabwriter.Writer configured for traceway's table output style: left-aligned columns separated by two spaces. Callers must call Flush() after writing all rows.
tw := output.NewTabWriter(w) fmt.Fprintln(tw, "ID\tNAME") fmt.Fprintf(tw, "%s\t%s\n", id, name) tw.Flush()
func ParseFieldsFlag ¶
ParseFieldsFlag splits "a, b, c" → []string{"a", "b", "c"}. Empty input → nil.
func RenderError ¶
func RenderError(w io.Writer, mode Mode, env ErrorEnvelope) error
RenderError writes the envelope to w. Compact JSON for ModeJSON/ModeYAML; prose for ModeTable. (YAML mode uses JSON for errors — easier for callers to parse and matches gh's behavior for machine-formatted errors.)
func RenderJSON ¶
RenderJSON marshals v as compact JSON to w (one record per line, no indent). If fields is non-nil, projects each item of a top-level "data" array (Traceway's wrapper shape) — or the top-level object itself if it has no "data" key — to just the named fields. "pagination" and other top-level wrapper keys pass through unchanged.
Compact output is intentional: it minimizes tokens for LLM consumers and matches what real APIs return. Humans wanting pretty output can pipe to `jq` (or use `--output table`).
func RenderYAML ¶
RenderYAML marshals v as YAML to w, applying the same field projection as RenderJSON when fields is non-nil. Internally we round-trip through JSON so that callers' types only need json struct tags (no need for parallel yaml tags on every struct in pkg/client).
Types ¶
type ErrorEnvelope ¶
type ErrorEnvelope struct {
Code string `json:"error"`
Message string `json:"message"`
Hint string `json:"hint,omitempty"`
ExitCode int `json:"exit_code"`
}
ErrorEnvelope is the stable error contract written to stderr on any failure. Code is a snake_case stable identifier; LLMs may branch on it.
type Mode ¶
type Mode int
Mode controls how Render formats its output.
func ResolveMode ¶
ResolveMode picks an effective Mode. An explicit user value wins; otherwise default to table on TTY and json on non-TTY.
The error returned by ParseMode for invalid explicit values is intentionally suppressed here — the caller should validate via ParseMode at flag-parse time.
Source Files