Help us shape the future of Go! Take the 2026 Go Developer Survey

output

package
v1.47.0 Latest Latest
Warning

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

 Go to latest Published: Oct 31, 2026 License: Apache-2.0 Imports: 35 Imported by: 0

Documentation

Overview

Package output provides shared output writing and failure classification.

Index

Constants

View Source 
const LoadingDelay = 400 * time.Millisecond
View Source 
const ResourceSummaryHint = "Full data: --format json."

Variables

View Source 
var ErrDownloadDestinationChanged = errors.New("download destination changed during transfer")

ErrDownloadDestinationChanged signals that a destination or staging file changed ownership or state.

View Source 
var ErrDownloadSymlink = errors.New("symlink download destinations are not supported")

ErrDownloadSymlink reports an unsupported final-entry symlink destination.

View Source 
var Formats = []string{"auto", "text", "explore", "json", "jsonl", "pretty", "raw", "yaml"}

Functions

func APIRequestID added in v1.39.1 

func APIRequestID(apierr *openai.Error) string

APIRequestID accepts only bounded, single-line returned identifiers and rejects caller reflection.

func ApplyJSONPath 

func ApplyJSONPath(value gjson.Result, path string) gjson.Result

ApplyJSONPath preserves the original value when the requested path is absent.

func CopyBinaryOutput added in v1.39.1 

func CopyBinaryOutput(ctx context.Context, destination io.Writer, source io.Reader) error

CopyBinaryOutput uses process SIGPIPE protection only for actual stdout. Keep the copy errors unmarked so StreamToStdout cannot suppress an observed failure.

func CopyDownloadData added in v1.39.1 

func CopyDownloadData(ctx context.Context, destination io.Writer, source io.Reader) error

CopyDownloadData retains source errors returned with bytes even if writing those bytes fails. io.Copy otherwise returns only the destination error in that case.

func CountTerminalLines 

func CountTerminalLines(data []byte, terminalWidth int) int

CountTerminalLines counts wrapped newlines using the existing pager policy.

func CreatePrivateDownloadFile 

func CreatePrivateDownloadFile(root *os.Root, name string) (*os.File, error)

CreatePrivateDownloadFile exclusively creates private download staging inside root.

func DownloadContext added in v1.39.1 

func DownloadContext(response *http.Response) context.Context

DownloadContext retains the response request context, or uses a background context.

func DownloadContextError added in v1.39.1 

func DownloadContextError(ctx context.Context) error

DownloadContextError retains both context cancellation and its underlying cause.

func DownloadSignalContext added in v1.39.1 

func DownloadSignalContext(parent context.Context) (context.Context, func())

DownloadSignalContext cancels on process signals. The caller unregisters and reaps this watcher before returning; ordinary cleanup never changes a successful result.

func FormatJSON 

func FormatJSON(res gjson.Result, opts FormatOptions, destination io.Writer, terminal bool) ([]byte, error)

FormatJSON formats one result. The caller classifies the final destination, including feature wrappers and terminals behind pagers; intermediate buffers must not change terminal escaping or color policy.

func IsBrokenPipe 

func IsBrokenPipe(err error) bool

IsBrokenPipe reports whether every cause is a broken output pipe, excluding diagnostic writes and upstream failures.

func LoadingAnimationSupported added in v1.39.1 

func LoadingAnimationSupported(getenv func(string) string) bool

func LoadingSpinner added in v1.39.1 

func LoadingSpinner(getenv func(string) string, goos string) spinner.Spinner

func OpenDownloadDestination added in v1.39.1 

func OpenDownloadDestination(path string, nonblock bool) (*os.File, error)

OpenDownloadDestination opens an existing output without following its final symlink or modifying its contents. nonblock protects regular-file inspection against a concurrent substitution with a FIFO.

func ParameterFlag added in v1.39.1 

func ParameterFlag(command *cli.Command, parameter string) (name, path string)

ParameterFlag maps untrusted API parameter paths to locally declared flags.

func ResolveFormat 

func ResolveFormat(opts FormatOptions) string

Automatic output is readable on every destination. Extraction keeps its existing JSON/raw-string contract, including when stdout is redirected.

func StartLoadingFeedback added in v1.39.1 

func StartLoadingFeedback(ctx context.Context, out io.Writer, label, prompt string, animate bool, animation spinner.Spinner, size func() (int, int)) (stopFeedback func(), advance func(LoadingStage))

The picker supplies only prompt text already visible in its form. Clearing frames does not redact terminal captures. The caller stops this worker before another writer uses the terminal. Feedback writes are best effort; stop joins the worker without changing cursor visibility or terminal input modes.

func Stream 

func Stream(label string, generateOutput func(w *os.File) error) error

