Documentation
¶
Overview ¶
Package progress provides terminal progress bars with multiple tasks and customizable columns.
Index ¶
- Variables
- func DefaultBarStyles() (back, complete, finished, pulse string)
- func Track[T any](items []T, description string, opts ...Option) func(func(T) bool)
- 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) 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 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 ¶
func DefaultBarStyles() (back, complete, finished, pulse string)
DefaultBarStyles returns the default style names for a progress bar.
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.
Types ¶
type BarColumn ¶
type BarColumn struct {
BarWidth *int // Width of the bar, nil = auto
Style string // Style name for completed portion
CompleteStyle string
FinishedStyle string
PulseStyle string
// 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 to display.
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) AddTask ¶
func (p *Progress) AddTask(description string, total *float64, opts ...TaskOption) TaskID
AddTask adds a new task 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)
// Style names (keys in the style map)
BackStyle string
CompleteStyle string
FinishedStyle string
PulseStyle string
}
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 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) 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)
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.