Documentation
¶
Overview ¶
Package progress provides terminal progress bars with multiple tasks and customizable columns.
Index ¶
- Variables
- func DefaultBarStyles() (back, complete, finished, pulse *style.Style)
- func Track[T any](items []T, description string, opts ...Option) func(func(T) bool)
- func WithAutoWidth() func(*TextColumn)
- func WithBarWidth(width int) func(*BarColumn)
- func WithFinishedText(text string) func(*SpinnerColumn)
- func WithJustify(j console.Justify) func(*TextColumn)
- func WithMarkup(enabled bool) func(*TextColumn)
- func WithSpinnerName(name string) func(*SpinnerColumn)
- func WithSpinnerStyle(s style.Style) func(*SpinnerColumn)
- func WithTextStyle(s style.Style) func(*TextColumn)
- func WithWidth(w int) func(*TextColumn)
- type BarColumn
- type Column
- type DownloadColumn
- type FileSizeColumn
- type MofNCompleteColumn
- type Option
- type Progress
- func (p *Progress) AddSection(opts ...SectionOption) *Section
- func (p *Progress) AddTask(description string, total *float64, opts ...TaskOption) TaskID
- func (p *Progress) Advance(taskID TaskID, amount float64)
- func (p *Progress) Copy(dst io.Writer, src io.Reader, total int64, description string) (int64, error)
- func (p *Progress) CopyBuffer(dst io.Writer, src io.Reader, buf []byte, total int64, description string) (int64, error)
- func (p *Progress) Done(taskID TaskID, description ...string)
- func (p *Progress) Finished() bool
- func (p *Progress) Refresh()
- func (p *Progress) RemoveTask(taskID TaskID)
- func (p *Progress) ResetTask(taskID TaskID, start bool)
- func (p *Progress) Start(ctx context.Context)
- func (p *Progress) StartTask(taskID TaskID)
- func (p *Progress) Stop()
- func (p *Progress) StopTask(taskID TaskID)
- func (p *Progress) String() string
- func (p *Progress) Update(taskID TaskID, cfg TaskUpdateConfig)
- func (p *Progress) WrapFile(path string, description string) (*Reader, TaskID, error)
- func (p *Progress) WrapReadCloser(rc io.ReadCloser, total int64, description string) (*ReadCloser, TaskID)
- func (p *Progress) WrapReader(r io.Reader, total int64, description string) (*Reader, TaskID)
- func (p *Progress) WrapWriter(w io.Writer, total int64, description string) (*Writer, TaskID)
- type ProgressBar
- type ReadCloser
- type Reader
- type RenderableColumn
- type Section
- type SectionOption
- type SeparatorColumn
- type SpinnerColumn
- type Task
- type TaskConfig
- type TaskID
- type TaskOption
- type TaskProgressColumn
- type TaskSnapshot
- type TaskUpdateConfig
- type TextColumn
- type TimeElapsedColumn
- type TimeRemainingColumn
- type TotalFileSizeColumn
- type TransferSpeedColumn
- type Writer
Constants ¶
This section is empty.
Variables ¶
var ErrNotSeekable = errors.New("reader does not support seeking")
ErrNotSeekable is returned when Seek is called on a reader that doesn't support seeking.
Functions ¶
func DefaultBarStyles ¶
DefaultBarStyles returns the default styles for a progress bar.
func WithAutoWidth ¶ added in v1.0.5
func WithAutoWidth() func(*TextColumn)
WithAutoWidth sizes the column to the widest value among the tasks in the same section, recomputed on each render. This keeps following columns (e.g. the bar) aligned without hardcoding a width.
func WithFinishedText ¶
func WithFinishedText(text string) func(*SpinnerColumn)
WithFinishedText sets the text shown when task is finished.
func WithJustify ¶
func WithJustify(j console.Justify) func(*TextColumn)
WithJustify sets the text justification.
func WithMarkup ¶
func WithMarkup(enabled bool) func(*TextColumn)
WithMarkup enables or disables markup parsing (default: true).
func WithSpinnerName ¶
func WithSpinnerName(name string) func(*SpinnerColumn)
WithSpinnerName sets the spinner name.
func WithSpinnerStyle ¶
func WithSpinnerStyle(s style.Style) func(*SpinnerColumn)
WithSpinnerStyle sets the spinner style.
func WithTextStyle ¶
func WithTextStyle(s style.Style) func(*TextColumn)
WithTextStyle sets the text style.
func WithWidth ¶
func WithWidth(w int) func(*TextColumn)
WithWidth sets the minimum width for padding. This disables auto-width.
Types ¶
type BarColumn ¶
type BarColumn struct {
BarWidth *int
Style *style.Style
CompleteStyle *style.Style
FinishedStyle *style.Style
PulseStyle *style.Style
// contains filtered or unexported fields
}
BarColumn displays the progress bar.
func NewBarColumn ¶
NewBarColumn creates a new bar column.
func (*BarColumn) MaxRefresh ¶
MaxRefresh implements Column.
type Column ¶
type Column interface {
// Render renders the column for the given task.
Render(task TaskSnapshot, c *console.Console, opts console.Options) []segment.Segment
// MaxRefresh returns the minimum interval between re-renders, or 0 for no throttle.
MaxRefresh() time.Duration
}
Column is the interface for progress bar columns.
func DefaultColumns ¶
func DefaultColumns() []Column
DefaultColumns returns the default set of columns.
type DownloadColumn ¶
type DownloadColumn struct {
BinaryUnits bool // Use KiB/MiB/GiB instead of KB/MB/GB
Style *style.Style
// contains filtered or unexported fields
}
DownloadColumn displays download progress in bytes.
func NewDownloadColumn ¶
func NewDownloadColumn(binaryUnits bool) *DownloadColumn
NewDownloadColumn creates a new download column.
func (*DownloadColumn) MaxRefresh ¶
func (dc *DownloadColumn) MaxRefresh() time.Duration
MaxRefresh implements Column.
func (*DownloadColumn) Render ¶
func (dc *DownloadColumn) Render(task TaskSnapshot, c *console.Console, opts console.Options) []segment.Segment
Render implements Column.
type FileSizeColumn ¶
type FileSizeColumn struct {
BinaryUnits bool
Style *style.Style
// contains filtered or unexported fields
}
FileSizeColumn displays the completed amount as a file size.
func NewFileSizeColumn ¶
func NewFileSizeColumn(binaryUnits bool) *FileSizeColumn
NewFileSizeColumn creates a new file size column.
func (*FileSizeColumn) MaxRefresh ¶
func (fsc *FileSizeColumn) MaxRefresh() time.Duration
MaxRefresh implements Column.
func (*FileSizeColumn) Render ¶
func (fsc *FileSizeColumn) Render(task TaskSnapshot, c *console.Console, opts console.Options) []segment.Segment
Render implements Column.
type MofNCompleteColumn ¶
type MofNCompleteColumn struct {
Separator string
Style *style.Style
// contains filtered or unexported fields
}
MofNCompleteColumn displays "M/N" progress.
func NewMofNCompleteColumn ¶
func NewMofNCompleteColumn(separator string) *MofNCompleteColumn
NewMofNCompleteColumn creates a new M/N column.
func (*MofNCompleteColumn) MaxRefresh ¶
func (mc *MofNCompleteColumn) MaxRefresh() time.Duration
MaxRefresh implements Column.
func (*MofNCompleteColumn) Render ¶
func (mc *MofNCompleteColumn) Render(task TaskSnapshot, c *console.Console, opts console.Options) []segment.Segment
Render implements Column.
type Option ¶
type Option func(*Progress)
Option configures a Progress.
func WithColumns ¶
WithColumns sets the columns for the default section (section 0).
func WithDisable ¶
WithDisable disables all output (useful for CI).
func WithExpand ¶
WithExpand expands the display to fill terminal width.
func WithRefreshRate ¶
WithRefreshRate sets the refresh rate in Hz (default 10).
func WithSpeedEstimatePeriod ¶
WithSpeedEstimatePeriod sets the window for speed estimation (default 30s).
func WithTransient ¶
WithTransient clears the progress display when stopped.
type Progress ¶
type Progress struct {
// contains filtered or unexported fields
}
Progress manages multiple progress tasks.
func (*Progress) AddSection ¶ added in v1.0.5
func (p *Progress) AddSection(opts ...SectionOption) *Section
AddSection adds a new section with the given options and returns it. Sections render in the order they are added. The default section (section 0) is created implicitly by New.
func (*Progress) AddTask ¶
func (p *Progress) AddTask(description string, total *float64, opts ...TaskOption) TaskID
AddTask adds a new task to the default section and returns its ID.
func (*Progress) Copy ¶
func (p *Progress) Copy(dst io.Writer, src io.Reader, total int64, description string) (int64, error)
Copy copies from src to dst while tracking progress. Returns the number of bytes copied and any error.
func (*Progress) CopyBuffer ¶
func (p *Progress) CopyBuffer(dst io.Writer, src io.Reader, buf []byte, total int64, description string) (int64, error)
CopyBuffer copies from src to dst using the provided buffer while tracking progress.
func (*Progress) Done ¶ added in v1.0.3
Done marks a task as finished, regardless of its current progress. This is useful for indeterminate tasks (total=nil) that need to be explicitly marked complete, e.g. after an API call returns. An optional description can be passed to update the display text.
func (*Progress) RemoveTask ¶
RemoveTask removes a task from the display.
func (*Progress) Update ¶
func (p *Progress) Update(taskID TaskID, cfg TaskUpdateConfig)
Update updates a task's state.
func (*Progress) WrapFile ¶
WrapFile opens a file and wraps it with progress tracking. Returns the wrapped reader, task ID, and any error.
func (*Progress) WrapReadCloser ¶
func (p *Progress) WrapReadCloser(rc io.ReadCloser, total int64, description string) (*ReadCloser, TaskID)
WrapReadCloser wraps an io.ReadCloser with progress tracking.
func (*Progress) WrapReader ¶
WrapReader wraps an io.Reader with progress tracking. Returns the wrapped reader and a function to stop tracking.
type ProgressBar ¶
type ProgressBar struct {
Total *float64
Completed float64
Width *int // nil = auto width
Pulse bool // Force pulse animation
AnimationTime float64 // Time for animation (used for pulse offset)
ASCIIOnly bool
Finished bool // Task is finished (use finished style)
BackStyle *style.Style
CompleteStyle *style.Style
FinishedStyle *style.Style
PulseStyle *style.Style
}
ProgressBar renders a single progress bar.
func (*ProgressBar) Measure ¶
func (pb *ProgressBar) Measure(c *console.Console, opts console.Options) console.Measurement
Measure implements console.Measurable.
type ReadCloser ¶
type ReadCloser struct {
*Reader
// contains filtered or unexported fields
}
ReadCloser wraps an io.ReadCloser with progress tracking.
func NewReadCloser ¶
func NewReadCloser(rc io.ReadCloser, p *Progress, taskID TaskID) *ReadCloser
NewReadCloser creates a progress-tracking ReadCloser.
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader wraps an io.Reader to track progress.
type RenderableColumn ¶
type RenderableColumn struct {
Renderable console.Renderable
// contains filtered or unexported fields
}
RenderableColumn displays a static renderable.
func NewRenderableColumn ¶
func NewRenderableColumn(r console.Renderable) *RenderableColumn
NewRenderableColumn creates a new renderable column.
func (*RenderableColumn) MaxRefresh ¶
func (rc *RenderableColumn) MaxRefresh() time.Duration
MaxRefresh implements Column.
func (*RenderableColumn) Render ¶
func (rc *RenderableColumn) Render(task TaskSnapshot, c *console.Console, opts console.Options) []segment.Segment
Render implements Column.
type Section ¶ added in v1.0.5
type Section struct {
// contains filtered or unexported fields
}
Section is a group of tasks rendered together with a shared column layout and optional indentation. Sections render top-to-bottom in the order they are added.
type SectionOption ¶ added in v1.0.5
type SectionOption func(*Section)
SectionOption configures a Section.
func WithSectionColumns ¶ added in v1.0.5
func WithSectionColumns(cols ...Column) SectionOption
WithSectionColumns sets the columns for this section.
func WithSectionIndent ¶ added in v1.0.5
func WithSectionIndent(n int) SectionOption
WithSectionIndent sets the number of leading space characters prepended to each task line in this section. Default is 0 (flush left).
type SeparatorColumn ¶
SeparatorColumn displays a static separator string.
func NewSeparatorColumn ¶
func NewSeparatorColumn(text string) *SeparatorColumn
NewSeparatorColumn creates a separator column.
func (*SeparatorColumn) MaxRefresh ¶
func (sc *SeparatorColumn) MaxRefresh() time.Duration
MaxRefresh implements Column.
func (*SeparatorColumn) Render ¶
func (sc *SeparatorColumn) Render(task TaskSnapshot, c *console.Console, opts console.Options) []segment.Segment
Render implements Column.
type SpinnerColumn ¶
type SpinnerColumn struct {
SpinnerName string
Style *style.Style
FinishedText string
FinishedStyle *style.Style
Speed float64
// contains filtered or unexported fields
}
SpinnerColumn displays an animated spinner.
func NewSpinnerColumn ¶
func NewSpinnerColumn(opts ...func(*SpinnerColumn)) *SpinnerColumn
NewSpinnerColumn creates a new spinner column.
func (*SpinnerColumn) Cleanup ¶ added in v1.0.4
func (sc *SpinnerColumn) Cleanup(id TaskID)
Cleanup removes per-task state for the given task ID.
func (*SpinnerColumn) MaxRefresh ¶
func (sc *SpinnerColumn) MaxRefresh() time.Duration
MaxRefresh implements Column.
func (*SpinnerColumn) Render ¶
func (sc *SpinnerColumn) Render(task TaskSnapshot, c *console.Console, opts console.Options) []segment.Segment
Render implements Column.
func (*SpinnerColumn) SetTaskSpinner ¶
func (sc *SpinnerColumn) SetTaskSpinner(id TaskID, name string)
SetTaskSpinner assigns a specific spinner name to a task, overriding the column default. Must be called before the task's first render.
type Task ¶
type Task struct {
// contains filtered or unexported fields
}
Task represents a single progress task.
func NewTask ¶
func NewTask(id TaskID, cfg TaskConfig, getTime func() float64, speedPeriod float64) *Task
NewTask creates a new task.
func (*Task) Done ¶ added in v1.0.3
Done marks the task as finished, regardless of current progress. If the task has a known total and hasn't reached it, completed is set to total. An optional description can be passed to update the display text.
func (*Task) Snapshot ¶
func (t *Task) Snapshot() TaskSnapshot
Snapshot returns a read-only copy of the task state.
type TaskConfig ¶
type TaskConfig struct {
Description string
Total *float64
Completed float64
Visible bool
Start bool
Fields map[string]any
}
TaskConfig holds configuration for creating a task.
type TaskOption ¶
type TaskOption func(*TaskConfig)
TaskOption configures task creation.
func TaskWithCompleted ¶
func TaskWithCompleted(completed float64) TaskOption
TaskWithCompleted sets the initial completed count.
func TaskWithFields ¶
func TaskWithFields(fields map[string]any) TaskOption
TaskWithFields sets custom fields.
func TaskWithStart ¶
func TaskWithStart(start bool) TaskOption
TaskWithStart sets whether to start timing immediately.
func TaskWithVisible ¶
func TaskWithVisible(visible bool) TaskOption
TaskWithVisible sets task visibility.
type TaskProgressColumn ¶
type TaskProgressColumn struct {
ShowSpeed bool // Show speed when total is unknown
Style *style.Style
// contains filtered or unexported fields
}
TaskProgressColumn displays the progress percentage or speed.
func NewTaskProgressColumn ¶
func NewTaskProgressColumn(showSpeed bool) *TaskProgressColumn
NewTaskProgressColumn creates a new task progress column.
func (*TaskProgressColumn) MaxRefresh ¶
func (tpc *TaskProgressColumn) MaxRefresh() time.Duration
MaxRefresh implements Column.
func (*TaskProgressColumn) Render ¶
func (tpc *TaskProgressColumn) Render(task TaskSnapshot, c *console.Console, opts console.Options) []segment.Segment
Render implements Column.
type TaskSnapshot ¶
type TaskSnapshot struct {
ID TaskID
Description string
Total *float64
Completed float64
Elapsed *float64
TimeRemaining *float64
Percentage float64
Speed *float64
FinishedSpeed *float64
FinishedTime *float64
Started bool
Finished bool
Visible bool
Fields map[string]any
CurrentTime float64
}
TaskSnapshot is a read-only copy of task state for rendering.
func (TaskSnapshot) GetSpeed ¶
func (s TaskSnapshot) GetSpeed() *float64
GetSpeed returns the current or finished speed.
func (TaskSnapshot) Remaining ¶
func (s TaskSnapshot) Remaining() *float64
Remaining returns the remaining steps, or nil if total is unknown.
type TaskUpdateConfig ¶
type TaskUpdateConfig struct {
Description *string
Total *float64
Completed *float64
Advance *float64
Visible *bool
Fields map[string]any
}
TaskUpdateConfig holds optional fields for updating a task.
type TextColumn ¶
type TextColumn struct {
Text string // Text to display (can use {task.description}, etc.)
Style *style.Style
Justify console.Justify
Width int // Minimum width (0 = no padding)
AutoWidth bool // Size Width to the widest value in the section (recomputed each frame)
NoWrap bool
Markup bool // Enable markup parsing (default true)
// contains filtered or unexported fields
}
TextColumn displays text with optional formatting.
func DescriptionColumn ¶
func DescriptionColumn(opts ...func(*TextColumn)) *TextColumn
DescriptionColumn creates a column that displays the task description. This is a convenience wrapper around TextColumn with sensible defaults. Supports markup syntax like "[bold red]Downloading[/]" in task descriptions.
func NewTextColumn ¶
func NewTextColumn(text string, opts ...func(*TextColumn)) *TextColumn
NewTextColumn creates a new text column.
func (*TextColumn) MaxRefresh ¶
func (tc *TextColumn) MaxRefresh() time.Duration
MaxRefresh implements Column.
func (*TextColumn) Render ¶
func (tc *TextColumn) Render(task TaskSnapshot, c *console.Console, opts console.Options) []segment.Segment
Render implements Column.
type TimeElapsedColumn ¶
type TimeElapsedColumn struct {
Compact bool
Style *style.Style
// contains filtered or unexported fields
}
TimeElapsedColumn displays the elapsed time.
func NewTimeElapsedColumn ¶
func NewTimeElapsedColumn() *TimeElapsedColumn
NewTimeElapsedColumn creates a new time elapsed column.
func (*TimeElapsedColumn) MaxRefresh ¶
func (tec *TimeElapsedColumn) MaxRefresh() time.Duration
MaxRefresh implements Column.
func (*TimeElapsedColumn) Render ¶
func (tec *TimeElapsedColumn) Render(task TaskSnapshot, c *console.Console, opts console.Options) []segment.Segment
Render implements Column.
type TimeRemainingColumn ¶
type TimeRemainingColumn struct {
Compact bool // Use compact format (MM:SS)
ElapsedWhenFinished bool // Show elapsed time when finished
Style *style.Style
// contains filtered or unexported fields
}
TimeRemainingColumn displays the estimated time remaining.
func NewTimeRemainingColumn ¶
func NewTimeRemainingColumn() *TimeRemainingColumn
NewTimeRemainingColumn creates a new time remaining column.
func (*TimeRemainingColumn) MaxRefresh ¶
func (trc *TimeRemainingColumn) MaxRefresh() time.Duration
MaxRefresh implements Column.
func (*TimeRemainingColumn) Render ¶
func (trc *TimeRemainingColumn) Render(task TaskSnapshot, c *console.Console, opts console.Options) []segment.Segment
Render implements Column.
type TotalFileSizeColumn ¶
type TotalFileSizeColumn struct {
BinaryUnits bool
Style *style.Style
// contains filtered or unexported fields
}
TotalFileSizeColumn displays the total as a file size.
func NewTotalFileSizeColumn ¶
func NewTotalFileSizeColumn(binaryUnits bool) *TotalFileSizeColumn
NewTotalFileSizeColumn creates a new total file size column.
func (*TotalFileSizeColumn) MaxRefresh ¶
func (tfsc *TotalFileSizeColumn) MaxRefresh() time.Duration
MaxRefresh implements Column.
func (*TotalFileSizeColumn) Render ¶
func (tfsc *TotalFileSizeColumn) Render(task TaskSnapshot, c *console.Console, opts console.Options) []segment.Segment
Render implements Column.
type TransferSpeedColumn ¶
type TransferSpeedColumn struct {
BinaryUnits bool
Style *style.Style
// contains filtered or unexported fields
}
TransferSpeedColumn displays transfer speed in bytes/second.
func NewTransferSpeedColumn ¶
func NewTransferSpeedColumn(binaryUnits bool) *TransferSpeedColumn
NewTransferSpeedColumn creates a new transfer speed column.
func (*TransferSpeedColumn) MaxRefresh ¶
func (tsc *TransferSpeedColumn) MaxRefresh() time.Duration
MaxRefresh implements Column.
func (*TransferSpeedColumn) Render ¶
func (tsc *TransferSpeedColumn) Render(task TaskSnapshot, c *console.Console, opts console.Options) []segment.Segment
Render implements Column.
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer wraps an io.Writer to track progress.
func (*Writer) BytesWritten ¶
BytesWritten returns the total bytes written so far.