README ¶
Multi Progress Bar for Go
Mutex free progress bar library, for console programs.
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
- Predefined Decoratros: Elapsed time, Ewmaest based ETA, Percentage, Bytes counter
Usage
Following is the simplest use case:
name := "Single bar:"
// Star mpb's rendering goroutine.
// If you don't plan to cancel, feed with nil
// otherwise provide context.Context, see cancel example
p := mpb.New(nil)
// Set custom format, the default one is "[=>-]"
p.Format("╢▌▌░╟")
bar := p.AddBar(100).PrependName(name, 0).AppendPercentage()
for i := 0; i < 100; i++ {
time.Sleep(time.Duration(rand.Intn(100)) * time.Millisecond)
bar.Incr(1)
}
p.Stop()
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(nil)
for i := 0; i < 3; i++ {
wg.Add(1) // add wg delta
name := fmt.Sprintf("Bar#%d:", i)
bar := p.AddBar(100).PrependName(name, len(name)).AppendPercentage()
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++ {
time.Sleep(time.Duration(rand.Intn(100)) * time.Millisecond)
bar.Incr(1)
}
}()
}
wg.Wait() // Wait for goroutines to finish
p.Stop() // Stop mpb's rendering goroutine
// p.AddBar(1) // panic: you cannot reuse p, create new one!
fmt.Println("finish")
The source code: example/simple/main.go
Cancel
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
Here is example from getparty src code.
Installation
$ go get -u github.com/vbauerster/mpb
License
The typeface used in screen shots: Iosevka
Documentation ¶
Index ¶
- Variables
- func Format(i int64) *formatter
- func IsClosed(ch <-chan struct{}) bool
- type Bar
- func (b *Bar) AppendETA(padding int) *Bar
- func (b *Bar) AppendElapsed() *Bar
- func (b *Bar) AppendFunc(f DecoratorFunc) *Bar
- func (b *Bar) AppendPercentage() *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) PrependCounters(unit Units, padding int) *Bar
- func (b *Bar) PrependETA(padding int) *Bar
- func (b *Bar) PrependElapsed(padding int) *Bar
- func (b *Bar) PrependFunc(f DecoratorFunc) *Bar
- func (b *Bar) PrependName(name string, padding int) *Bar
- func (b *Bar) PrependPercentage(padding int) *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()
- type Reader
- type Statistics
- type Units
Constants ¶
This section is empty.
Variables ¶
var ErrCallAfterStop = errors.New("method call on stopped Progress instance")
ErrCallAfterStop thrown by panic, if Progress methods like AddBar() are called after Stop() has been called
Functions ¶
func IsClosed ¶
func IsClosed(ch <-chan struct{}) bool
IsClosed check if ch closed caution see: http://www.tapirgames.com/blog/golang-channel-closing
Types ¶
type Bar ¶
type Bar struct {
// contains filtered or unexported fields
}
Bar represents a progress Bar
func (*Bar) AppendElapsed ¶
func (*Bar) AppendFunc ¶
func (b *Bar) AppendFunc(f DecoratorFunc) *Bar
AppendFunc appends DecoratorFunc
func (*Bar) AppendPercentage ¶
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) PrependETA ¶
func (*Bar) PrependElapsed ¶
func (*Bar) PrependFunc ¶
func (b *Bar) PrependFunc(f DecoratorFunc) *Bar
PrependFunc prepends DecoratorFunc
func (*Bar) PrependPercentage ¶
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) 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 ¶
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 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 Stop()
func (*Progress) BarCount ¶
BarCount returns bars count in the container. Pancis if called on stopped Progress instance, i.e after 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 Stop()
func (*Progress) RemoveBar ¶
RemoveBar removes bar at any time pancis, if called on stopped Progress instance, i.e after Stop()
func (*Progress) SetOut ¶
SetOut sets underlying writer of progress. Default is os.Stdout pancis, if called on stopped Progress instance, i.e after Stop()
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