output

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Apr 30, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrOutputConflict = errors.New("cannot combine --json and --plain")

Functions

func CountPayload 

func CountPayload(count int) map[string]any

CountPayload creates a count result object.

func Detail added in v0.1.5 

func Detail(ctx context.Context, jsonData any, plainValues []any, fields []Field) error

Detail writes a single resource across all three output modes. JSON mode writes jsonData, Plain mode writes plainValues as TSV, and Human mode renders fields as aligned key-value pairs.

func ErrorPayload 

func ErrorPayload(err error) map[string]any

ErrorPayload creates an error status object.

func Fprintf added in v0.1.5 

func Fprintf(ctx context.Context, format string, args ...any) (int, error)

Fprintf writes formatted text to the context Writer's stdout.

func Fprintln added in v0.1.5 

func Fprintln(ctx context.Context, args ...any) (int, error)

Fprintln writes a line to the context Writer's stdout.

func IDPayload 

func IDPayload(id string) map[string]any

IDPayload creates an ID result object.

func IsHuman 

func IsHuman(ctx context.Context) bool

IsHuman returns true if human-readable output is enabled (neither JSON nor plain).

func IsJSON 

func IsJSON(ctx context.Context) bool

IsJSON returns true if JSON output is enabled.

func IsPlain 

func IsPlain(ctx context.Context) bool

IsPlain returns true if plain/TSV output is enabled.

func JSON 

func JSON(ctx context.Context, v any) error

JSON writes v as JSON to the context's writer.

func JSONErr 

func JSONErr(ctx context.Context, v any) error

JSONErr writes v as JSON to stderr.

func PathPayload 

func PathPayload(path string) map[string]any

PathPayload creates a path result object.

func Plain 

func Plain(ctx context.Context, values ...any) error

Plain writes values as tab-separated text to the writer.

func PlainFromSlice 

func PlainFromSlice(ctx context.Context, slice any, fields []string) error

PlainFromSlice writes each struct in a slice as a TSV row.

func PlainFromStruct 

func PlainFromStruct(ctx context.Context, v any, fields []string) error

PlainFromStruct extracts specified fields from a struct and writes as TSV.

func PlainRows 

func PlainRows(ctx context.Context, rows [][]any) error

PlainRows writes multiple rows as TSV.

func Print 

func Print(ctx context.Context, jsonData any, plainValues []any, humanFn func() error) error

Print writes to stdout based on output mode.

func PrintSlice 

func PrintSlice(ctx context.Context, slice any, fields []string, headers []string) error

PrintSlice writes a slice based on output mode.

func StatusPayload 

func StatusPayload(status string, message string) map[string]any

StatusPayload creates a simple status object for JSON output.

func SuccessPayload 

func SuccessPayload(message string) map[string]any

SuccessPayload creates a success status object.

func WithMode 

func WithMode(ctx context.Context, mode Mode) context.Context

WithMode adds output mode to context.

func WithProgress 

func WithProgress(ctx context.Context, p *Progress) context.Context

WithProgress stores a progress session in context.

func WithSyncTimeline added in v0.1.3 

func WithSyncTimeline(ctx context.Context, tl *SyncTimeline) context.Context

WithSyncTimeline stores a SyncTimeline in context.

func WithWriter 

func WithWriter(ctx context.Context, w *Writer) context.Context

WithWriter adds writer to context.

func WriteDetail added in v0.1.5 

func WriteDetail(w io.Writer, fields []Field) error

WriteDetail writes fields as aligned "Label: Value" pairs. Fields created with F() are skipped when their value is the zero value.

func WriteJSON 

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

WriteJSON writes v as indented JSON to the writer.

func WritePlain 

func WritePlain(w io.Writer, values ...any) error

WritePlain writes values as tab-separated line.

func WriteTable 

func WriteTable(ctx context.Context, slice any, fields []string, headers []string) error

WriteTable writes a slice of structs as a table.

Types

type CopyTimeline 

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

CopyTimeline renders a rolling timeline of copy stages to stderr. It satisfies migrate.CopyObserver via structural typing.

func NewCopyTimeline 

func NewCopyTimeline(ctx context.Context, dryRun bool) *CopyTimeline

NewCopyTimeline creates a timeline renderer. Call Close() when done.

func (*CopyTimeline) Close 

func (tl *CopyTimeline) Close()

Close stops the spinner goroutine and clears the active stage display. Does NOT render the footer — call Footer() first if the operation succeeded. Idempotent: safe to call multiple times.

func (*CopyTimeline) ErrorFooter 

func (tl *CopyTimeline) ErrorFooter(msg string)

ErrorFooter renders a closing error line (└ Error! <msg>). Clears the active spinner, stops the animation loop, and marks closed. Idempotent: second call is a no-op.

func (*CopyTimeline) Footer 

func (tl *CopyTimeline) Footer()

Footer renders the closing summary line (└ Done! Done in Xs). Call this only on success — omit on error so the footer doesn't mislead. Idempotent: second call is a no-op.

