Documentation
¶
Overview ¶
Package output renders command results. stdout carries exactly one JSON document, because that is what an agent parses; everything a person needs to read goes to stderr.
Index ¶
- func CodeOf(err error) string
- func EnsureSlice[T any](values []T) []T
- func ProtoValue(message proto.Message) (json.RawMessage, error)
- func ProtoValues[T proto.Message](messages []T) (json.RawMessage, error)
- type Error
- type Format
- type Renderer
- func (r *Renderer) Envelope(value any, rows []Row) error
- func (r *Renderer) Format() Format
- func (r *Renderer) JSON(value any) error
- func (r *Renderer) Message(message proto.Message, rows []Row) error
- func (r *Renderer) Progress(format string, args ...any)
- func (r *Renderer) ProtoJSON(message proto.Message) error
- func (r *Renderer) Table(rows []Row) error
- func (r *Renderer) WriteError(err Error)
- type Row
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CodeOf ¶
CodeOf maps an error onto the CLI's stable error code, which is what an agent branches on. The matching exit codes live in the client package.
func EnsureSlice ¶
func EnsureSlice[T any](values []T) []T
EnsureSlice returns a non-nil slice so an empty list encodes as [] rather than null: a caller iterating the result should not have to special-case it.
func ProtoValue ¶
func ProtoValue(message proto.Message) (json.RawMessage, error)
ProtoValue renders a protobuf message for embedding in an envelope.
A message put into an envelope as-is would be encoded by encoding/json, which reads the struct tags protoc-gen-go emits: snake_case. The same relation would then look different depending on whether it was the whole result or one entry of a list.
func ProtoValues ¶
func ProtoValues[T proto.Message](messages []T) (json.RawMessage, error)
ProtoValues renders a list of protobuf messages for embedding in an envelope. An empty list encodes as [], never as null.
Types ¶
type Error ¶
type Error struct {
Code string `json:"code"`
Message string `json:"message"`
Hint string `json:"hint,omitempty"`
Details []string `json:"details,omitempty"`
}
Error is the machine-readable error envelope. Hint carries an actionable next step, which is what lets an agent recover without guessing.
type Format ¶
type Format string
Format is the rendering the caller asked for.
func ParseFormat ¶
ParseFormat validates the --format value.
type Renderer ¶
type Renderer struct {
// contains filtered or unexported fields
}
Renderer writes results to stdout and progress to stderr.
func (*Renderer) Envelope ¶
Envelope renders a command-specific result shape in JSON mode and the supplied rows in table mode.
func (*Renderer) Message ¶
Message renders a protobuf message. Table mode uses the supplied rows, and falls back to JSON when the caller had none to give.
func (*Renderer) Progress ¶
Progress writes a human-readable line to stderr. It is never part of the machine-readable contract.
func (*Renderer) WriteError ¶
WriteError writes the error envelope to stderr.
Source Files