progress

package
v1.16.5 Latest Latest
Warning

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

 Go to latest Published: Apr 10, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Event 

type Event struct {
	// Type is the event type discriminator.
	Type EventType `json:"type"`
	// At is the event timestamp.
	At time.Time `json:"at"`

	// IDs (stable).
	GroupID uint64 `json:"gid,omitempty"`
	TaskID  uint64 `json:"tid,omitempty"`

	// PrintLines payload.
	Lines []string `json:"lines,omitempty"`

	// Sync payload.
	SyncID uint64 `json:"sync_id,omitempty"`

	// Common "title" field (group/task add, group update).
	Title *string `json:"title,omitempty"`

	// Group options (group update).
	ShowMeta             *bool `json:"show_meta,omitempty"`
	HideDetailsOnSuccess *bool `json:"hide_details_on_success,omitempty"`
	SortTasksByTitle     *bool `json:"sort_tasks_by_title,omitempty"`
	// Group close.
	//
	// Finished=false means "seal snapshot": the group is moved from Active to
	// History immediately (used for interrupts). When omitted, it defaults to
	// true ("normal close").
	Finished *bool `json:"finished,omitempty"`

	// Task add.
	Pending bool `json:"pending,omitempty"`

	// Task update.
	Kind          *TaskKind `json:"kind,omitempty"`
	Meta          *string   `json:"meta,omitempty"`
	Message       *string   `json:"message,omitempty"`
	HideIfFast    *bool     `json:"hide_if_fast,omitempty"`
	RevealAfterMs *int64    `json:"reveal_after_ms,omitempty"`

	// Task progress.
	Current *int64 `json:"current,omitempty"`
	Total   *int64 `json:"total,omitempty"`

	// Task state transition.
	Status *TaskStatus `json:"status,omitempty"`
}

Event is the canonical, append-only input to the tuiv2 progress engine.

It is intentionally designed to be JSON-lines friendly.

Fields are mostly optional and interpreted based on Type.

func DecodeEvent 

func DecodeEvent(line []byte) (Event, error)

DecodeEvent decodes a single JSON event line.

type EventType 

type EventType string

EventType is the stable string representation of an event kind. 

const (
	// EventPrintLines prints one or more text lines as a single output block.
	//
	// A blank line can be represented as `EventPrintLines{Lines: []string{""}}`.
	EventPrintLines EventType = "print_lines"
	// EventSync is an internal barrier event.
	//
	// It is emitted by UI.Sync and allows callers to wait until all previously
	// emitted events are processed (and persisted to the event log when enabled).
	//
	// Renderers should ignore it.
	EventSync         EventType = "sync"
	EventGroupAdd     EventType = "group_add"
	EventGroupUpdate  EventType = "group_update"
	EventGroupClose   EventType = "group_close"
	EventTaskAdd      EventType = "task_add"
	EventTaskUpdate   EventType = "task_update"
	EventTaskProgress EventType = "task_progress"
	EventTaskState    EventType = "task_state"
)

Event types.

type Group 

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

Group groups a set of related tasks (usually one stage).

Group is a lightweight handle: it emits events into the UI engine. It is safe to use from any goroutine.

func (*Group) Close 

func (g *Group) Close()

Close marks the group as closed.

It is safe to call Close multiple times.

func (*Group) Seal 

func (g *Group) Seal()

Seal moves the group from the Active area to the immutable History area in ModeTTY by printing a snapshot of current state.

Seal is idempotent and has no effect in non-TTY modes.

func (*Group) SetHideDetailsOnSuccess 

func (g *Group) SetHideDetailsOnSuccess(hide bool)

SetHideDetailsOnSuccess configures whether per-task details should be hidden when the group is closed and all tasks succeed (TTY mode only).

func (*Group) SetShowMeta 

func (g *Group) SetShowMeta(show bool)

SetShowMeta configures whether the group header should include elapsed timing information (TTY mode only).

func (*Group) SetSortTasksByTitle 

func (g *Group) SetSortTasksByTitle(sort bool)

SetSortTasksByTitle configures whether tasks should be shown in a stable title-sorted order in the TTY Active area.

func (*Group) SetTitle 

func (g *Group) SetTitle(title string)

SetTitle updates the group title.

It is safe to call multiple times. It has no effect after the UI is closed.

func (*Group) Task 

func (g *Group) Task(title string) *Task

Task creates a new running task under this group.

func (*Group) TaskPending 

func (g *Group) TaskPending(title string) *Task

TaskPending creates a new task under this group in a "pending" state.

type Mode 

type Mode int

Mode decides how the progress UI renders.

- ModeAuto: choose ModeTTY when output is a TTY, otherwise ModePlain. - ModeTTY: dynamic multi-line progress display (ANSI). - ModePlain: stable event logs, no ANSI overwrite. - ModeOff: no progress output. 

const (
	// ModeAuto chooses ModeTTY when output is a TTY, otherwise ModePlain.
	ModeAuto Mode = iota
	// ModeTTY uses a dynamic multi-line progress display (ANSI).
	ModeTTY
	// ModePlain uses stable event logs with no ANSI overwrite.
	ModePlain
	// ModeOff disables progress output.
	ModeOff
)

