README ¶
Multi Progress Bar
mpb is a Go lib for rendering progress bars in terminal applications.
It is inspired by uiprogress library, but unlike the last one, implementation is mutex free, following Go's idiom:
Don't communicate by sharing memory, share memory by communicating.
Features
- Multiple Bars: mpb can render multiple progress bars that can be tracked concurrently
- Cancellable: cancel rendering goroutine at any time
- Dynamic Addition: Add additional progress bar at any time
- Dynamic Removal: Remove rendering progress bar at any time
- Dynamic Sorting: Sort bars as you wish
- Dynamic Resize: Resize bars on terminal width change
- Custom Decorator Functions: Add custom functions around the bar along with helper functions
- Dynamic Decorator's Width Sync: Sync width among decorator group (available since v2)
- Predefined Decoratros: Elapsed time, Ewmaest based ETA, Percentage, Bytes counter
Installation
To get the package, execute:
go get gopkg.in/vbauerster/mpb.v2
Usage
Following is the simplest use case:
// Star mpb's rendering goroutine.
p := mpb.New()
// Set custom width for every bar, which mpb will render
// The default one in 70
p.SetWidth(80)
// Set custom format for every bar, the default one is "[=>-]"
p.Format("╢▌▌░╟")
// Set custom refresh rate, the default one is 100 ms
p.RefreshRate(120 * time.Millisecond)
// Add a bar. You're not limited to just one bar, add many if you need.
bar := p.AddBar(100).PrependName("Single Bar:", 0, 0).AppendPercentage(5, 0)
for i := 0; i < 100; i++ {
bar.Incr(1) // increment progress bar
time.Sleep(time.Duration(rand.Intn(100)) * time.Millisecond)
}
// Don't forget to stop mpb's rendering goroutine
p.Stop()
// You cannot add bars after p.Stop() has been called
// p.AddBar(100) // will panic
Running this, will produce:
However mpb was designed with concurrency in mind. Each new bar renders in its own goroutine, therefore adding multiple bars is easy and safe:
var wg sync.WaitGroup
p := mpb.New()
wg.Add(3) // add wg delta
for i := 0; i < 3; i++ {
name := fmt.Sprintf("Bar#%d:", i)
bar := p.AddBar(100).
PrependName(name, len(name), 0).
// Prepend Percentage decorator and sync width
PrependPercentage(3, mpb.DwidthSync|mpb.DextraSpace).
// Append ETA and don't sync width
AppendETA(2, 0)
go func() {
defer wg.Done()
// you can p.AddBar() here, but ordering will be non deterministic
// if you still need p.AddBar() here and maintain ordering, use
// (*mpb.Progress).BeforeRenderFunc(f mpb.BeforeRender)
for i := 0; i < 100; i++ {
bar.Incr(1)
time.Sleep(time.Duration(rand.Intn(100)) * time.Millisecond)
}
}()
}
wg.Wait() // Wait for goroutines to finish
p.Stop() // Stop mpb's rendering goroutine
The source code: example/simple/main.go
Cancel
To cancel use either WithCancel or WithContext method. The last one requires Go 1.7
The source code: example/cancel/main.go
Removing bar
The source code: example/remove/main.go
Sorting bars by progress
The source code: example/sort/main.go
Resizing bars on terminal width change
The source code: example/prependETA/main.go
Multiple io
The source code: example/io/multiple/main.go
Custom Decorators
Refer to godoc example.
License
The typeface used in screen shots: Iosevka
Documentation ¶
Overview ¶
Package mpb is a library for rendering progress bars in terminal applications.
Index ¶
- Constants
- Variables
- func Format(i int64) *formatter
- type Bar
- func (b *Bar) AppendETA(minWidth int, conf byte) *Bar
- func (b *Bar) AppendElapsed(minWidth int, conf byte) *Bar
- func (b *Bar) AppendFunc(f DecoratorFunc) *Bar
- func (b *Bar) AppendPercentage(minWidth int, conf byte) *Bar
- func (b *Bar) Completed()
- func (b *Bar) Format(format string) *Bar
- func (b *Bar) GetAppenders() []DecoratorFunc
- func (b *Bar) GetID() int
- func (b *Bar) GetPrependers() []DecoratorFunc
- func (b *Bar) GetStatistics() *Statistics
- func (b *Bar) InProgress() bool
- func (b *Bar) Incr(n int)
- func (b *Bar) IncrWithReFill(n int, r rune)
- func (b *Bar) NumOfAppenders() int
- func (b *Bar) NumOfPrependers() int
- func (b *Bar) PrependCounters(pairFormat string, unit Units, minWidth int, conf byte) *Bar
- func (b *Bar) PrependETA(minWidth int, conf byte) *Bar
- func (b *Bar) PrependElapsed(minWidth int, conf byte) *Bar
- func (b *Bar) PrependFunc(f DecoratorFunc) *Bar
- func (b *Bar) PrependName(name string, minWidth int, conf byte) *Bar
- func (b *Bar) PrependPercentage(minWidth int, conf byte) *Bar
- func (b *Bar) ProxyReader(r io.Reader) *Reader
- func (b *Bar) RemoveAllAppenders()
- func (b *Bar) RemoveAllPrependers()
- func (b *Bar) SetEtaAlpha(a float64) *Bar
- func (b *Bar) SetWidth(n int) *Bar
- func (b *Bar) TrimLeftSpace() *Bar
- func (b *Bar) TrimRightSpace() *Bar
- type BeforeRender
- type DecoratorFunc
- type Progress
- func (p *Progress) AddBar(total int64) *Bar
- func (p *Progress) AddBarWithID(id int, total int64) *Bar
- func (p *Progress) BarCount() int
- func (p *Progress) BeforeRenderFunc(f BeforeRender) *Progress
- func (p *Progress) Format(format string) *Progress
- func (p *Progress) RefreshRate(d time.Duration) *Progress
- func (p *Progress) RemoveBar(b *Bar) bool
- func (p *Progress) SetOut(w io.Writer) *Progress
- func (p *Progress) SetWidth(n int) *Progress
- func (p *Progress) Stop()
- func (p *Progress) WithCancel(ch <-chan struct{}) *Progress
- func (p *Progress) WithContext(ctx context.Context) *Progress
- type Reader
- type Statistics
- type Units
Examples ¶
Constants ¶
const ( // DidentRight specifies identation direction. // | foo| b| Without DidentRight // |foo |b | With DidentRight DidentRight = 1 << iota // DwidthSync will auto sync max width DwidthSync // DextraSpace adds extra space, makes sence with DwidthSync only. // When DidentRight bit set, the space will be added to the right, // otherwise to the left. DextraSpace )
const (
UnitBytes
)
Variables ¶
var ErrCallAfterStop = errors.New("method call on stopped Progress instance")
ErrCallAfterStop thrown by panic, if Progress methods like (*Progress).AddBar() are called after (*Progress).Stop() has been called
Functions ¶
Types ¶
type Bar ¶
type Bar struct {
// contains filtered or unexported fields
}
Bar represents a progress Bar
func (*Bar) AppendFunc ¶
func (b *Bar) AppendFunc(f DecoratorFunc) *Bar
AppendFunc appends DecoratorFunc
func (*Bar) Completed ¶
func (b *Bar) Completed()
Completed signals to the bar, that process has been completed. You should call this method when total is unknown and you've reached the point of process completion.
func (*Bar) GetAppenders ¶
func (b *Bar) GetAppenders() []DecoratorFunc
GetAppenders returns slice of appender DecoratorFunc
func (*Bar) GetPrependers ¶
func (b *Bar) GetPrependers() []DecoratorFunc
GetPrependers returns slice of prepender DecoratorFunc
func (*Bar) GetStatistics ¶
func (b *Bar) GetStatistics() *Statistics
GetStatistics returs *Statistics, which contains information like Tottal, Current, TimeElapsed and TimePerItemEstimate
func (*Bar) InProgress ¶
InProgress returns true, while progress is running Can be used as condition in for loop
func (*Bar) IncrWithReFill ¶
IncrWithReFill increments pb with different fill character
func (*Bar) NumOfAppenders ¶
func (*Bar) NumOfPrependers ¶
func (*Bar) PrependCounters ¶
func (*Bar) PrependFunc ¶
func (b *Bar) PrependFunc(f DecoratorFunc) *Bar
PrependFunc prepends DecoratorFunc
func (*Bar) PrependName ¶
PrependName prepends name argument to the bar. The conf argument defines the formatting properties
func (*Bar) ProxyReader ¶
ProxyReader wrapper for io operations, like io.Copy
func (*Bar) RemoveAllAppenders ¶
func (b *Bar) RemoveAllAppenders()
RemoveAllAppenders removes all append functions
func (*Bar) RemoveAllPrependers ¶
func (b *Bar) RemoveAllPrependers()
RemoveAllPrependers removes all prepend functions
func (*Bar) SetEtaAlpha ¶
SetEtaAlpha sets alfa for exponential-weighted-moving-average ETA estimator Defaults to 0.25 Normally you shouldn't touch this
func (*Bar) TrimLeftSpace ¶
TrimLeftSpace removes space befor LeftEnd charater
func (*Bar) TrimRightSpace ¶
TrimRightSpace removes space after RightEnd charater
type BeforeRender ¶
type BeforeRender func([]*Bar)
BeforeRender is a func, which gets called before render process
type DecoratorFunc ¶
type DecoratorFunc func(s *Statistics, myWidth chan<- int, maxWidth <-chan int) string
DecoratorFunc is a function that can be prepended and appended to the progress bar
type Progress ¶
type Progress struct {
// contains filtered or unexported fields
}
Progress represents the container that renders Progress bars
func New ¶
func New() *Progress
New creates new Progress instance, which will orchestrate bars rendering process. It acceepts context.Context, for cancellation. If you don't plan to cancel, it is safe to feed with nil
func (*Progress) AddBar ¶
AddBar creates a new progress bar and adds to the container pancis, if called on stopped Progress instance, i.e after (*Progress).Stop()
func (*Progress) AddBarWithID ¶
AddBarWithID creates a new progress bar and adds to the container pancis, if called on stopped Progress instance, i.e after (*Progress).Stop()
func (*Progress) BarCount ¶
BarCount returns bars count in the container. Pancis if called on stopped Progress instance, i.e after (*Progress).Stop()
func (*Progress) BeforeRenderFunc ¶
func (p *Progress) BeforeRenderFunc(f BeforeRender) *Progress
BeforeRenderFunc accepts a func, which gets called before render process.
func (*Progress) Format ¶
Format sets custom format for underlying bar(s). The default one is "[=>-]"
func (*Progress) RefreshRate ¶
RefreshRate overrides default (100ms) refresh rate value pancis, if called on stopped Progress instance, i.e after (*Progress).Stop()
func (*Progress) RemoveBar ¶
RemoveBar removes bar at any time. Pancis, if called on stopped Progress instance, i.e after (*Progress).Stop()
func (*Progress) SetOut ¶
SetOut sets underlying writer of progress. Default is os.Stdout pancis, if called on stopped Progress instance, i.e after (*Progress).Stop()
func (*Progress) Stop ¶
func (p *Progress) Stop()
Stop shutdowns Progress' goroutine. Should be called only after each bar's work done, i.e. bar has reached its 100 %. It is NOT for cancelation. Use WithContext or WithCancel for cancelation purposes.
func (*Progress) WithCancel ¶
WithCancel cancellation via channel
type Statistics ¶
Statistics represents statistics of the progress bar. Cantains: Total, Current, TimeElapsed, TimePerItemEstimate
func (*Statistics) Eta ¶
func (s *Statistics) Eta() time.Duration
Eta returns exponential-weighted-moving-average ETA estimator