func (*CopyTimeline) Header 

func (tl *CopyTimeline) Header(from, to string)

Header prints the opening line of the timeline.

func (*CopyTimeline) PreparePrompt added in v0.1.13 

func (tl *CopyTimeline) PreparePrompt()

PreparePrompt clears live spinner output before a blocking prompt is printed.

func (*CopyTimeline) StageDone 

func (tl *CopyTimeline) StageDone(name, summary string)

StageDone finalizes a stage with a summary.

func (*CopyTimeline) StageItem 

func (tl *CopyTimeline) StageItem(name, detail string, current, total int64)

StageItem updates the active stage's sub-detail.

func (*CopyTimeline) StageSkip 

func (tl *CopyTimeline) StageSkip(name, reason string)

StageSkip marks a stage as skipped with a reason.

func (*CopyTimeline) StageStart 

func (tl *CopyTimeline) StageStart(name string)

StageStart begins a new active stage with a spinner.

func (*CopyTimeline) StageWarning added in v0.1.13 

func (tl *CopyTimeline) StageWarning(stage, msg string)

StageWarning records or prints a warning owned by one timeline stage.

func (*CopyTimeline) SubStageDone 

func (tl *CopyTimeline) SubStageDone(stage, sub, summary string)

SubStageDone records a completed sub-item within the active stage.

type Field added in v0.1.5 

type Field struct {
	Label string
	Value any
	// contains filtered or unexported fields
}

Field represents one row in a detail view.

func F added in v0.1.5 

func F(label string, value any) Field

F creates a Field that is skipped when the value is the zero value for its type.

func FAlways added in v0.1.5 

func FAlways(label string, value any) Field

FAlways creates a Field that is always displayed, even when zero.

type Mode 

type Mode struct {
	JSON  bool
	Plain bool
}

Mode represents the output format mode.

func FromContext 

func FromContext(ctx context.Context) Mode

FromContext extracts output mode from context.

func FromEnv 

func FromEnv() Mode

FromEnv creates a Mode from environment variables.

func FromFlags 

func FromFlags(jsonOut, plainOut bool) (Mode, error)

FromFlags creates a Mode from CLI flags.

type ParseError 

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

ParseError indicates invalid output mode configuration.

func (*ParseError) Error 

func (e *ParseError) Error() string

type Progress 

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

Progress renders lightweight human-only progress feedback on stderr.

func NewDisabledProgress 

func NewDisabledProgress() *Progress

NewDisabledProgress returns a no-op progress that silently discards all output. Use when a timeline renderer handles progress display instead.

func NewProgress 

func NewProgress(ctx context.Context) *Progress

NewProgress builds a human-mode stderr progress session for the current context.

func ProgressFromContext 

func ProgressFromContext(ctx context.Context) *Progress

ProgressFromContext extracts the progress session from context.

func (*Progress) Close 

func (p *Progress) Close()

Close stops background rendering and leaves stderr clean.

func (*Progress) Counter 

func (p *Progress) Counter(label string, total int64) *Task

Counter starts an item counter task.

func (*Progress) Phase 

func (p *Progress) Phase(label string) *Task

Phase starts a spinner task.

func (*Progress) Transfer 

func (p *Progress) Transfer(label string, total int64) *Task

Transfer starts a byte-progress task.

type SyncCategory added in v0.1.3 

type SyncCategory struct {
	Label string
	Count int
}

SyncCategory describes one category for the timeline.

type SyncTimeline added in v0.1.3 

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

SyncTimeline renders category-grouped progress for theme push/sync.

func NewSyncTimeline added in v0.1.3 

func NewSyncTimeline(ctx context.Context, mode, theme string, dryRun bool) *SyncTimeline

NewSyncTimeline creates a timeline renderer for theme push/sync.

func SyncTimelineFromContext added in v0.1.3 

func SyncTimelineFromContext(ctx context.Context) *SyncTimeline

SyncTimelineFromContext retrieves the SyncTimeline from context, or nil.

func (*SyncTimeline) CategoryDone added in v0.1.3 

func (tl *SyncTimeline) CategoryDone(index int)

CategoryDone finalizes a category, writing a permanent completion line.

func (*SyncTimeline) Close added in v0.1.3 

func (tl *SyncTimeline) Close()

Close stops the animation goroutine and clears the active display. Idempotent.

func (*SyncTimeline) DeleteFailed added in v0.1.3 

func (tl *SyncTimeline) DeleteFailed(displayPath, errorDetail string)

DeleteFailed records a delete failure.

func (*SyncTimeline) DeletesDone added in v0.1.3 

func (tl *SyncTimeline) DeletesDone()

DeletesDone finalizes the delete phase with a permanent completion line.

func (*SyncTimeline) ErrorFooter added in v0.1.3 

func (tl *SyncTimeline) ErrorFooter()

ErrorFooter renders a closing error summary line. Idempotent.

func (*SyncTimeline) FileDeleted added in v0.1.3 

func (tl *SyncTimeline) FileDeleted()