func (Mode) String 

func (m Mode) String() string

type Options 

type Options struct {
	// Mode decides how the progress UI renders.
	Mode Mode
	// Out is the output writer used by the UI.
	//
	// If nil, it defaults to os.Stderr.
	//
	// ModeAuto and ModeTTY rely on TTY detection. Only *os.File writers can be
	// detected as TTY; other writers will be treated as non-TTY and fall back to
	// plain output.
	Out io.Writer

	// EventLog is an optional JSON-lines sink of the event stream.
	//
	// It is primarily intended for daemon mode: the daemon process writes event
	// logs to a file, and the starter process replays them in a real TTY.
	EventLog io.Writer

	// Now returns the current time.
	// If nil, it defaults to time.Now.
	//
	// It exists to make tests deterministic.
	Now func() time.Time
}

Options controls how the progress UI behaves.

type Task 

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

Task represents one line item in a group.

Task is a lightweight handle: it emits events into the UI engine. It is safe to use from any goroutine.

func (*Task) Cancel 

func (t *Task) Cancel(reason string)

Cancel marks the task as canceled with an optional reason.

func (*Task) Done 

func (t *Task) Done()

Done marks the task as successfully completed.

func (*Task) Error 

func (t *Task) Error(msg string)

Error marks the task as failed with a message.

func (*Task) Retrying 

func (t *Task) Retrying(msg string)

Retrying marks the task as retrying with a message, while keeping it active.

func (*Task) SetCurrent 

func (t *Task) SetCurrent(current int64)

SetCurrent sets the progress current value for this task.

func (*Task) SetHideIfFast 

func (t *Task) SetHideIfFast(revealAfter time.Duration)

SetHideIfFast configures this task to be hidden in TTY mode unless it runs for at least revealAfter, or errors.

func (*Task) SetKindDownload 

func (t *Task) SetKindDownload()

SetKindDownload marks this task as a download task.

func (*Task) SetMessage 

func (t *Task) SetMessage(msg string)

SetMessage sets a human-readable message for this task.

func (*Task) SetMeta 

func (t *Task) SetMeta(meta string)

SetMeta sets stable, user-facing metadata for this task (e.g. component version for downloads).

func (*Task) SetTotal 

func (t *Task) SetTotal(total int64)

SetTotal sets the progress total for this task.

func (*Task) Skip 

func (t *Task) Skip(reason string)

Skip marks the task as skipped with an optional reason.

func (*Task) Start 

func (t *Task) Start()

Start marks the task as running. It is safe to call Start multiple times.

type TaskKind 

type TaskKind string

TaskKind is the stable string representation of a task kind. 

const (
	TaskKindGeneric  TaskKind = "generic"
	TaskKindDownload TaskKind = "download"
)

Task kinds.

type TaskStatus 

type TaskStatus string

TaskStatus is the stable string representation of a task status. 

const (
	TaskStatusPending  TaskStatus = "pending"
	TaskStatusRunning  TaskStatus = "running"
	TaskStatusRetrying TaskStatus = "retrying"
	TaskStatusDone     TaskStatus = "done"
	TaskStatusError    TaskStatus = "error"
	TaskStatusSkipped  TaskStatus = "skipped"
	TaskStatusCanceled TaskStatus = "canceled"
)

Task statuses.

type UI 

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

UI is a unified progress display for both TTY users and non-TTY logs/CI.

Create a UI via New, then create Group/Task objects and update them from any goroutine. Call Close when the program exits.

func New 

func New(opts Options) *UI

New creates a new progress UI.

func (*UI) Close 

func (ui *UI) Close() error

Close stops the UI and releases any internal resources.

func (*UI) Group 

func (ui *UI) Group(title string) *Group

Group creates a new group of tasks (usually a "stage") under this UI.

func (*UI) Mode 

func (ui *UI) Mode() Mode

Mode returns the resolved mode used by this UI.

It may differ from Options.Mode when Options.Mode is ModeAuto (or when terminal capability checks force a downgrade to ModePlain).

func (*UI) PrintLines 

func (ui *UI) PrintLines(lines []string)

PrintLines prints one or more text lines as a single output block.

It flushes any pending partial line from UI.Writer() first, then appends an output block.

func (*UI) ReplayEvent 

func (ui *UI) ReplayEvent(e Event)

ReplayEvent injects a single Event into this UI.

It is intended for daemon mode starter processes that tail an event log file.

func (*UI) Sync 

func (ui *UI) Sync()

Sync blocks until all previously emitted events are processed by the UI engine.

It is primarily intended for daemon mode: callers may use it to ensure output is fully persisted to the event log before exposing readiness signals (e.g. creating the HTTP command server port file).

func (*UI) Writer 

func (ui *UI) Writer() io.Writer

Writer returns a writer that is safe to use together with the progress UI.

In ModeTTY, it appends complete lines to the History area (above the Active area), so they remain in the terminal scrollback and don't corrupt multi-line progress rendering.

In ModePlain and ModeOff, it still emits line-based events so daemon mode can persist and replay output.

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.