progress

Documentation

Overview

Package progress contains progress bar widget functionality. Use progress.New to create a new progress widget container. That widget should be added to a context using progress.NewContext, and retrieved via progress.FromContext. Invoke one of the Progress.NewX methods to create a new progress.Bar. Invoke Bar.Incr to increment the bar's progress, and invoke Bar.Stop to stop the bar. Be sure to invoke Progress.Stop when the progress widget is no longer needed.

You can use the progress.NewReader and progress.NewWriter functions to wrap an io.Reader or io.Writer, respectively, with a progress bar. Both functions expect the supplied ctx arg to contain a *progress.Progress. Note also that both wrappers are context-aware; that is, they will stop the reading/writing process when the context is canceled. Be sure to call Close on the wrappers when done.

Index

• Constants
• Variables
• func Incr(ctx context.Context, n int)
• func NewBarContext(ctx context.Context, bar Bar) context.Context
• func NewContext(ctx context.Context, p *Progress) context.Context
• func NewReader(ctx context.Context, msg string, size int64, r io.Reader) io.Reader
• type Bar
• type BarOpt
• type Colors
  • func DefaultColors() *Colors
  • func (c *Colors) EnableColor(enable bool)
• type Progress
  • func FromContext(ctx context.Context) *Progress
  • func New(ctx context.Context, out io.Writer, maxBars int, delay time.Duration, ...) *Progress
  • func (p *Progress) HideOnWriter(w io.Writer) io.Writer
  • func (p *Progress) NewByteCounter(msg string, size int64, opts ...BarOpt) Bar
  • func (p *Progress) NewFilesizeCounter(msg string, f *os.File, fp string, opts ...BarOpt) Bar
  • func (p *Progress) NewTimeoutWaiter(msg string, expires time.Time, opts ...BarOpt) Bar
  • func (p *Progress) NewUnitCounter(msg, unit string, opts ...BarOpt) Bar
  • func (p *Progress) NewUnitTotalCounter(msg, unit string, total int64, opts ...BarOpt) Bar
  • func (p *Progress) NewWaiter(msg string, opts ...BarOpt) Bar
  • func (p *Progress) Stop()
• type Writer
  • func NewWriter(ctx context.Context, msg string, size int64, w io.Writer) Writer

Constants

const (

	// DefaultMaxBars is the default threshold at which any further bars are
	// combined into a group bar.
	DefaultMaxBars = 5
)

Variables

var OptMemUsage = optMemUsage{}

OptMemUsage is an BarOpt that causes the bar to display program memory usage.

var OptTimer = optTimer{}

OptTimer is an BarOpt that causes the bar to display elapsed seconds.

Functions

func Incr

func Incr(ctx context.Context, n int)

Incr invokes [Bar.Incr] with amount n on the outermost Bar in ctx. Use in conjunction with a context returned from NewBarContext. It safe to invoke Incr on a nil context or a context that doesn't contain a Bar.

NOTE: This context-based incrementing is a bit of an experiment. I'm hesitant in going further with context-based logic, as it's not clear to me that it's a good idea to lean on context so much. So, it's possible this mechanism may be removed in the future.

func NewBarContext

func NewBarContext(ctx context.Context, bar Bar) context.Context

NewBarContext returns ctx with bar added as a value. This context can be used in conjunction with progress.Incr to increment the progress bar.

func NewContext

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

NewContext returns ctx with p added as a value.

func NewReader

func NewReader(ctx context.Context, msg string, size int64, r io.Reader) io.Reader

NewReader returns an io.Reader that wraps r, is context-aware, and generates a progress bar as bytes are read from r. It is expected that ctx contains a *progress.Progress, as returned by progress.FromContext. If not, this function delegates to contextio.NewReader: the returned reader will still be context-ware. See the contextio package for more details.

Context state is checked BEFORE every Read.

The returned io.Reader also implements io.Closer, even if the underlying reader does not. This is necessary because we need a means of stopping the progress bar when writing is complete. If the underlying reader does implement io.Closer, it will be closed when the returned reader is closed.

Types

type Bar

type Bar interface {
	// Incr increments the progress bar by amount n.
	Incr(n int)

	// Stop stops and removes the bar, preventing further use of the bar.
	Stop()
	// contains filtered or unexported methods
}

Bar represents a single progress bar, owned by a Progress instance. The caller invokes Incr as necessary to increment the bar's progress. When the bar is complete, the caller should invoke Bar.Stop.

type BarOpt

type BarOpt interface {
	// contains filtered or unexported methods
}

BarOpt is a functional option for Bar creation.

type Colors

type Colors struct {
	Error    *color.Color
	Filler   *color.Color
	MemUsage *color.Color
	Message  *color.Color
	Percent  *color.Color
	Size     *color.Color
	Timer    *color.Color
	Waiting  *color.Color
	Warning  *color.Color
}

Colors is the set of colors used for the progress bars.

func DefaultColors

func DefaultColors() *Colors

DefaultColors returns the default colors used for the progress bars.

func (*Colors) EnableColor

func (c *Colors) EnableColor(enable bool)

EnableColor enables or disables color for the progress bars.

type Progress

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

Progress represents a container that renders one or more progress bars. The caller is responsible for calling Progress.Stop to indicate completion.

func FromContext

func FromContext(ctx context.Context) *Progress

