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.v3
Usage
Following is the simplest use case:
p := mpb.New(
// override default (80) width
mpb.WithWidth(100),
// override default "[=>-]" format
mpb.WithFormat("╢▌▌░╟"),
// override default 100ms refresh rate
mpb.WithRefreshRate(120*time.Millisecond),
)
total := 100
name := "Single Bar:"
// Add a bar. You're not limited to just one bar, add many if you need.
bar := p.AddBar(int64(total),
// Prepending decorators
mpb.PrependDecorators(
// Name decorator with minWidth and no width sync options
decor.Name(name, len(name), 0),
// ETA decorator with minWidth and width sync options DwidthSync|DextraSpace
decor.ETA(4, decor.DSyncSpace),
),
// Appending decorators
mpb.AppendDecorators(
// Percentage decorator with minWidth and no width sync options
decor.Percentage(5, 0),
),
)
for i := 0; i < total; i++ {
time.Sleep(time.Duration(rand.Intn(100)) * time.Millisecond)
bar.Incr(1) // increment progress bar
}
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:
p := mpb.New()
total := 100
numBars := 3
var wg sync.WaitGroup
wg.Add(numBars)
for i := 0; i < numBars; i++ {
name := fmt.Sprintf("Bar#%d:", i)
bar := p.AddBar(int64(total),
mpb.PrependDecorators(
decor.Name(name, len(name), 0),
decor.Percentage(3, decor.DSyncSpace),
),
mpb.AppendDecorators(
decor.ETA(2, 0),
),
)
go func() {
defer wg.Done()
for i := 0; i < total; 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: examples/simple/main.go
Cancel
The source code: examples/cancel/main.go
Removing bar
The source code: examples/remove/main.go
Sorting bars by progress
The source code: examples/sort/main.go
Resizing bars on terminal width change
The source code: examples/prependETA/main.go
Multiple io
The source code: examples/io/multiple/main.go
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"
"github.com/vbauerster/mpb/decor"
)
func main() {
p := mpb.New(
// override default (80) width
mpb.WithWidth(100),
// override default "[=>-]" format
mpb.WithFormat("╢▌▌░╟"),
// override default 100ms refresh rate
mpb.WithRefreshRate(120*time.Millisecond),
)
total := 100
name := "Single Bar:"
// Add a bar. You're not limited to just one bar, add many if you need.
bar := p.AddBar(int64(total),
// Prepending decorators
mpb.PrependDecorators(
// Name decorator with minWidth and no width sync options
decor.Name(name, len(name), 0),
// ETA decorator with minWidth and width sync options DwidthSync|DextraSpace
decor.ETA(4, decor.DSyncSpace),
),
// Appending decorators
mpb.AppendDecorators(
// Percentage decorator with minWidth and no width sync options
decor.Percentage(5, 0),
),
)
for i := 0; i < total; i++ {
time.Sleep(time.Duration(rand.Intn(100)) * time.Millisecond)
bar.Incr(1) // increment progress bar
}
p.Stop()
}
Output:
Index ¶
- type Bar
- func (b *Bar) Complete()
- func (b *Bar) Current() int64
- func (b *Bar) ID() int
- func (b *Bar) InProgress() bool
- func (b *Bar) Incr(n int)
- func (b *Bar) NumOfAppenders() int
- func (b *Bar) NumOfPrependers() int
- func (b *Bar) ProxyReader(r io.Reader) *Reader
- func (b *Bar) RemoveAllAppenders()
- func (b *Bar) RemoveAllPrependers()
- func (b *Bar) ResumeFill(r rune, till int64)
- func (b *Bar) Total() int64
- type BarOption
- type BeforeRender
- type Progress
- type ProgressOption
- func Output(w io.Writer) ProgressOption
- func WithBeforeRenderFunc(f BeforeRender) ProgressOption
- func WithCancel(ch <-chan struct{}) ProgressOption
- func WithContext(ctx context.Context) ProgressOption
- func WithFormat(format string) ProgressOption
- func WithRefreshRate(d time.Duration) ProgressOption
- func WithShutdownNotifier(ch chan struct{}) ProgressOption
- func WithWidth(w int) ProgressOption
- type Reader
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Bar ¶
type Bar struct {
// contains filtered or unexported fields
}
Bar represents a progress Bar
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) 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"
"github.com/vbauerster/mpb/decor"
)
func main() {
p := mpb.New()
bar := p.AddBar(100, mpb.AppendDecorators(decor.Percentage(5, 0)))
for bar.InProgress() {
time.Sleep(time.Millisecond * 20)
bar.Incr(1)
}
}
Output:
func (*Bar) NumOfAppenders ¶
func (*Bar) NumOfPrependers ¶
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) ResumeFill ¶
ResumeFill fills bar with different r rune, from 0 to till amount of progress.
type BarOption ¶
type BarOption func(*state)
func AppendDecorators ¶
func AppendDecorators(appenders ...decor.DecoratorFunc) BarOption
func BarEtaAlpha ¶
BarEtaAlpha option is a way to adjust ETA behavior. You can play with it, if you're not satisfied with default behavior. Default value is 0.25.
func BarTrimLeft ¶
func BarTrimLeft() BarOption
func BarTrimRight ¶
func BarTrimRight() BarOption
func PrependDecorators ¶
func PrependDecorators(prependers ...decor.DecoratorFunc) BarOption
type BeforeRender ¶
type BeforeRender func([]*Bar)
BeforeRender is a func, which gets called before render process
type Progress ¶
type Progress struct {
// contains filtered or unexported fields
}
Progress represents the container that renders Progress bars
func New ¶
func New(options ...ProgressOption) *Progress
New creates new Progress instance, which orchestrates bars rendering process. Accepts mpb.ProgressOption funcs for customization.
type ProgressOption ¶
type ProgressOption func(*pConf)
func WithBeforeRenderFunc ¶
func WithBeforeRenderFunc(f BeforeRender) ProgressOption
WithBeforeRenderFunc provided BeforeRender func, will be called before each render cycle.
func WithCancel ¶
func WithCancel(ch <-chan struct{}) ProgressOption
WithCancel provide your cancel channel, which you plan to close at some point.
func WithContext ¶
func WithContext(ctx context.Context) ProgressOption
func WithFormat ¶
func WithFormat(format string) ProgressOption
WithFormat overrides default bar format "[=>-]"
func WithRefreshRate ¶
func WithRefreshRate(d time.Duration) ProgressOption
WithRefreshRate overrides default 100ms refresh rate
func WithShutdownNotifier ¶
func WithShutdownNotifier(ch chan struct{}) ProgressOption
WithShutdownNotifier provided chanel will be closed, inside p.Stop() call
Source Files
Directories