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:" // adding a single bar, which will inherit container's width bar := p.Add(int64(total), // progress bar filler with customized style mpb.NewBarFiller("╢▌▌░╟"), mpb.PrependDecorators( // display our name with one space on the right decor.Name(name, decor.WC{W: len(name) + 1, C: decor.DidentRight}), // replace ETA decorator with "done" message, OnComplete event decor.OnComplete( // ETA decorator with ewma age of 60, and width reservation of 4 decor.EwmaETA(decor.ET_STYLE_GO, 60, decor.WC{W: 4}), "done", ), ), mpb.AppendDecorators(decor.Percentage()), ) // simulating some work 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(rand.Intn(10)+1) * max / 10) bar.Increment() // we need to call DecoratorEwmaUpdate to fulfill ewma decorator's contract bar.DecoratorEwmaUpdate(time.Since(start)) } // wait for our bar to complete and flush p.Wait()
Output:
Index ¶
- Constants
- Variables
- type Bar
- func (b *Bar) Abort(drop bool)
- func (b *Bar) Completed() bool
- func (b *Bar) Current() int64
- func (b *Bar) DecoratorAverageAdjust(start time.Time)
- func (b *Bar) DecoratorEwmaUpdate(dur 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) ProxyReader(r io.Reader) io.ReadCloser
- func (b *Bar) SetCurrent(current int64)
- func (b *Bar) SetPriority(priority int)
- func (b *Bar) SetRefill(amount int64)
- func (b *Bar) SetTotal(total int64, triggerComplete bool)
- func (b *Bar) TraverseDecorators(cb func(decor.Decorator))
- type BarFiller
- type BarFillerFunc
- type BarOption
- func AppendDecorators(decorators ...decor.Decorator) BarOption
- func BarExtender(filler BarFiller) BarOption
- func BarFillerClearOnComplete() BarOption
- func BarFillerMiddleware(middle func(BarFiller) BarFiller) BarOption
- func BarFillerOnComplete(message string) BarOption
- func BarFillerTrim() BarOption
- func BarID(id int) BarOption
- func BarNoPop() BarOption
- func BarOptOn(option BarOption, predicate func() bool) BarOption
- func BarOptional(option BarOption, pick bool) BarOption
- func BarPriority(priority int) BarOption
- func BarQueueAfter(runningBar *Bar) BarOption
- func BarRemoveOnComplete() BarOption
- func BarWidth(width int) BarOption
- func PrependDecorators(decorators ...decor.Decorator) BarOption
- type ContainerOption
- func ContainerOptOn(option ContainerOption, predicate func() bool) ContainerOption
- func ContainerOptional(option ContainerOption, pick bool) ContainerOption
- func PopCompletedMode() 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 struct{}) 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
- func (p *Progress) AddBar(total int64, options ...BarOption) *Bar
- func (p *Progress) AddSpinner(total int64, alignment SpinnerAlignment, options ...BarOption) *Bar
- func (p *Progress) BarCount() int
- func (p *Progress) UpdateBarPriority(b *Bar, priority int)
- func (p *Progress) Wait()
- type SpinnerAlignment
Examples ¶
Constants ¶
const BarDefaultStyle string = "[=>-]<+"
BarDefaultStyle is a style for rendering a progress bar. It consist of 7 ordered runes:
'1st rune' stands for left boundary rune '2nd rune' stands for fill rune '3rd rune' stands for tip rune '4th rune' stands for space rune '5th rune' stands for right boundary rune '6th rune' stands for reverse tip rune '7th rune' stands for refill rune
Variables ¶
var SpinnerDefaultStyle = []string{"⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"}
SpinnerDefaultStyle is a style for rendering a spinner.
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. Call this, if you'd like to stop/remove bar before completion event. It has no effect after completion event. If drop is true bar will be removed as well.
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) DecoratorEwmaUpdate ¶
DecoratorEwmaUpdate updates all EWMA based decorators. Should be called on each iteration, because EWMA's unit of measure is an iteration's duration. Panics if called before *Bar.Incr... family methods.
func (*Bar) ProxyReader ¶
func (b *Bar) ProxyReader(r io.Reader) io.ReadCloser
ProxyReader wraps r with metrics required for progress tracking. 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(ioutil.Discard, proxyReader) p.Wait()
Output:
func (*Bar) SetCurrent ¶
SetCurrent sets progress' current to an arbitrary value. Setting a negative value will cause a panic.
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 dynamically. If total is less than or equal to zero it takes progress' current value.
func (*Bar) TraverseDecorators ¶
TraverseDecorators traverses all available decorators and calls cb func on each.
type BarFiller ¶
type BarFiller interface {
Fill(w io.Writer, reqWidth int, stat decor.Statistics)
}
BarFiller interface. Bar (without decorators) renders itself by calling BarFiller's Fill method.
reqWidth is requested width, set by `func WithWidth(int) ContainerOption`. If not set, it defaults to terminal width.
Default implementations can be obtained via:
func NewBarFiller(style string) BarFiller func NewBarFillerRev(style string) BarFiller func NewBarFillerPick(style string, rev bool) BarFiller func NewSpinnerFiller(style []string, alignment SpinnerAlignment) BarFiller
func NewBarFiller ¶
NewBarFiller returns a BarFiller implementation which renders a progress bar in regular direction. If style is empty string, BarDefaultStyle is applied. To be used with `*Progress.Add(...) *Bar` method.
func NewBarFillerPick ¶
NewBarFillerPick pick between regular and reverse BarFiller implementation based on rev param. To be used with `*Progress.Add(...) *Bar` method.
func NewBarFillerRev ¶
NewBarFillerRev returns a BarFiller implementation which renders a progress bar in reverse direction. If style is empty string, BarDefaultStyle is applied. To be used with `*Progress.Add(...) *Bar` method.
func NewSpinnerFiller ¶
func NewSpinnerFiller(style []string, alignment SpinnerAlignment) BarFiller
NewSpinnerFiller returns a BarFiller implementation which renders a spinner. If style is nil or zero length, SpinnerDefaultStyle is applied. To be used with `*Progress.Add(...) *Bar` method.
type BarFillerFunc ¶
type BarFillerFunc func(w io.Writer, reqWidth int, stat decor.Statistics)
BarFillerFunc is function type adapter to convert function into BarFiller.
func (BarFillerFunc) Fill ¶
func (f BarFillerFunc) Fill(w io.Writer, reqWidth int, stat decor.Statistics)
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 provides a way to extend bar to the next new line.
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 BarNoPop ¶
func BarNoPop() BarOption
BarNoPop disables bar pop out of container. Effective when PopCompletedMode of container is enabled.
func BarOptOn ¶
BarOptOn will invoke provided option only when higher order predicate evaluates to true.
func BarOptional ¶
BarOptional will invoke provided option only when pick is true.
func BarPriority ¶
BarPriority sets bar's priority. Zero is highest priority, i.e. bar will be on top. If `BarReplaceOnComplete` option is supplied, this option is ignored.
func BarQueueAfter ¶
BarQueueAfter queues this (being constructed) bar to relplace runningBar after it has been completed.
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 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 ContainerOptOn ¶
func ContainerOptOn(option ContainerOption, predicate func() bool) ContainerOption
ContainerOptOn will invoke provided option only when higher order predicate evaluates to true.
func ContainerOptional ¶
func ContainerOptional(option ContainerOption, pick bool) ContainerOption
ContainerOptional will invoke provided option only when pick is true.
func PopCompletedMode ¶
func PopCompletedMode() ContainerOption
PopCompletedMode will pop and stop rendering completed bars.
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. Setting it to nil will effectively disable auto refresh rate and discard any output, useful if you want to disable progress bars with little overhead.
func WithRefreshRate ¶
func WithRefreshRate(d time.Duration) ContainerOption
WithRefreshRate overrides default 120ms 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 struct{}) ContainerOption
WithShutdownNotifier provided chanel will be closed, after all bars have been rendered.
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 filler. If `total <= 0` trigger complete event is disabled until reset with *bar.SetTotal(int64, bool). Panics if *Progress instance is done, i.e. called after *Progress.Wait().
func (*Progress) AddBar ¶
AddBar creates a bar with default bar filler. Different filler can be choosen and applied via `*Progress.Add(...) *Bar` method.
func (*Progress) AddSpinner ¶
func (p *Progress) AddSpinner(total int64, alignment SpinnerAlignment, options ...BarOption) *Bar
AddSpinner creates a bar with default spinner filler. Different filler can be choosen and applied via `*Progress.Add(...) *Bar` method.
func (*Progress) UpdateBarPriority ¶
UpdateBarPriority same as *Bar.SetPriority(int).
type SpinnerAlignment ¶
type SpinnerAlignment int
SpinnerAlignment enum.
const ( SpinnerOnLeft SpinnerAlignment = iota SpinnerOnMiddle SpinnerOnRight )
SpinnerAlignment kinds.
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/v6" module.
|
Package decor provides common decorators for "github.com/vbauerster/mpb/v6" module. |