Stream writes to process stdout or its pager according to terminal state.

func StreamToPager 

func StreamToPager(label string, generateOutput func(w *os.File) error) error

func StreamToPagerWithPipe 

func StreamToPagerWithPipe(label string, generateOutput func(w *os.File) error) error

StreamToPagerWithPipe runs the pipe-based pager transport used on Windows and when the Unix socket transport cannot be established.

func StreamToStdout 

func StreamToStdout(generateOutput func(w *os.File) error) error

StreamToStdout preserves stdout signal handling and suppresses only failures classified as broken output pipes, retaining upstream and diagnostic errors.

func Transform 

func Transform(ctx context.Context, value gjson.Result, transform transformers.Transformer) (gjson.Result, error)

Transform checks cancellation before and after one response transformation.

func UseColors 

func UseColors(terminal bool) bool

UseColors applies JSON color policy to the final destination classification.

func WriteFiniteJSONList 

func WriteFiniteJSONList[T any](source jsonview.Iterator[T], opts FiniteJSONListOptions) error

WriteFiniteJSONList frames a finite source as one JSON array without collecting the complete result. The caller retains ownership of the source.

func WriteManagedBinaryResponse added in v1.39.1 

func WriteManagedBinaryResponse(response *http.Response, outfile string) (string, error)

WriteManagedBinaryResponse stages the network transfer before changing ordinary destinations. Existing files keep their inode, links, permissions, ACLs and xattrs. A later local completion failure can leave those existing files partially written.

func WriteManagedDownloadResponse added in v1.39.1 

func WriteManagedDownloadResponse(
	response *http.Response,
	outfile string,
	copyResponse func(context.Context, io.Writer, io.Reader) error,
) (message string, err error)

WriteManagedDownloadResponse stages a transfer using endpoint-specific validation, including speech SSE.

func WriteReadableIterator 

func WriteReadableIterator(iter jsonview.Iterator[JSON], opts ReadableOptions) error

WriteReadableIterator renders records as they arrive, keeping stream state separate from list records.

func WriteReadableResource 

func WriteReadableResource(out io.Writer, value gjson.Result, opts ReadableOptions) (bool, error)

WriteReadableResource applies resource projections to readable results without field extraction. Report omissions so each response or list can explain them once.

Types

type DiagnosticError 

type DiagnosticError struct{ Err error }

DiagnosticError identifies failures that belong to stderr, even inside stdout's stream lifecycle.

func (*DiagnosticError) Error 

func (e *DiagnosticError) Error() string

func (*DiagnosticError) Unwrap 

func (e *DiagnosticError) Unwrap() error

type DownloadResponseBody added in v1.39.1 

type DownloadResponseBody struct {
	io.ReadCloser
	// contains filtered or unexported fields
}

DownloadResponseBody lets cancellation and ordinary completion share ownership.

func (*DownloadResponseBody) Close added in v1.39.1 

func (b *DownloadResponseBody) Close() error

type DownloadSaveError added in v1.39.1 

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

DownloadSaveError reports the destination's state without exposing local paths.

func NewDownloadSaveError added in v1.39.1 

func NewDownloadSaveError(message string, cause error) *DownloadSaveError

NewDownloadSaveError retains the underlying cause behind a value-safe message.

func (*DownloadSaveError) Error added in v1.39.1 

func (e *DownloadSaveError) Error() string

func (*DownloadSaveError) ExitCode added in v1.39.1 

func (e *DownloadSaveError) ExitCode() int

func (*DownloadSaveError) Unwrap added in v1.39.1 

func (e *DownloadSaveError) Unwrap() error

type DownloadSignalError added in v1.39.1 

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

DownloadSignalError identifies cancellation caused by a process signal.

func (*DownloadSignalError) Error added in v1.39.1 

func (e *DownloadSignalError) Error() string

func (*DownloadSignalError) SignalExitCode added in v1.39.1 

func (e *DownloadSignalError) SignalExitCode() int

SignalExitCode returns the status for the process signal that canceled the operation.

func (*DownloadSignalError) Unwrap added in v1.39.1 

func (e *DownloadSignalError) Unwrap() error

type FiniteJSONListError 

type FiniteJSONListError struct{}

FiniteJSONListError contains a fixed diagnostic for malformed list items. It never includes response data or parser error details.

func (*FiniteJSONListError) Error 

func (*FiniteJSONListError) Error() string

type FiniteJSONListOptions 

type FiniteJSONListOptions struct {
	IteratorOptions
	Stdout   io.Writer
	Terminal bool
	Title    string
}

FiniteJSONListOptions carries an already selected finite-list presentation. Callers supply Context and Transform, check initial source/cancellation errors, and apply feature selection before invoking WriteFiniteJSONList. Terminal describes the final destination, including wrapped terminal writers.

