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),
),
)
max := 200 * time.Millisecond
for i := 0; i < total; i++ {
time.Sleep(time.Duration(rand.Intn(10)+1) * max / 10)
bar.Increment()
}
// Wait for all bars to complete
p.Wait()
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(3, 0),
),
)
go func() {
defer wg.Done()
max := 200 * time.Millisecond
for i := 0; i < total; i++ {
time.Sleep(time.Duration(rand.Intn(10)+1) * max / 10)
bar.Increment()
}
}()
}
// Wait for all bars to complete
p.Wait()
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 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),
),
)
max := 200 * time.Millisecond
for i := 0; i < total; i++ {
time.Sleep(time.Duration(rand.Intn(10)+1) * max / 10)
bar.Increment()
}
// Wait for all bars to complete
p.Wait()
}
Output:
Index ¶
- type Bar
- func (b *Bar) Complete()
- func (b *Bar) Completed() bool
- func (b *Bar) Current() int64
- func (b *Bar) ID() 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 from rendering queue. If you need to remove, invoke Progress.RemoveBar(*Bar) instead.
func (*Bar) Completed ¶
Completed reports whether the bar is in completed state
Example ¶
package main
import (
"math/rand"
"time"
"github.com/vbauerster/mpb"
)
func main() {
p := mpb.New()
bar := p.AddBar(100)
max := 200 * time.Millisecond
for !bar.Completed() {
time.Sleep(time.Duration(rand.Intn(10)+1) * max / 10)
bar.Increment()
}
p.Wait()
}
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) UpdateBarPriority ¶
UpdateBarPriority provides a way to change bar's order position. Zero is highest priority, i.e. bar will be on top.
func (*Progress) Wait ¶
func (p *Progress) Wait()
Wait first waits for all bars to complete, then waits for user provided WaitGroup, if any. It's optional to call, in other words if you don't call Progress.Wait(), it's not guaranteed that all bars will be flushed completely to the underlying io.Writer.
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, after all bars have been rendered.
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.Wait() without calling Wait() on provided *sync.WaitGroup. Makes sense when there are more than one bar to render.
Source Files
Directories