mpb

package module
v8.8.3 Latest Latest
Warning

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

 Go to latest Published: Aug 26, 2024 License: Unlicense Imports: 15 Imported by: 157

README

Multi Progress Bar

GoDoc Test status Lint status

mpb is a Go lib for rendering progress bars in terminal applications.

Features

  • Multiple Bars: Multiple progress bars are supported
  • Dynamic Total: Set total while bar is running
  • Dynamic Add/Remove: Dynamically add or remove bars
  • Cancellation: Cancel whole rendering process
  • Predefined Decorators: Elapsed time, ewma based ETA, Percentage, Bytes counter
  • Decorator's width sync: Synchronized decorator's width among multiple bars

Usage

Rendering single bar
package main

import (
    "math/rand"
    "time"

    "github.com/vbauerster/mpb/v8"
    "github.com/vbauerster/mpb/v8/decor"
)

func main() {
    // initialize progress container, with custom width
    p := mpb.New(mpb.WithWidth(64))

    total := 100
    name := "Single Bar:"
    // create a single bar, which will inherit container's width
    bar := p.New(int64(total),
        // BarFillerBuilder with custom style
        mpb.BarStyle().Lbound("╢").Filler("▌").Tip("▌").Padding("░").Rbound("╟"),
        mpb.PrependDecorators(
            // display our name with one space on the right
            decor.Name(name, decor.WC{C: decor.DindentRight | decor.DextraSpace}),
            // replace ETA decorator with "done" message, OnComplete event
            decor.OnComplete(decor.AverageETA(decor.ET_STYLE_GO), "done"),
        ),
        mpb.AppendDecorators(decor.Percentage()),
    )
    // simulating some work
    max := 100 * time.Millisecond
    for i := 0; i < total; i++ {
        time.Sleep(time.Duration(rand.Intn(10)+1) * max / 10)
        bar.Increment()
    }
    // wait for our bar to complete and flush
    p.Wait()
}
Rendering multiple bars
    var wg sync.WaitGroup
    // passed wg will be accounted at p.Wait() call
    p := mpb.New(mpb.WithWaitGroup(&wg))
    total, numBars := 100, 3
    wg.Add(numBars)

    for i := 0; i < numBars; i++ {
        name := fmt.Sprintf("Bar#%d:", i)
        bar := p.AddBar(int64(total),
            mpb.PrependDecorators(
                // simple name decorator
                decor.Name(name),
                // decor.DSyncWidth bit enables column width synchronization
                decor.Percentage(decor.WCSyncSpace),
            ),
            mpb.AppendDecorators(
                // replace ETA decorator with "done" message, OnComplete event
                decor.OnComplete(
                    // ETA decorator with ewma age of 30
                    decor.EwmaETA(decor.ET_STYLE_GO, 30, decor.WCSyncWidth), "done",
                ),
            ),
        )
        // simulating some work
        go func() {
            defer wg.Done()
            rng := rand.New(rand.NewSource(time.Now().UnixNano()))
            max := 100 * time.Millisecond
            for i := 0; i < total; i++ {
                // start variable is solely for EWMA calculation
                // EWMA's unit of measure is an iteration's duration
                start := time.Now()
                time.Sleep(time.Duration(rng.Intn(10)+1) * max / 10)
                // we need to call EwmaIncrement to fulfill ewma decorator's contract
                bar.EwmaIncrement(time.Since(start))
            }
        }()
    }
    // wait for passed wg and for all bars to complete and flush
    p.Wait()
Dynamic total

dynamic total

Complex example

complex

Bytes counters

byte counters

Documentation

Overview

Package mpb is a library for rendering progress bars in terminal applications.

Example 
// initialize progress container, with custom width
p := mpb.New(mpb.WithWidth(64))

total := 100
name := "Single Bar:"
// create a single bar, which will inherit container's width
bar := p.New(int64(total),
	// BarFillerBuilder with custom style
	mpb.BarStyle().Lbound("╢").Filler("▌").Tip("▌").Padding("░").Rbound("╟"),
	mpb.PrependDecorators(
		// display our name with one space on the right
		decor.Name(name, decor.WC{C: decor.DindentRight | decor.DextraSpace}),
		// replace ETA decorator with "done" message, OnComplete event
		decor.OnComplete(decor.AverageETA(decor.ET_STYLE_GO), "done"),
	),
	mpb.AppendDecorators(decor.Percentage()),
)
// simulating some work
max := 100 * time.Millisecond
for i := 0; i < total; i++ {
	time.Sleep(time.Duration(rand.Intn(10)+1) * max / 10)
	bar.Increment()
}
// wait for our bar to complete and flush
p.Wait()

Output:

Index

Examples

Constants

This section is empty.

Variables

View Source 
var DoneError = fmt.Errorf("%T instance can't be reused after %[1]T.Wait()", (*Progress)(nil))

DoneError represents use after `(*Progress).Wait()` error.

Functions

This section is empty.

Types

type Bar 

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

Bar represents a progress bar.

func (*Bar) Abort 

func (b *Bar) Abort(drop bool)

Abort interrupts bar's running goroutine. Abort won't be engaged if bar is already in complete state. If drop is true bar will be removed as well. To make sure that bar has been removed call `(*Bar).Wait()` method.

func (*Bar) Aborted 

func (b *Bar) Aborted() bool

Aborted reports whether the bar is in aborted state.

func (*Bar) Completed 

func (b *Bar) Completed() bool

Completed reports whether the bar is in completed state.

Example 
p := mpb.New()
bar := p.AddBar(100)

max := 100 * time.Millisecond
for !bar.Completed() {
	time.Sleep(time.Duration(rand.Intn(10)+1) * max / 10)
	bar.Increment()
}

p.Wait()

Output:

func (*Bar) Current 

func (b *Bar) Current() int64

Current returns bar's current value, in other words sum of all increments.

func (*Bar) DecoratorAverageAdjust 

func (b *Bar) DecoratorAverageAdjust(start time.Time)

DecoratorAverageAdjust adjusts decorators implementing decor.AverageDecorator interface. Call if there is need to set start time after decorators have been constructed.

func (*Bar) EnableTriggerComplete 

func (b *Bar) EnableTriggerComplete()

EnableTriggerComplete enables triggering complete event. It's effective only for bars which were constructed with `total <= 0`. If `curren >= total` at the moment of call, complete event is triggered right away.

func (*Bar) EwmaIncrBy added in v8.1.0 

func (b *Bar) EwmaIncrBy(n int, iterDur time.Duration)

EwmaIncrBy is a shorthand for b.EwmaIncrInt64(int64(n), iterDur).

func (*Bar) EwmaIncrInt64 added in v8.1.0 

func (b *Bar) EwmaIncrInt64(n int64, iterDur time.Duration)

EwmaIncrInt64 increments progress by amount of n and updates EWMA based decorators by dur of a single iteration.

func (*Bar) EwmaIncrement added in v8.1.0 

func (b *Bar) EwmaIncrement(iterDur time.Duration)

EwmaIncrement is a shorthand for b.EwmaIncrInt64(1, iterDur).

func (*Bar) EwmaSetCurrent added in v8.1.0 

func (b *Bar) EwmaSetCurrent(current int64, iterDur time.Duration)

EwmaSetCurrent sets progress' current to an arbitrary value and updates EWMA based decorators by dur of a single iteration.

func (*Bar) ID 

func (b *Bar) ID() int

ID returs id of the bar.

func (*Bar) IncrBy 

func (b *Bar) IncrBy(n int)

IncrBy is a shorthand for b.IncrInt64(int64(n)).

func (*Bar) IncrInt64 

func (b *Bar) IncrInt64(n int64)

IncrInt64 increments progress by amount of n.

func (*Bar) Increment 

func (b *Bar) Increment()

Increment is a shorthand for b.IncrInt64(1).

func (*Bar) IsRunning 

func (b *Bar) IsRunning() bool

IsRunning reports whether the bar is in running state.

func (*Bar) ProxyReader 

func (b *Bar) ProxyReader(r io.Reader) io.ReadCloser

ProxyReader wraps io.Reader with metrics required for progress tracking. If `r` is 'unknown total/size' reader it's mandatory to call `(*Bar).SetTotal(-1, true)` after the wrapper returns `io.EOF`. If bar is already completed or aborted, returns nil. Panics if `r` is nil.

Example 
// import crand "crypto/rand"

var total int64 = 1024 * 1024 * 500
reader := io.LimitReader(crand.Reader, total)

p := mpb.New()
bar := p.AddBar(total,
	mpb.AppendDecorators(
		decor.CountersKibiByte("% .2f / % .2f"),
	),
)

// create proxy reader
proxyReader := bar.ProxyReader(reader)
defer proxyReader.Close()

// and copy from reader, ignoring errors
_, _ = io.Copy(io.Discard, proxyReader)

p.Wait()

Output:

func (*Bar) ProxyWriter added in v8.1.0 

func (b *Bar) ProxyWriter(w io.Writer) io.WriteCloser

ProxyWriter wraps io.Writer with metrics required for progress tracking. If bar is already completed or aborted, returns nil. Panics if `w` is nil.

func (*Bar) SetCurrent 

func (b *Bar) SetCurrent(current int64)

SetCurrent sets progress' current to an arbitrary value.

func (*Bar) SetPriority 

func (b *Bar) SetPriority(priority int)

SetPriority changes bar's order among multiple bars. Zero is highest priority, i.e. bar will be on top. If you don't need to set priority dynamically, better use BarPriority option.

func (*Bar) SetRefill 

func (b *Bar) SetRefill(amount int64)

SetRefill sets refill flag with specified amount. The underlying BarFiller will change its visual representation, to indicate refill event. Refill event may be referred to some retry operation for example.

func (*Bar) SetTotal 

func (b *Bar) SetTotal(total int64, complete bool)

SetTotal sets total to an arbitrary value. It's effective only for bar which was constructed with `total <= 0`. Setting total to negative value is equivalent to `(*Bar).SetTotal((*Bar).Current(), bool)` but faster. If `complete` is true complete event is triggered right away. Calling `(*Bar).EnableTriggerComplete` makes this one no operational.

func (*Bar) TraverseDecorators 

func (b *Bar) TraverseDecorators(cb func(decor.Decorator))

TraverseDecorators traverses available decorators and calls cb func on each in a new goroutine. Decorators implementing decor.Wrapper interface are unwrapped first.

func (*Bar) Wait 

func (b *Bar) Wait()

Wait blocks until bar is completed or aborted.

type BarFiller 

type BarFiller interface {
	Fill(io.Writer, decor.Statistics) error
}

BarFiller interface. Bar (without decorators) renders itself by calling BarFiller's Fill method.

type BarFillerBuilder 

type BarFillerBuilder interface {
	Build() BarFiller
}

BarFillerBuilder interface. Default implementations are: 

BarStyle()
SpinnerStyle()
NopStyle()

func NopStyle 

func NopStyle() BarFillerBuilder

NopStyle provides BarFillerBuilder which builds NOP BarFiller.

type BarFillerFunc 

type BarFillerFunc func(io.Writer, decor.Statistics) error

BarFillerFunc is function type adapter to convert compatible function into BarFiller interface.

func (BarFillerFunc) Fill 

func (f BarFillerFunc) Fill(w io.Writer, stat decor.Statistics) error

type BarOption 

type BarOption func(*bState)

BarOption is a func option to alter default behavior of a bar.

func AppendDecorators 

func AppendDecorators(decorators ...decor.Decorator) BarOption

AppendDecorators let you inject decorators to the bar's right side.

func BarExtender 

func BarExtender(filler BarFiller, rev bool) BarOption

BarExtender extends bar with arbitrary lines. Provided BarFiller will be called at each render/flush cycle. Any lines written to the underlying io.Writer will extend the bar either in above (rev = true) or below (rev = false) direction.

func BarFillerClearOnComplete 

func BarFillerClearOnComplete() BarOption

BarFillerClearOnComplete clears bar's filler on complete event. It's shortcut for BarFillerOnComplete("").

func BarFillerMiddleware 

func BarFillerMiddleware(middle func(BarFiller) BarFiller) BarOption

BarFillerMiddleware provides a way to augment the underlying BarFiller.

func BarFillerOnComplete 

func BarFillerOnComplete(message string) BarOption

BarFillerOnComplete replaces bar's filler with message, on complete event.

func BarFillerTrim 

func BarFillerTrim() BarOption

BarFillerTrim removes leading and trailing space around the underlying BarFiller.

func BarFuncOptOn 

func BarFuncOptOn(option func() BarOption, predicate func() bool) BarOption

BarFuncOptOn will call option and return its value only when predicate evaluates to true.

func BarFuncOptional 

func BarFuncOptional(option func() BarOption, cond bool) BarOption

BarFuncOptional will call option and return its value only when cond is true.

func BarID 

func BarID(id int) BarOption

BarID sets bar id.

func BarNoPop 

func BarNoPop() BarOption

BarNoPop disables bar pop out of container. Effective when PopCompletedMode of container is enabled.

func BarOptOn 

func BarOptOn(option BarOption, predicate func() bool) BarOption

BarOptOn will return provided option only when predicate evaluates to true.

func BarOptional 

func BarOptional(option BarOption, cond bool) BarOption

BarOptional will return provided option only when cond is true.

func BarPriority 

func BarPriority(priority int) BarOption

BarPriority sets bar's priority. Zero is highest priority, i.e. bar will be on top. This option isn't effective with `BarQueueAfter` option.

func BarQueueAfter 

func BarQueueAfter(bar *Bar) BarOption

BarQueueAfter puts this (being constructed) bar into the queue. BarPriority will be inherited from the argument bar. When argument bar completes or aborts queued bar replaces its place.

func BarRemoveOnComplete 

func BarRemoveOnComplete() BarOption

BarRemoveOnComplete removes both bar's filler and its decorators on complete event.

func BarWidth 

func BarWidth(width int) BarOption

BarWidth sets bar width independent of the container.

func PrependDecorators 

func PrependDecorators(decorators ...decor.Decorator) BarOption

PrependDecorators let you inject decorators to the bar's left side.

type BarStyleComposer 

type BarStyleComposer interface {
	BarFillerBuilder
	Lbound(string) BarStyleComposer
	LboundMeta(func(string) string) BarStyleComposer
	Rbound(string) BarStyleComposer
	RboundMeta(func(string) string) BarStyleComposer
	Filler(string) BarStyleComposer
	FillerMeta(func(string) string) BarStyleComposer
	Refiller(string) BarStyleComposer
	RefillerMeta(func(string) string) BarStyleComposer
	Padding(string) BarStyleComposer
	PaddingMeta(func(string) string) BarStyleComposer
	Tip(frames ...string) BarStyleComposer
	TipMeta(func(string) string) BarStyleComposer
	TipOnComplete() BarStyleComposer
	Reverse() BarStyleComposer
}

BarStyleComposer interface.

func BarStyle 

func BarStyle() BarStyleComposer

BarStyle constructs default bar style which can be altered via BarStyleComposer interface.

type ContainerOption 

type ContainerOption func(*pState)

ContainerOption is a func option to alter default behavior of a bar container. Container term refers to a Progress struct which can hold one or more Bars.

func ContainerFuncOptOn 

func ContainerFuncOptOn(option func() ContainerOption, predicate func() bool) ContainerOption

ContainerFuncOptOn will call option and return its value only when predicate evaluates to true.

func ContainerFuncOptional 

func ContainerFuncOptional(option func() ContainerOption, cond bool) ContainerOption

ContainerFuncOptional will call option and return its value only when cond is true.

func ContainerOptOn 

func ContainerOptOn(option ContainerOption, predicate func() bool) ContainerOption

ContainerOptOn will return provided option only when predicate evaluates to true.

func ContainerOptional 

func ContainerOptional(option ContainerOption, cond bool) ContainerOption

ContainerOptional will return provided option only when cond is true.

func PopCompletedMode 

func PopCompletedMode() ContainerOption

PopCompletedMode pop completed bars out of progress container. In this mode completed bars get moved to the top and stop participating in rendering cycle.

func WithAutoRefresh added in v8.2.0 

func WithAutoRefresh() ContainerOption

WithAutoRefresh force auto refresh regardless of what output is set to. Applicable only if not WithManualRefresh set.

func WithDebugOutput 

func WithDebugOutput(w io.Writer) ContainerOption

WithDebugOutput sets debug output.

func WithManualRefresh 

func WithManualRefresh(ch <-chan interface{}) ContainerOption

WithManualRefresh disables internal auto refresh time.Ticker. Refresh will occur upon receive value from provided ch.

func WithOutput 

func WithOutput(w io.Writer) ContainerOption

WithOutput overrides default os.Stdout output. If underlying io.Writer is not a terminal then auto refresh is disabled unless WithAutoRefresh option is set.

func WithRefreshRate 

func WithRefreshRate(d time.Duration) ContainerOption

WithRefreshRate overrides default 150ms refresh rate.

func WithRenderDelay 

func WithRenderDelay(ch <-chan struct{}) ContainerOption

WithRenderDelay delays rendering. By default rendering starts as soon as bar is added, with this option it's possible to delay rendering process by keeping provided chan unclosed. In other words rendering will start as soon as provided chan is closed.

func WithShutdownNotifier 

func WithShutdownNotifier(ch chan<- interface{}) ContainerOption

WithShutdownNotifier value of type `[]*mpb.Bar` will be send into provided channel upon container shutdown.

func WithWaitGroup 

func WithWaitGroup(wg *sync.WaitGroup) ContainerOption

WithWaitGroup provides means to have a single joint point. If *sync.WaitGroup is provided, you can safely call just p.Wait() without calling Wait() on provided *sync.WaitGroup. Makes sense when there are more than one bar to render.

func WithWidth 

func WithWidth(width int) ContainerOption

WithWidth sets container width. If not set it defaults to terminal width. A bar added to the container will inherit its width, unless overridden by `func BarWidth(int) BarOption`.

type Progress 

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

Progress represents a container that renders one or more progress bars.

func New 

func New(options ...ContainerOption) *Progress

New creates new Progress container instance. It's not possible to reuse instance after `(*Progress).Wait` method has been called.

func NewWithContext 

func NewWithContext(ctx context.Context, options ...ContainerOption) *Progress

NewWithContext creates new Progress container instance with provided context. It's not possible to reuse instance after `(*Progress).Wait` method has been called.

func (*Progress) Add 

func (p *Progress) Add(total int64, filler BarFiller, options ...BarOption) (*Bar, error)

Add creates a bar which renders itself by provided BarFiller. If `total <= 0` triggering complete event by increment methods is disabled. If called after `(*Progress).Wait()` then `(nil, DoneError)` is returned.

func (*Progress) AddBar 

func (p *Progress) AddBar(total int64, options ...BarOption) *Bar

AddBar creates a bar with default bar filler.

func (*Progress) AddSpinner 

func (p *Progress) AddSpinner(total int64, options ...BarOption) *Bar

AddSpinner creates a bar with default spinner filler.

func (*Progress) MustAdd added in v8.3.0 

func (p *Progress) MustAdd(total int64, filler BarFiller, options ...BarOption) *Bar

MustAdd creates a bar which renders itself by provided BarFiller. If `total <= 0` triggering complete event by increment methods is disabled. Panics if called after `(*Progress).Wait()`.

func (*Progress) New 

func (p *Progress) New(total int64, builder BarFillerBuilder, options ...BarOption) *Bar

New creates a bar by calling `Build` method on provided `BarFillerBuilder`.

func (*Progress) Shutdown added in v8.1.0 

func (p *Progress) Shutdown()

Shutdown cancels any running bar immediately and then shutdowns `*Progress` instance. Normally this method shouldn't be called unless you know what you are doing. Proper way to shutdown is to call `(*Progress).Wait()` instead.

func (*Progress) UpdateBarPriority 

func (p *Progress) UpdateBarPriority(b *Bar, priority int, lazy bool)

UpdateBarPriority either immediately or lazy. With lazy flag order is updated after the next refresh cycle. If you don't care about laziness just use `(*Bar).SetPriority(int)`.

func (*Progress) Wait 

func (p *Progress) Wait()

Wait waits for all bars to complete and finally shutdowns container. After this method has been called, there is no way to reuse `*Progress` instance.

func (*Progress) Write 

func (p *Progress) Write(b []byte) (int, error)

Write is implementation of io.Writer. Writing to `*Progress` will print lines above a running bar. Writes aren't flushed immediately, but at next refresh cycle. If called after `(*Progress).Wait()` then `(0, DoneError)` is returned.

type SpinnerStyleComposer 

type SpinnerStyleComposer interface {
	BarFillerBuilder
	PositionLeft() SpinnerStyleComposer
	PositionRight() SpinnerStyleComposer
	Meta(func(string) string) SpinnerStyleComposer
}

SpinnerStyleComposer interface.

func SpinnerStyle 

func SpinnerStyle(frames ...string) SpinnerStyleComposer

SpinnerStyle constructs default spinner style which can be altered via SpinnerStyleComposer interface.

Source Files

View all Source files

Directories

Path Synopsis
Package cwriter is a console writer abstraction for the underlying OS.
 Package cwriter is a console writer abstraction for the underlying OS.
Package decor provides common decorators for "github.com/vbauerster/mpb/v8" module.
 Package decor provides common decorators for "github.com/vbauerster/mpb/v8" module.

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.