FromContext returns the Progress added to ctx via NewContext, or returns nil. Note that it is safe to invoke the methods of a nil Progress.

func New

func New(ctx context.Context, out io.Writer, maxBars int, delay time.Duration, colors *Colors) *Progress

New returns a new Progress instance, which is a container for progress bars. The returned Progress instance is safe for concurrent use, and all of its exported methods can be safely invoked on a nil Progress. The caller is responsible for calling Progress.Stop on the returned Progress.

Arg delay specifies a duration to wait before rendering the progress bar. The Progress is lazily initialized, and thus the delay clock doesn't start ticking until the first call to one of the Progress.NewXBar functions.

Arg maxBars specifies the threshold at which any further bars are combined into a group bar. This is useful for UX, to avoid flooding the terminal with progress bars, and for performance, as the progress widgets don't scale well. If maxBars is <= 0, a nil Progress is returned, which won't render any UX.

func (*Progress) HideOnWriter

func (p *Progress) HideOnWriter(w io.Writer) io.Writer

HideOnWriter returns an io.Writer that hides the Progress when w is written to. Note that the Progress may show itself again after its render delay has elapsed anew. HideOnWriter is typically called with os.Stdout, to hide the Progress when the main program writes to stdout.

func (*Progress) NewByteCounter

func (p *Progress) NewByteCounter(msg string, size int64, opts ...BarOpt) Bar

NewByteCounter returns a new determinate bar whose label metric is the size in bytes of the data being processed. The caller is ultimately responsible for calling Bar.Stop on the returned Bar.

func (*Progress) NewFilesizeCounter

func (p *Progress) NewFilesizeCounter(msg string, f *os.File, fp string, opts ...BarOpt) Bar

NewFilesizeCounter returns a new indeterminate bar whose label metric is a filesize, or "-" if it can't be read. If f is non-nil, its size is used; else the file at path fp is used. The caller is ultimately responsible for calling Bar.Stop on the returned Bar.

func (*Progress) NewTimeoutWaiter

func (p *Progress) NewTimeoutWaiter(msg string, expires time.Time, opts ...BarOpt) Bar

NewTimeoutWaiter returns a new indeterminate bar whose label is the amount of time remaining until expires. It produces output similar to:

Locking @sakila                    ●∙∙              timeout in 7s

The caller is ultimately responsible for calling Bar.Stop on the returned bar, although the bar will also be stopped when the parent Progress stops.

func (*Progress) NewUnitCounter

func (p *Progress) NewUnitCounter(msg, unit string, opts ...BarOpt) Bar

NewUnitCounter returns a new indeterminate bar whose label metric is the plural of the provided unit. The caller is ultimately responsible for calling Bar.Stop on the returned Bar.

bar := p.NewUnitCounter("Ingest records", "rec")
defer bar.Stop()

for i := 0; i < 100; i++ {
    bar.Incr(1)
    time.Sleep(100 * time.Millisecond)
}

This produces output similar to:

Ingesting records               ∙∙●              87 recs

Note that the unit arg is automatically pluralized.

func (*Progress) NewUnitTotalCounter

func (p *Progress) NewUnitTotalCounter(msg, unit string, total int64, opts ...BarOpt) Bar

NewUnitTotalCounter returns a new determinate bar whose label metric is the plural of the provided unit. The caller is ultimately responsible for calling Bar.Stop on the returned Bar.

This produces output similar to:

Ingesting sheets   ∙∙∙∙∙●                     4 / 16 sheets

Note that the unit arg is automatically pluralized.

func (*Progress) NewWaiter

func (p *Progress) NewWaiter(msg string, opts ...BarOpt) Bar

NewWaiter returns a generic indeterminate spinner with a timer. This produces output similar to:

@excel/remote: start download                ●∙∙                4s

The caller is ultimately responsible for calling Bar.Stop on the returned Bar.

func (*Progress) Stop

func (p *Progress) Stop()

Stop waits for all bars to complete and finally shuts down the progress container. After this method has been called, there is no way to reuse the Progress instance.

type Writer

type Writer interface {
	io.WriteCloser

	// Stop stops and removes the progress bar. Typically this is accomplished
	// by invoking Writer.Close, but there are circumstances where it may
	// be desirable to stop the progress bar without closing the underlying
	// writer.
	Stop()
}

Writer is an io.WriteCloser as returned by NewWriter.

func NewWriter

func NewWriter(ctx context.Context, msg string, size int64, w io.Writer) Writer

NewWriter returns a progress.Writer that wraps w, is context-aware, and generates a progress bar as bytes are written to w. It is expected that ctx contains a *progress.Progress, as returned by progress.FromContext. If not, this function delegates to contextio.NewWriter: the returned writer will still be context-aware. See the contextio package for more details.

Context state is checked BEFORE every Write.

The returned progress.Writer implements io.ReaderFrom to allow io.Copy to select the best strategy while still checking the context state before every chunk transfer.

The returned progress.Writer also implements io.Closer, even if the underlying writer does not. This is necessary because we need a means of stopping the progress bar when writing is complete. If the underlying writer does implement io.Closer, it will be closed when the returned writer is closed.

The caller is expected to close the returned writer, which results in the progress bar being removed. However, the progress bar can also be removed independently of closing the writer by invoking Writer.Stop.

If size is unknown, set to -1; this will result in an indeterminate progress spinner instead of a bar.