README
¶
Multi Progress Bar
mpb is a Go lib for rendering progress bars in terminal applications.
Features
- Multiple Bars: Multiple progress bars are supported
- Dynamic Total: Set total while bar is running
- Dynamic Addition: Additional bar could be added at later time
- Dynamic Removal: Remove particular bar, before or after completion
- Dynamic Resize: Adaptive bar resize (doesn't work inside tmux)
- Cancellation: Cancel whole rendering process
- Predefined Decorators: Elapsed time, Ewmaest based ETA, Percentage, Bytes counter
- Decorator's width sync: Synchronized decorator's width among multiple bars
Installation
go get github.com/vbauerster/mpb
Note: it is preferable to go get from github.com, rather than gopkg.in. See issue #11.
Usage
Rendering single bar
p := mpb.New(
// override default (80) width
mpb.WithWidth(100),
// override default "[=>-]" format
mpb.WithFormat("╢▌▌░╟"),
// override default 120ms refresh rate
mpb.WithRefreshRate(100*time.Millisecond),
)
total := 100
name := "Single Bar:"
// Add a bar
// You're not limited to just a single bar, add as many as you need
bar := p.AddBar(int64(total),
// Prepending decorators
mpb.PrependDecorators(
// StaticName decorator with minWidth and no extra config
// If you need to change name while rendering, use DynamicName
decor.StaticName(name, len(name), 0),
// ETA decorator with minWidth and no extra config
decor.ETA(4, 0),
),
// Appending decorators
mpb.AppendDecorators(
// Percentage decorator with minWidth and no extra config
decor.Percentage(5, 0),
),
)
for i := 0; i < total; i++ {
time.Sleep(time.Duration(rand.Intn(10)+1) * time.Second / 100)
bar.Increment()
}
// Gracefully shutdown mpb's monitor goroutine
p.Stop()
Rendering multiple bars
var wg sync.WaitGroup
p := mpb.New(mpb.WithWaitGroup(&wg))
total := 100
numBars := 3
wg.Add(numBars)
for i := 0; i < numBars; i++ {
name := fmt.Sprintf("Bar#%d:", i)
bar := p.AddBar(int64(total),
mpb.PrependDecorators(
decor.StaticName(name, 0, 0),
// DSyncSpace is shortcut for DwidthSync|DextraSpace
// means sync the width of respective decorator's column
// and prepend one extra space.
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(10)+1) * time.Second / 100)
bar.Increment()
}
}()
}
// Gracefully shutdown mpb's monitor goroutine
p.Stop()
Dynamic Total
Adaptive resize
Note: don't expect much, it corrupts if resizing too fast.
Bytes counter decorator
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 a single bar, add as many as you need
bar := p.AddBar(int64(total),
// Prepending decorators
mpb.PrependDecorators(
// StaticName decorator with minWidth and no extra config
// If you need to change name while rendering, use DynamicName
decor.StaticName(name, len(name), 0),
// ETA decorator with minWidth and no extra config
decor.ETA(4, 0),
),
// Appending decorators
mpb.AppendDecorators(
// Percentage decorator with minWidth and no extra config
decor.Percentage(5, 0),
),
)
for i := 0; i < total; i++ {
time.Sleep(time.Duration(rand.Intn(10)+1) * time.Second / 100)
bar.Increment()
}
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) IncrBy(n int)
- func (b *Bar) Increment()
- 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) SetTotal(total int64, final bool)
- func (b *Bar) Total() int64
- type BarOption
- func AppendDecorators(appenders ...decor.DecoratorFunc) BarOption
- func BarAutoIncrTotal(trigger, amount int64) BarOption
- func BarDynamicTotal() BarOption
- func BarEtaAlpha(a float64) BarOption
- func BarID(id int) BarOption
- func BarTrim() BarOption
- func BarTrimLeft() BarOption
- func BarTrimRight() BarOption
- func PrependDecorators(prependers ...decor.DecoratorFunc) BarOption
- type Progress
- type ProgressOption
- func Output(w io.Writer) ProgressOption
- func OutputInterceptors(interseptors ...func(io.Writer)) 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 WithWaitGroup(wg *sync.WaitGroup) 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 stops bar's progress tracking, but doesn't remove the bar. If you need to remove, call Progress.RemoveBar(*Bar) instead.
func (*Bar) InProgress ¶
InProgress returns true, while progress is running. Can be used as condition in for loop
Example ¶
package main
import (
"math/rand"
"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.Duration(rand.Intn(10)+1) * time.Second / 100)
bar.Increment()
}
}
Output:
func (*Bar) NumOfAppenders ¶
NumOfAppenders returns current number of append decorators
func (*Bar) NumOfPrependers ¶
NumOfPrependers returns current number of prepend decorators
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(*bState)
BarOption is a function option which changes the default behavior of a bar, if passed to p.AddBar(int64, ...BarOption)
func AppendDecorators ¶
func AppendDecorators(appenders ...decor.DecoratorFunc) BarOption
AppendDecorators let you inject decorators to the bar's right side
func BarAutoIncrTotal ¶
BarAutoIncrTotal auto increment total by amount, when trigger percentage remained till bar completion. In other words: say you've set trigger = 10, then auto increment will start after bar reaches 90 %.
func BarDynamicTotal ¶
func BarDynamicTotal() BarOption
BarDynamicTotal enables dynamic total behaviour.
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 PrependDecorators ¶
func PrependDecorators(prependers ...decor.DecoratorFunc) BarOption
PrependDecorators let you inject decorators to the bar's left side
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.
func (*Progress) Stop ¶
func (p *Progress) Stop()
Stop is a way to gracefully shutdown mpb's rendering goroutine. It is NOT for cancellation (use mpb.WithContext for cancellation purposes). If *sync.WaitGroup has been provided via mpb.WithWaitGroup(), its Wait() method will be called first.
func (*Progress) UpdateBarPriority ¶
UpdateBarPriority provides a way to change bar's order position. Zero is highest priority, i.e. bar will be on top.
type ProgressOption ¶
type ProgressOption func(*pState)
ProgressOption is a function option which changes the default behavior of progress pool, if passed to mpb.New(...ProgressOption)
func OutputInterceptors ¶
func OutputInterceptors(interseptors ...func(io.Writer)) ProgressOption
OutputInterceptors provides a way to write to the underlying progress pool's writer. Could be useful if you want to output something below the bars, while they're rendering.
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
WithContext provided context will be used for cancellation purposes
func WithFormat ¶
func WithFormat(format string) ProgressOption
WithFormat overrides default bar format "[=>-]"
func WithRefreshRate ¶
func WithRefreshRate(d time.Duration) ProgressOption
WithRefreshRate overrides default 120ms refresh rate
func WithShutdownNotifier ¶
func WithShutdownNotifier(ch chan struct{}) ProgressOption
WithShutdownNotifier provided chanel will be closed, inside p.Stop() call
func WithWaitGroup ¶
func WithWaitGroup(wg *sync.WaitGroup) ProgressOption
WithWaitGroup provides means to have a single joint point. If *sync.WaitGroup is provided, you can safely call just p.Stop() without calling Wait() on provided *sync.WaitGroup. Makes sense when there are more than one bar to render.
Source Files
Directories