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 120ms refresh rate
mpb.WithRefreshRate(180*time.Millisecond),
)
total := 100
name := "Single Bar:"
// adding a single bar
bar := p.AddBar(int64(total),
// override default "[=>-]" style
mpb.BarStyle("╢▌▌░╟"),
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.
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(64),
// override default 120ms refresh rate
mpb.WithRefreshRate(180*time.Millisecond),
)
total := 100
name := "Single Bar:"
// adding a single bar
bar := p.AddBar(int64(total),
// override default "[=>-]" style
mpb.BarStyle("╢▌▌░╟"),
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()
}
Output:
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.ReadCloser
- func (b *Bar) RemoveAllAppenders()
- func (b *Bar) RemoveAllPrependers()
- func (b *Bar) SetRefill(amount int64)
- func (b *Bar) SetTotal(total int64, complete 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 BarParkTo(runningBar *Bar) BarOption
- func BarPriority(priority int) BarOption
- func BarRemoveOnComplete() BarOption
- func BarReplaceOnComplete(runningBar *Bar) BarOption
- func BarReverse() BarOption
- func BarStyle(style string) BarOption
- func BarWidth(width int) BarOption
- func MakeFillerTypeSpecificBarOption(typeChecker func(Filler) (interface{}, bool), cb func(interface{})) BarOption
- func OptionOnCondition(option BarOption, condition func() bool) BarOption
- func PrependDecorators(prependers ...decor.Decorator) BarOption
- func SpinnerStyle(frames []string) BarOption
- func TrimSpace() BarOption
- type Filler
- type FillerFunc
- type Progress
- func (p *Progress) Abort(b *Bar, remove bool)
- func (p *Progress) Add(total int64, filler Filler, options ...BarOption) *Bar
- func (p *Progress) AddBar(total int64, options ...BarOption) *Bar
- func (p *Progress) AddSpinner(total int64, alignment SpinnerAlignment, options ...BarOption) *Bar
- func (p *Progress) BarCount() int
- func (p *Progress) UpdateBarPriority(b *Bar, priority int)
- func (p *Progress) Wait()
- type ProgressOption
- func WithContext(ctx context.Context) ProgressOption
- func WithDebugOutput(w io.Writer) 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
- type SpinnerAlignment
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) 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 := 100 * time.Millisecond
for !bar.Completed() {
time.Sleep(time.Duration(rand.Intn(10)+1) * max / 10)
bar.Increment()
}
p.Wait()
}
Output:
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 ¶
func (b *Bar) ProxyReader(r io.Reader) io.ReadCloser
ProxyReader wraps r with metrics required for progress tracking.
Example ¶
package main
import (
"io"
"io/ioutil"
"net/http"
"github.com/vbauerster/mpb"
"github.com/vbauerster/mpb/decor"
)
func main() {
p := mpb.New()
// make http get request, ignoring errors
resp, _ := http.Get("https://homebrew.bintray.com/bottles/libtiff-4.0.7.sierra.bottle.tar.gz")
defer resp.Body.Close()
// Assuming ContentLength > 0
bar := p.AddBar(resp.ContentLength,
mpb.AppendDecorators(
decor.CountersKibiByte("%6.1f / %6.1f"),
),
)
// create proxy reader
reader := bar.ProxyReader(resp.Body)
// and copy from reader, ignoring errors
io.Copy(ioutil.Discard, reader)
p.Wait()
}
Output:
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.
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 BarReverse ¶
func BarReverse() BarOption
BarReverse reverse mode, bar will progress from right to left.
func BarStyle ¶
BarStyle sets custom bar style, default one is "[=>-]<+".
'[' left bracket rune '=' fill rune '>' tip rune '-' empty rune ']' right bracket rune '<' reverse tip rune, used when BarReverse option is set '+' refill rune, used when *Bar.SetRefill(int64) is called
It's ok to provide first five runes only, for example mpb.BarStyle("╢▌▌░╟")
func MakeFillerTypeSpecificBarOption ¶
func MakeFillerTypeSpecificBarOption( typeChecker func(Filler) (interface{}, bool), cb func(interface{}), ) BarOption
MakeFillerTypeSpecificBarOption makes BarOption specific to Filler's actual type. If you implement your own Filler, so most probably you'll need this. See BarStyle or SpinnerStyle for example.
func OptionOnCondition ¶
OptionOnCondition returns option when condition evaluates to true.
func PrependDecorators ¶
PrependDecorators let you inject decorators to the bar's left side.
func SpinnerStyle ¶
SpinnerStyle sets custom spinner style. Effective when Filler type is spinner.
type Filler ¶
type Filler interface {
Fill(w io.Writer, width int, s *decor.Statistics)
}
Filler interface. Bar renders by calling Filler's Fill method. You can literally have any bar kind, by implementing this interface and passing it to the Add method.
type FillerFunc ¶
type FillerFunc func(w io.Writer, width int, stat *decor.Statistics)
FillerFunc is function type adapter to convert function into Filler.
func (FillerFunc) Fill ¶
func (f FillerFunc) Fill(w io.Writer, width int, stat *decor.Statistics)
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) AddSpinner ¶
func (p *Progress) AddSpinner(total int64, alignment SpinnerAlignment, options ...BarOption) *Bar
AddSpinner creates a new spinner bar and adds to the container.
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 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 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.
func WithWidth ¶
func WithWidth(w int) ProgressOption
WithWidth sets container width. Default is 80. Bars inherit this width, as long as no BarWidth is applied.
type SpinnerAlignment ¶
type SpinnerAlignment int
SpinnerAlignment enum.
const ( SpinnerOnLeft SpinnerAlignment = iota SpinnerOnMiddle SpinnerOnRight )
SpinnerAlignment kinds.
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
|
|