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 is 80
p.SetWidth(100)
// 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++ {
time.Sleep(time.Duration(rand.Intn(100)) * time.Millisecond)
bar.Incr(1) // increment progress bar
}
// Don't forget to stop mpb's rendering goroutine
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()
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++ {
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
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.
Example ¶
package main
import (
"math/rand"
"time"
"github.com/vbauerster/mpb"
)
func main() {
// Star mpb's rendering goroutine.
p := mpb.New()
// Set custom width for every bar, which mpb will contain
// The default one is 80
p.SetWidth(100)
// 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++ {
time.Sleep(time.Duration(rand.Intn(100)) * time.Millisecond)
bar.Incr(1) // increment progress bar
}
// Don't forget to stop mpb's rendering goroutine
p.Stop()
}
Output:
Index ¶
- Constants
- 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) Complete()
- func (b *Bar) Completed()
- func (b *Bar) Format(format string) *Bar
- func (b *Bar) GetID() int
- func (b *Bar) GetStatistics() *Statistics
- func (b *Bar) InProgress() bool
- func (b *Bar) Incr(n int)
- func (b *Bar) IncrWithReFill(n int, refill *Refill)
- 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(width int) *Progress
- func (p *Progress) ShutdownNotify(ch chan struct{}) *Progress
- func (p *Progress) Stop()
- func (p *Progress) WithCancel(ch <-chan struct{}) *Progress
- func (p *Progress) WithContext(ctx context.Context) *Progress
- type Reader
- type Refill
- 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 ¶
This section is empty.
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
Example ¶
package main
import (
"fmt"
"math/rand"
"sync"
"time"
"unicode/utf8"
"github.com/vbauerster/mpb"
)
func main() {
decor := func(s *mpb.Statistics, myWidth chan<- int, maxWidth <-chan int) string {
str := fmt.Sprintf("%3d/%3d", s.Current, s.Total)
// send width to Progress' goroutine
myWidth <- utf8.RuneCountInString(str)
// receive max width
max := <-maxWidth
return fmt.Sprintf(fmt.Sprintf("%%%ds", max+1), str)
}
totalItem := 100
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(int64(totalItem)).
PrependName(name, len(name), 0).
AppendFunc(decor)
go func() {
defer wg.Done()
for i := 0; i < totalItem; i++ {
time.Sleep(time.Duration(rand.Intn(totalItem)) * time.Millisecond)
bar.Incr(1)
}
}()
}
wg.Wait() // Wait for goroutines to finish
p.Stop() // Stop mpb's rendering goroutine
}
Output:
func (*Bar) Complete ¶
func (b *Bar) Complete()
Complete 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. If you don't call this method, it will be called implicitly, upon p.Stop() call.
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
Example ¶
package main
import (
"time"
"github.com/vbauerster/mpb"
)
func main() {
p := mpb.New()
bar := p.AddBar(100).AppendPercentage(5, 0)
for bar.InProgress() {
time.Sleep(time.Millisecond * 20)
bar.Incr(1)
}
}
Output:
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
Example ¶
package main
import (
"fmt"
"math/rand"
"sync"
"time"
"unicode/utf8"
"github.com/vbauerster/mpb"
)
func main() {
decor := func(s *mpb.Statistics, myWidth chan<- int, maxWidth <-chan int) string {
str := fmt.Sprintf("%3d/%3d", s.Current, s.Total)
// send width to Progress' goroutine
myWidth <- utf8.RuneCountInString(str)
// receive max width
max := <-maxWidth
return fmt.Sprintf(fmt.Sprintf("%%%ds", max+1), str)
}
totalItem := 100
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(int64(totalItem)).
PrependName(name, len(name), 0).
PrependFunc(decor)
go func() {
defer wg.Done()
for i := 0; i < totalItem; i++ {
time.Sleep(time.Duration(rand.Intn(totalItem)) * time.Millisecond)
bar.Incr(1)
}
}()
}
wg.Wait() // Wait for goroutines to finish
p.Stop() // Stop mpb's rendering goroutine
}
Output:
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) AddBarWithID ¶
AddBarWithID creates a new progress bar and adds to the container.
func (*Progress) BeforeRenderFunc ¶
func (p *Progress) BeforeRenderFunc(f BeforeRender) *Progress
BeforeRenderFunc accepts a func, which gets called before render process.
func (*Progress) RefreshRate ¶
RefreshRate overrides default (100ms) refresh rate value
func (*Progress) ShutdownNotify ¶
ShutdownNotify means to be notified when main rendering goroutine quits, usualy after p.Stop() call.
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. You have to call p.Stop() anyway, after cancel. Pancis, if nil channel is passed.
type Refill ¶
type Refill struct {
Char rune
// contains filtered or unexported fields
}
Refil is a struct for b.IncrWithReFill
type Statistics ¶
type Statistics struct {
ID int
Completed bool
Aborted bool
Total int64
Current int64
StartTime time.Time
TimeElapsed time.Duration
TimePerItemEstimate time.Duration
}
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
Source Files
Directories