progress

package
v1.1.2 Latest Latest
Warning

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

Go to latest
Published: Jul 20, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package progress provides terminal progress bars with multiple tasks and customizable columns.

Index

Constants

This section is empty.

Variables

View Source
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 *style.Style)

DefaultBarStyles returns the default styles for a progress bar.

func Track

func Track[T any](items []T, description string, opts ...Option) func(func(T) bool)

Track iterates over items while showing progress.

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 WithBarWidth

func WithBarWidth(width int) func(*BarColumn)

WithBarWidth sets the bar 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

func NewBarColumn(opts ...func(*BarColumn)) *BarColumn

NewBarColumn creates a new bar column.

func (*BarColumn) MaxRefresh

func (bc *BarColumn) MaxRefresh() time.Duration

MaxRefresh implements Column.

func (*BarColumn) Render

func (bc *BarColumn) Render(task TaskSnapshot, c *console.Console, opts console.Options) []segment.Segment

Render 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

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

Render implements Column.

type Option

type Option func(*Progress)

Option configures a Progress.

func WithColumns

func WithColumns(columns ...Column) Option

WithColumns sets the columns for the default section (section 0).

func WithConsole

func WithConsole(c *console.Console) Option

WithConsole sets the console to use.

func WithDisable

func WithDisable(disable bool) Option

WithDisable disables all output (useful for CI).

func WithExpand

func WithExpand(expand bool) Option

WithExpand expands the display to fill terminal width.

func WithRefreshRate

func WithRefreshRate(hz float64) Option

WithRefreshRate sets the refresh rate in Hz (default 10).

func WithSpeedEstimatePeriod

func WithSpeedEstimatePeriod(seconds float64) Option

WithSpeedEstimatePeriod sets the window for speed estimation (default 30s).

func WithTransient

func WithTransient(transient bool) Option

WithTransient clears the progress display when stopped.

type Progress

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

Progress manages multiple progress tasks.

func New

func New(opts ...Option) *Progress

New creates a new Progress with the given options.

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) Advance

func (p *Progress) Advance(taskID TaskID, amount float64)

Advance increments a task's progress.

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

func (p *Progress) Done(taskID TaskID, description ...string)

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) Finished

func (p *Progress) Finished() bool

Finished returns true if all tasks are finished.

func (*Progress) Refresh

func (p *Progress) Refresh()

Refresh forces an immediate refresh.

func (*Progress) RemoveTask

func (p *Progress) RemoveTask(taskID TaskID)

RemoveTask removes a task from the display.

func (*Progress) ResetTask

func (p *Progress) ResetTask(taskID TaskID, start bool)

ResetTask resets a task to initial state.

func (*Progress) Start

func (p *Progress) Start(ctx context.Context)

Start begins the progress display.

func (*Progress) StartTask

func (p *Progress) StartTask(taskID TaskID)

StartTask begins timing a task.

func (*Progress) Stop

func (p *Progress) Stop()

Stop ends the progress display.

func (*Progress) StopTask

func (p *Progress) StopTask(taskID TaskID)

StopTask pauses timing a task.

func (*Progress) String

func (p *Progress) String() string

Simple string builder for progress output when not using Live

func (*Progress) Update

func (p *Progress) Update(taskID TaskID, cfg TaskUpdateConfig)

Update updates a task's state.

func (*Progress) WrapFile

func (p *Progress) WrapFile(path string, description string) (*Reader, TaskID, error)

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

func (p *Progress) WrapReader(r io.Reader, total int64, description string) (*Reader, TaskID)

WrapReader wraps an io.Reader with progress tracking. Returns the wrapped reader and a function to stop tracking.

func (*Progress) WrapWriter

func (p *Progress) WrapWriter(w io.Writer, total int64, description string) (*Writer, TaskID)

WrapWriter wraps an io.Writer with progress 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

Measure implements console.Measurable.

func (*ProgressBar) Render

func (pb *ProgressBar) Render(c *console.Console, opts console.Options) []segment.Segment

Render implements console.Renderable.

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.

func (*ReadCloser) Close

func (rc *ReadCloser) Close() error

Close closes the underlying reader.

type Reader

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

Reader wraps an io.Reader to track progress.

func NewReader

func NewReader(r io.Reader, p *Progress, taskID TaskID) *Reader

NewReader creates a progress-tracking reader.

func (*Reader) BytesRead

func (r *Reader) BytesRead() int64

BytesRead returns the total bytes read so far.

func (*Reader) Close

func (r *Reader) Close() error

Close implements io.Closer if the underlying reader supports it.

func (*Reader) Read

func (r *Reader) Read(p []byte) (n int, err error)

Read implements io.Reader.

func (*Reader) Seek

func (r *Reader) Seek(offset int64, whence int) (int64, error)

Seek implements io.Seeker if the underlying reader supports it.

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

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.

func (*Section) AddTask added in v1.0.5

func (s *Section) AddTask(description string, total *float64, opts ...TaskOption) TaskID

AddTask adds a task to this section and returns its globally-unique TaskID.

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

type SeparatorColumn struct {
	Text  string
	Style *style.Style
}

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

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) Advance

func (t *Task) Advance(amount float64)

Advance increments the completed count.

func (*Task) Done added in v1.0.3

func (t *Task) Done(description ...string)

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) ID

func (t *Task) ID() TaskID

ID returns the task ID.

func (*Task) Reset

func (t *Task) Reset(start bool)

Reset resets the task to initial state.

func (*Task) Snapshot

func (t *Task) Snapshot() TaskSnapshot

Snapshot returns a read-only copy of the task state.

func (*Task) Start

func (t *Task) Start()

Start begins timing the task.

func (*Task) Stop

func (t *Task) Stop()

Stop pauses timing the task.

func (*Task) Update

func (t *Task) Update(cfg TaskUpdateConfig)

Update updates 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 TaskID

type TaskID int64

TaskID is a unique identifier for a progress 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

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

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

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

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

Render implements Column.

type Writer

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

Writer wraps an io.Writer to track progress.

func NewWriter

func NewWriter(w io.Writer, p *Progress, taskID TaskID) *Writer

NewWriter creates a progress-tracking writer.

func (*Writer) BytesWritten

func (w *Writer) BytesWritten() int64

BytesWritten returns the total bytes written so far.

func (*Writer) Close

func (w *Writer) Close() error

Close implements io.Closer if the underlying writer supports it.

func (*Writer) Write

func (w *Writer) Write(p []byte) (n int, err error)

Write implements io.Writer.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL