README
¶
Multi Progress Bar
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
Complex example
Bytes 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 ¶
- Variables
- type Bar
- func (b *Bar) Abort(drop bool)
- func (b *Bar) Aborted() bool
- func (b *Bar) Completed() bool
- func (b *Bar) Current() int64
- func (b *Bar) DecoratorAverageAdjust(start time.Time)
- func (b *Bar) EnableTriggerComplete()
- func (b *Bar) EwmaIncrBy(n int, iterDur time.Duration)
- func (b *Bar) EwmaIncrInt64(n int64, iterDur time.Duration)
- func (b *Bar) EwmaIncrement(iterDur time.Duration)
- func (b *Bar) EwmaSetCurrent(current int64, iterDur time.Duration)
- func (b *Bar) ID() int
- func (b *Bar) IncrBy(n int)
- func (b *Bar) IncrInt64(n int64)
- func (b *Bar) Increment()
- func (b *Bar) IsRunning() bool
- func (b *Bar) ProxyReader(r io.Reader) io.ReadCloser
- func (b *Bar) ProxyWriter(w io.Writer) io.WriteCloser
- func (b *Bar) SetCurrent(current int64)
- func (b *Bar) SetPriority(priority int)
- func (b *Bar) SetRefill(amount int64)
- func (b *Bar) SetTotal(total int64, triggerCompletion bool)
- func (b *Bar) TraverseDecorators(cb func(decor.Decorator))
- func (b *Bar) Wait()
- type BarFiller
- type BarFillerBuilder
- type BarFillerFunc
- type BarOption
- func AppendDecorators(decorators ...decor.Decorator) BarOption
- func BarExtender(filler BarFiller, rev bool) BarOption
- func BarFillerClearOnComplete() BarOption
- func BarFillerMiddleware(middle func(BarFiller) BarFiller) BarOption
- func BarFillerOnComplete(message string) BarOption
- func BarFillerTrim() BarOption
- func BarFuncOptOn(option func() BarOption, predicate func() bool) BarOption
- func BarFuncOptional(option func() BarOption, cond bool) BarOption
- func BarID(id int) BarOption
- func BarNoPop() BarOption
- func BarOptOn(option BarOption, predicate func() bool) BarOption
- func BarOptional(option BarOption, cond bool) BarOption
- func BarPriority(priority int) BarOption
- func BarQueueAfter(bar *Bar) BarOption
- func BarRemoveOnComplete() BarOption
- func BarWidth(width int) BarOption
- func PrependDecorators(decorators ...decor.Decorator) BarOption
- type BarStyleComposer
- type ContainerOption
- func ContainerFuncOptOn(option func() ContainerOption, predicate func() bool) ContainerOption
- func ContainerFuncOptional(option func() ContainerOption, cond bool) ContainerOption
- func ContainerOptOn(option ContainerOption, predicate func() bool) ContainerOption
- func ContainerOptional(option ContainerOption, cond bool) ContainerOption
- func PopCompletedMode() ContainerOption
- func WithAutoRefresh() ContainerOption
- func WithDebugOutput(w io.Writer) ContainerOption
- func WithManualRefresh(ch <-chan interface{}) ContainerOption
- func WithOutput(w io.Writer) ContainerOption
- func WithRefreshRate(d time.Duration) ContainerOption
- func WithRenderDelay(ch <-chan struct{}) ContainerOption
- func WithShutdownNotifier(ch chan<- interface{}) ContainerOption
- func WithWaitGroup(wg *sync.WaitGroup) ContainerOption
- func WithWidth(width int) ContainerOption
- type Progress
- func (p *Progress) Add(total int64, filler BarFiller, options ...BarOption) (*Bar, error)
- func (p *Progress) AddBar(total int64, options ...BarOption) *Bar
- func (p *Progress) AddSpinner(total int64, options ...BarOption) *Bar
- func (p *Progress) MustAdd(total int64, filler BarFiller, options ...BarOption) *Bar
- func (p *Progress) New(total int64, builder BarFillerBuilder, options ...BarOption) *Bar
- func (p *Progress) Shutdown()
- func (p *Progress) UpdateBarPriority(b *Bar, priority int, lazy bool)
- func (p *Progress) Wait()
- func (p *Progress) Write(b []byte) (int, error)
- type SpinnerStyleComposer
Examples ¶
Constants ¶
This section is empty.
Variables ¶
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 ¶
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) Completed ¶
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) DecoratorAverageAdjust ¶
DecoratorAverageAdjust adjusts all average based decorators. Call if you need to adjust start time of all average based decorators or after progress resume.
func (*Bar) EnableTriggerComplete ¶
func (b *Bar) EnableTriggerComplete()
EnableTriggerComplete enables triggering complete event. It's effective only for bars which were constructed with `total <= 0` and after total has been set with `(*Bar).SetTotal(int64, false)`. If `curren >= total` at the moment of call, complete event is triggered right away.
func (*Bar) EwmaIncrBy ¶ added in v8.1.0
EwmaIncrBy is a shorthand for b.EwmaIncrInt64(int64(n), iterDur).
func (*Bar) EwmaIncrInt64 ¶ added in v8.1.0
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
EwmaIncrement is a shorthand for b.EwmaIncrInt64(1, iterDur).
func (*Bar) EwmaSetCurrent ¶ added in v8.1.0
EwmaSetCurrent sets progress' current to an arbitrary value and updates EWMA based decorators by dur of a single iteration.
func (*Bar) IsRunning ¶
IsRunning reports whether the bar is running, i.e. not yet completed and not yet aborted.
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 ¶
SetCurrent sets progress' current to an arbitrary value.
func (*Bar) SetPriority ¶
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 ¶
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 ¶
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 triggerCompletion is true, total value is set to current and complete event is triggered right away.
func (*Bar) TraverseDecorators ¶
TraverseDecorators traverses all available decorators and calls cb func on each.
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 ¶
AppendDecorators let you inject decorators to the bar's right side.
func BarExtender ¶
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 ¶
BarFillerMiddleware provides a way to augment the underlying BarFiller.
func BarFillerOnComplete ¶
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 ¶
BarFuncOptOn will call option and return its value only when predicate evaluates to true.
func BarFuncOptional ¶
BarFuncOptional will call option and return its value only when cond is true.
func BarNoPop ¶
func BarNoPop() BarOption
BarNoPop disables bar pop out of container. Effective when PopCompletedMode of container is enabled.
func BarOptional ¶
BarOptional will return provided option only when cond is true.
func BarPriority ¶
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 ¶
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 PrependDecorators ¶
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 ¶
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) AddSpinner ¶
AddSpinner creates a bar with default spinner filler.
func (*Progress) MustAdd ¶ added in v8.3.0
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 ¶
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.
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
¶
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. |