type FormatOptions 

type FormatOptions struct {
	Format    string
	RawOutput bool
	Title     string
	Transform string
}

FormatOptions describes one JSON value after feature-specific transformation. Interactive exploration, paging, and output lifecycle remain with the caller.

type Iterator 

type Iterator[T any] struct {
	// contains filtered or unexported fields
}

Iterator shares one lazy transformation boundary across direct output, the pager, and the explorer. Current never reruns a transformation.

func NewIterator 

func NewIterator[T any](source jsonview.Iterator[T], opts IteratorOptions) *Iterator[T]

NewIterator shares one lazy transformation boundary between output consumers. Construction does not advance the source or inspect its error state.

func (*Iterator[T]) Current 

func (it *Iterator[T]) Current() JSON

func (*Iterator[T]) Err 

func (it *Iterator[T]) Err() error

func (*Iterator[T]) Next 

func (it *Iterator[T]) Next() bool

type IteratorOptions 

type IteratorOptions struct {
	Context   context.Context
	Transform transformers.Transformer
	Route     transformers.Route
	Limit     int64
}

IteratorOptions retains the caller's route, transformation, and item boundary. Zero Limit consumes no items; negative Limit is unlimited. Callers supply a Context and Transform for any iterator they advance.

type JSON 

type JSON struct{ gjson.Result }

JSON carries the same transformed value to direct, paged, and explorer output.

func (JSON) RawJSON 

func (value JSON) RawJSON() string

type LoadingStage added in v1.39.1 

type LoadingStage int32
const (
	LoadingWaiting LoadingStage = iota
	LoadingSaving
	LoadingSaved
)

type PagerError 

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

PagerError distinguishes pager setup and process failures from the request, formatter, or output callback. Keep the cause available to errors.Is/As.

func (*PagerError) Unwrap 

func (e *PagerError) Unwrap() error

type ReadableOptions 

type ReadableOptions struct {
	Context context.Context
	Route   transformers.Route
	FormatOptions
	Stdout, Stderr     io.Writer
	Terminal           bool
	DiagnosticsAllowed bool
	// EmptyText overrides the default message for a successful empty result.
	EmptyText string
}

ReadableOptions describes an already selected readable presentation. Assembly supplies a non-nil Context and writers, the final destination classification, and permission to emit optional diagnostics. The iterator is already transformed.

type ReceiptError added in v1.39.1 

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

ReceiptError reports that output was saved but its receipt could not be written.

func NewReceiptError added in v1.39.1 

func NewReceiptError(cause error) *ReceiptError

NewReceiptError retains the failed diagnostic write behind a fixed message.

func (*ReceiptError) Error added in v1.39.1 

func (e *ReceiptError) Error() string

func (*ReceiptError) Unwrap added in v1.39.1 

func (e *ReceiptError) Unwrap() error

type StreamResultError 

type StreamResultError struct{ Message string }

StreamResultError carries only fixed classifications from the stream transformers, never API prose, so the command presenter can retain meaning.

func (*StreamResultError) Error 

func (e *StreamResultError) Error() string

type TerminalWriter added in v1.39.1 

type TerminalWriter struct {
	Writer
	File *os.File
}

TerminalWriter preserves terminal detection when a viewer uses guarded output. Close retains ownership semantics by closing File; it is not a borrowed writer.

func (TerminalWriter) Close added in v1.39.1 

func (w TerminalWriter) Close() error

func (TerminalWriter) Fd added in v1.39.1 

func (w TerminalWriter) Fd() uintptr

func (TerminalWriter) Read added in v1.39.1 

func (w TerminalWriter) Read(p []byte) (int, error)

type WriteError 

type WriteError struct{ Err error }

WriteError identifies failures from the output sink, rather than from the iterator, transport, or formatter producing the output.

func (*WriteError) Error 

func (e *WriteError) Error() string

func (*WriteError) Unwrap 

func (e *WriteError) Unwrap() error

type Writer 

type Writer struct {
	Context context.Context
	Sink    io.Writer
}

Writer preserves cancellation separately from failures of the sink. Only actual sink errors may be treated as a closed output pipe by the pager. Context and Sink must be non-nil.

func (Writer) Write 

func (w Writer) Write(data []byte) (int, error)

func (Writer) WriteString 

func (w Writer) WriteString(data string) (int, error)

Source Files

View all Source files

Directories

Path Synopsis
Package listview provides lazy terminal list navigation and loaded-page rendering.
 Package listview provides lazy terminal list navigation and loaded-page rendering.
Package transform contains CLI-owned response transformations.
 Package transform contains CLI-owned response transformations.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.