FileDeleted records a successful delete.

func (*SyncTimeline) FileFailed added in v0.1.3 

func (tl *SyncTimeline) FileFailed(displayPath, errorDetail string)

FileFailed records an upload failure. errorDetail is a pre-formatted string.

func (*SyncTimeline) FileSkipped added in v0.1.9 

func (tl *SyncTimeline) FileSkipped()

FileSkipped records an intentionally skipped upload after user confirmation.

func (*SyncTimeline) FileUploaded added in v0.1.3 

func (tl *SyncTimeline) FileUploaded()

FileUploaded records a successful upload and increments the category counter.

func (*SyncTimeline) Footer added in v0.1.3 

func (tl *SyncTimeline) Footer()

Footer renders the closing success summary line. Idempotent.

func (*SyncTimeline) Header added in v0.1.3 

func (tl *SyncTimeline) Header()

Header prints the opening line and starts the animation loop.

func (*SyncTimeline) NothingToDo added in v0.1.3 

func (tl *SyncTimeline) NothingToDo()

NothingToDo renders a message when there are no files to process.

func (*SyncTimeline) PreparePrompt added in v0.1.9 

func (tl *SyncTimeline) PreparePrompt()

PreparePrompt clears live spinner output before a blocking prompt is printed.

func (*SyncTimeline) RenderPlan added in v0.1.3 

func (tl *SyncTimeline) RenderPlan(categories []SyncCategory, deleteCount int)

RenderPlan displays the dry-run plan without executing uploads.

func (*SyncTimeline) SetActiveDelete added in v0.1.3 

func (tl *SyncTimeline) SetActiveDelete(displayPath string)

SetActiveDelete updates the spinner to show the file being deleted.

func (*SyncTimeline) SetActiveFile added in v0.1.3 

func (tl *SyncTimeline) SetActiveFile(displayPath string)

SetActiveFile updates the spinner to show the file currently being uploaded.

func (*SyncTimeline) SetCategories added in v0.1.3 

func (tl *SyncTimeline) SetCategories(categories []SyncCategory)

SetCategories initializes the category list and computes label alignment.

func (*SyncTimeline) StartCategory added in v0.1.3 

func (tl *SyncTimeline) StartCategory(index int)

StartCategory begins a new active category with a spinner.

func (*SyncTimeline) StartDeletes added in v0.1.3 

func (tl *SyncTimeline) StartDeletes(total int)

StartDeletes begins the delete phase with a spinner.

type Table 

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

Table represents a simple table for human-readable output.

func NewTable 

func NewTable(out io.Writer, headers ...string) *Table

NewTable creates a new table writer.

func (*Table) Flush 

func (t *Table) Flush() error

Flush writes the table to the underlying writer.

func (*Table) Row 

func (t *Table) Row(values ...any)

Row adds a row to the table.

type Task 

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

Task represents one in-flight spinner, counter, or transfer.

func (*Task) Add 

func (t *Task) Add(n int64)

Add advances the task by n units/bytes.

func (*Task) Current 

func (t *Task) Current() int64

Current returns the current progress amount.

func (*Task) Done 

func (t *Task) Done(status string)

Done finalizes the task with an optional status label.

func (*Task) Fail 

func (t *Task) Fail(err error)

Fail finalizes the task as failed.

func (*Task) ResetProgress 

func (t *Task) ResetProgress()

ResetProgress resets current progress and elapsed timing for a retry/replay attempt.

func (*Task) SetLabel 

func (t *Task) SetLabel(label string)

SetLabel updates the task label.

func (*Task) SetTotal 

func (t *Task) SetTotal(total int64)

SetTotal updates the known total.

func (*Task) WrapReadCloser 

func (t *Task) WrapReadCloser(reader io.ReadCloser) io.ReadCloser

WrapReadCloser increments the task as data is read and preserves Close.

func (*Task) WrapReader 

func (t *Task) WrapReader(reader io.Reader) io.Reader

WrapReader increments the task as data is read.

func (*Task) WrapWriter 

func (t *Task) WrapWriter(writer io.Writer) io.Writer

WrapWriter increments the task as data is written.

type Writer 

type Writer struct {
	Out    io.Writer
	Err    io.Writer
	Mode   Mode
	NoTTY  bool
	Color  string // "auto", "always", "never"
	NoSpin bool   // Disable spinner
}

Writer holds output configuration.

func DefaultWriter 

func DefaultWriter() *Writer

DefaultWriter returns a writer with default settings.

func WriterFromContext 

func WriterFromContext(ctx context.Context) *Writer

WriterFromContext extracts writer from context.

func (*Writer) ErrIsTTY 

func (w *Writer) ErrIsTTY() bool

ErrIsTTY returns true if stderr is a terminal.

func (*Writer) IsTTY 

func (w *Writer) IsTTY() bool

IsTTY returns true if stdout is a terminal.

func (*Writer) UseColor 

func (w *Writer) UseColor() bool

UseColor returns true if color output should be used.

Source Files

View all Source files

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.