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 Add/Remove: Dynamically add or remove bars
- Cancellation: Cancel whole rendering process
- Predefined Decorators: Elapsed time, ewma 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(64),
// override default "[=>-]" format
mpb.WithFormat("╢▌▌░╟"),
// override default 120ms refresh rate
mpb.WithRefreshRate(180*time.Millisecond),
)
total := 100
name := "Single Bar:"
// adding a single bar
bar := p.AddBar(int64(total),
mpb.PrependDecorators(
// display our name with one space on the right
decor.Name(name, decor.WC{W: len(name) + 1, C: decor.DidentRight}),
// replace ETA decorator with "done" message, OnComplete event
decor.OnComplete(
// ETA decorator with ewma age of 60, and width reservation of 4
decor.EwmaETA(decor.ET_STYLE_GO, 60, decor.WC{W: 4}), "done",
),
),
mpb.AppendDecorators(decor.Percentage()),
)
// simulating some work
max := 100 * time.Millisecond
for i := 0; i < total; i++ {
start := time.Now()
time.Sleep(time.Duration(rand.Intn(10)+1) * max / 10)
// ewma based decorators require work duration measurement
bar.IncrBy(1, time.Since(start))
}
// wait for our bar to complete and flush
p.Wait()
Rendering multiple bars
var wg sync.WaitGroup
p := mpb.New(mpb.WithWaitGroup(&wg))
total, numBars := 100, 3
wg.Add(numBars)
for i := 0; i < numBars; i++ {
name := fmt.Sprintf("Bar#%d:", i)
bar := p.AddBar(int64(total),
mpb.PrependDecorators(
// simple name decorator
decor.Name(name),
// decor.DSyncWidth bit enables column width synchronization
decor.Percentage(decor.WCSyncSpace),
),
mpb.AppendDecorators(
// replace ETA decorator with "done" message, OnComplete event
decor.OnComplete(
// ETA decorator with ewma age of 60
decor.EwmaETA(decor.ET_STYLE_GO, 60), "done",
),
),
)
// simulating some work
go func() {
defer wg.Done()
max := 100 * time.Millisecond
for i := 0; i < total; i++ {
start := time.Now()
time.Sleep(time.Duration(rand.Intn(10)+1) * max / 10)
// ewma based decorators require work duration measurement
bar.IncrBy(1, time.Since(start))
}
}()
}
// wait for all bars to complete and flush
p.Wait()
Dynamic total
Complex example
Bytes counters
Documentation ¶
Overview ¶
Package mpb is a library for rendering progress bars in terminal applications.
Index ¶
- type Bar
- func (b *Bar) Completed() bool
- func (b *Bar) Current() int64
- func (b *Bar) ID() int
- func (b *Bar) IncrBy(n int, wdd ...time.Duration)
- func (b *Bar) Increment()
- func (b *Bar) ProxyReader(r io.Reader) io.Reader
- func (b *Bar) RefillBy(n int, r rune)
- func (b *Bar) RemoveAllAppenders()
- func (b *Bar) RemoveAllPrependers()
- func (b *Bar) SetRefill(n int, r rune)
- func (b *Bar) SetTotal(total int64, final bool)
- type BarOption
- func AppendDecorators(appenders ...decor.Decorator) BarOption
- func BarClearOnComplete() BarOption
- func BarID(id int) BarOption
- func BarNewLineExtend(efn func(io.Writer, *decor.Statistics)) BarOption
- func BarPriority(priority int) BarOption
- func BarRemoveOnComplete() BarOption
- func BarReplaceOnComplete(runningBar *Bar) BarOption
- func BarTrim() BarOption
- func BarTrimLeft() BarOption
- func BarTrimRight() BarOption
- func PrependDecorators(prependers ...decor.Decorator) BarOption
- type Progress
- type ProgressOption
- func WithCancel(ch <-chan struct{}) ProgressOption
- func WithContext(ctx context.Context) ProgressOption
- func WithDebugOutput(w io.Writer) ProgressOption
- func WithFormat(format string) ProgressOption
- func WithManualRefresh(ch <-chan time.Time) ProgressOption
- func WithOutput(w io.Writer) ProgressOption
- func WithRefreshRate(d time.Duration) ProgressOption
- func WithShutdownNotifier(ch chan struct{}) ProgressOption
- func WithWaitGroup(wg *sync.WaitGroup) ProgressOption
- func WithWidth(w int) ProgressOption
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) IncrBy ¶
IncrBy increments progress bar by amount of n. wdd is optional work duration i.e. time.Since(start), which expected to be provided, if any ewma based decorator is used.
func (*Bar) ProxyReader ¶
ProxyReader wraps r with metrics required for progress tracking.
func (*Bar) RemoveAllAppenders ¶
func (b *Bar) RemoveAllAppenders()
RemoveAllAppenders removes all append functions.
func (*Bar) RemoveAllPrependers ¶
func (b *Bar) RemoveAllPrependers()
RemoveAllPrependers removes all prepend functions.
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 ¶
AppendDecorators let you inject decorators to the bar's right side
func BarClearOnComplete ¶
func BarClearOnComplete() BarOption
BarClearOnComplete is a flag, if set will clear bar section on complete event. If you need to remove a whole bar line, refer to BarRemoveOnComplete.
func BarNewLineExtend ¶
func BarNewLineExtend(efn func(io.Writer, *decor.Statistics)) BarOption
BarNewLineExtend takes user defined efn, which gets called each render cycle. Any write to provided writer of efn, will appear on new line of respective bar.
func BarPriority ¶
BarPriority sets bar's priority. Zero is highest priority, i.e. bar will be on top. If `BarReplaceOnComplete` option is supplied, this option is ignored.
func BarRemoveOnComplete ¶
func BarRemoveOnComplete() BarOption
BarRemoveOnComplete is a flag, if set whole bar line will be removed on complete event. If both BarRemoveOnComplete and BarClearOnComplete are set, first bar section gets cleared and then whole bar line gets removed completely.
func BarReplaceOnComplete ¶
BarReplaceOnComplete is indicator for delayed bar start, after the `runningBar` is complete. To achieve bar replacement effect, `runningBar` should has its `BarRemoveOnComplete` option set.
func PrependDecorators ¶
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) Abort ¶
Abort is only effective while bar progress is running, it means remove bar now without waiting for its completion. If bar is already completed, there is nothing to abort. If you need to remove bar after completion, use BarRemoveOnComplete BarOption.
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 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 WithDebugOutput ¶
func WithDebugOutput(w io.Writer) ProgressOption
WithDebugOutput sets debug output.
func WithFormat ¶
func WithFormat(format string) ProgressOption
WithFormat overrides default bar format "[=>-]"
func WithManualRefresh ¶
func WithManualRefresh(ch <-chan time.Time) ProgressOption
WithManualRefresh disables internal auto refresh time.Ticker. Refresh will occur upon receive value from provided ch.
func WithOutput ¶
func WithOutput(w io.Writer) ProgressOption
WithOutput overrides default output os.Stdout
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 ¶
Path | Synopsis |
---|---|
Package decor contains common decorators used by "github.com/vbauerster/mpb" package.
|
Package decor contains common decorators used by "github.com/vbauerster/mpb" package. |
examples
|
|