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 Decoratros: 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 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()
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()
}
}()
}
// Wait for incr loop goroutines to finish,
// and shutdown mpb's rendering 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) 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 BeforeRender
- type Progress
- type ProgressOption
- func Output(w io.Writer) ProgressOption
- func OutputInterceptors(interseptors ...func(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 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 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 (
"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 BeforeRender ¶
type BeforeRender func([]*Bar)
BeforeRender is a func, which gets called before each rendering cycle
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(*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 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
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 100ms 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