mpb

package module
v4.12.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 5, 2020 License: Unlicense Imports: 15 Imported by: 47

README

Multi Progress Bar

GoDoc Build Status Go Report Card

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

Usage

Rendering single bar
package main

import (
    "math/rand"
    "time"

    "github.com/vbauerster/mpb/v4"
    "github.com/vbauerster/mpb/v4/decor"
)

func main() {
    // initialize progress container, with custom width
    p := mpb.New(mpb.WithWidth(64))

    total := 100
    name := "Single Bar:"
    // adding a single bar, which will inherit container's width
    bar := p.AddBar(int64(total),
        // override DefaultBarStyle, which is "[=>-]<+"
        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)
        // since ewma decorator is used, we need to pass time.Since(start)
        bar.Increment(time.Since(start))
    }
    // wait for our bar to complete and flush
    p.Wait()
}
Rendering multiple bars
    var wg sync.WaitGroup
    // pass &wg (optional), so p will wait for it eventually
    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()
            rng := rand.New(rand.NewSource(time.Now().UnixNano()))
            max := 100 * time.Millisecond
            for i := 0; i < total; i++ {
                start := time.Now()
                time.Sleep(time.Duration(rng.Intn(10)+1) * max / 10)
                // since ewma decorator is used, we need to pass time.Since(start)
                bar.Increment(time.Since(start))
            }
        }()
    }
    // Waiting for passed &wg and for all bars to complete and flush
    p.Wait()
Dynamic total

dynamic total

Complex example

complex

Bytes counters

byte counters

Documentation

Overview

Package mpb is a library for rendering progress bars in terminal applications.

Example 
// initialize progress container, with custom width
p := mpb.New(mpb.WithWidth(64))

total := 100
name := "Single Bar:"
// adding a single bar, which will inherit container's width
bar := p.AddBar(int64(total),
	// override DefaultBarStyle, which is "[=>-]<+"
	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)
	// since ewma decorator is used, we need to pass time.Since(start)
	bar.Increment(time.Since(start))
}
// wait for our bar to complete and flush
p.Wait()

Output:

Index

Examples

Constants

View Source 
const DefaultBarStyle string = "[=>-]<+"

DefaultBarStyle is a string containing 7 runes. Each rune is a building block of a progress bar. 

'1st rune' stands for left boundary rune

'2nd rune' stands for fill rune

'3rd rune' stands for tip rune

'4th rune' stands for empty rune

'5th rune' stands for right boundary rune

'6th rune' stands for reverse tip rune

'7th rune' stands for refill rune

Variables

View Source 
var DefaultSpinnerStyle = []string{"⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"}

DefaultSpinnerStyle is a slice of strings, which makes a spinner.

Functions

This section is empty.

Types

type Bar 

type Bar struct {
	// contains filtered or unexported fields
}

Bar represents a progress Bar.

func (*Bar) Abort added in v4.6.0 

func (b *Bar) Abort(drop bool)

Abort interrupts bar's running goroutine. Call this, if you'd like to stop/remove bar before completion event. It has no effect after completion event. If drop is true bar will be removed as well.

func (*Bar) AdjustAverageDecorators added in v4.9.0 

func (b *Bar) AdjustAverageDecorators(startTime time.Time)

AdjustAverageDecorators updates start time of all average decorators. Useful for resume-able tasks.

func (*Bar) Completed 

func (b *Bar) Completed() bool

Completed reports whether the bar is in completed state.

Example 
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) Current 

func (b *Bar) Current() int64

Current returns bar's current number, in other words sum of all increments.

func (*Bar) ID 

func (b *Bar) ID() int

ID returs id of the bar.

func (*Bar) IncrBy 

func (b *Bar) IncrBy(n int, wdd ...time.Duration)

IncrBy is a shorthand for b.IncrInt64(int64(n), wdd...).

func (*Bar) IncrInt64 added in v4.7.0 

func (b *Bar) IncrInt64(n int64, wdd ...time.Duration)

IncrInt64 increments progress bar by amount of n. wdd is an optional work duration i.e. time.Since(start), which expected to be passed, if any ewma based decorator is used.

func (*Bar) Increment 

func (b *Bar) Increment(wdd ...time.Duration)

Increment is a shorthand for b.IncrInt64(1, wdd...).

func (*Bar) ProxyReader 

func (b *Bar) ProxyReader(r io.Reader) io.ReadCloser

ProxyReader wraps r with metrics required for progress tracking.

Example 
// import crand "crypto/rand"

var total int64 = 1024 * 1024 * 500
reader := io.LimitReader(crand.Reader, total)

p := mpb.New()
bar := p.AddBar(total,
	mpb.AppendDecorators(
		decor.CountersKibiByte("% .2f / % .2f"),
	),
)

// create proxy reader
proxyReader := bar.ProxyReader(reader)
defer proxyReader.Close()

// and copy from reader, ignoring errors
io.Copy(ioutil.Discard, proxyReader)

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.

func (*Bar) SetCurrent added in v4.4.0 

func (b *Bar) SetCurrent(current int64, wdd ...time.Duration)

SetCurrent sets progress' current to arbitrary amount.

func (*Bar) SetPriority added in v4.6.0 

func (b *Bar) SetPriority(priority int)

SetPriority changes bar's order among multiple bars. Zero is highest priority, i.e. bar will be on top. If you don't need to set priority dynamically, better use BarPriority option.

func (*Bar) SetRefill 

func (b *Bar) SetRefill(amount int64)

SetRefill sets refill, if supported by underlying Filler. Useful for resume-able tasks.

func (*Bar) SetTotal 

func (b *Bar) SetTotal(total int64, complete bool)

SetTotal sets total dynamically. Set complete to true, to trigger bar complete event now.

func (*Bar) TraverseDecorators added in v4.9.0 

func (b *Bar) TraverseDecorators(cb decor.CBFunc)

TraverseDecorators traverses all available decorators and calls cb func on each.

type BarOption 

type BarOption func(*bState)

BarOption is a function option which changes the default behavior of a bar.

func AppendDecorators 

func AppendDecorators(decorators ...decor.Decorator) BarOption

AppendDecorators let you inject decorators to the bar's right side.

func BarClearOnComplete 

func BarClearOnComplete() BarOption

BarClearOnComplete clears bar filler only, on complete event.

func BarExtender 

func BarExtender(extender Filler) BarOption

BarExtender is an option to extend bar to the next new line, with arbitrary output.

func BarID 

func BarID(id int) BarOption

BarID sets bar id.

func BarNoPop added in v4.8.4 

func BarNoPop() BarOption

BarNoPop disables bar pop out of container. Effective when PopCompletedMode of container is enabled.

func BarOnComplete added in v4.10.0 

func BarOnComplete(message string) BarOption

BarOnComplete replaces bar filler with message, on complete event.

func BarOptOn added in v4.12.1 

func BarOptOn(option BarOption, condition func() bool) BarOption

BarOptOn returns option when condition evaluates to true.

func BarParkTo added in v4.5.0 

func BarParkTo(runningBar *Bar) BarOption

BarParkTo parks constructed bar into the runningBar. In other words, constructed bar will replace runningBar after it has been completed.

func BarPriority 

func BarPriority(priority int) BarOption

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 removes bar filler and decorators if any, on complete event.

func BarReplaceOnComplete 

func BarReplaceOnComplete(runningBar *Bar) BarOption

BarReplaceOnComplete is deprecated. Use BarParkTo instead.

func BarReverse added in v4.3.0 

func BarReverse() BarOption

BarReverse reverse mode, bar will progress from right to left.

func BarStyle 

func BarStyle(style string) BarOption

BarStyle overrides mpb.DefaultBarStyle, for example BarStyle("╢▌▌░╟"). If you need to override `reverse tip` and `refill rune` set 6th and 7th rune respectively, for example BarStyle("[=>-]<+").

func BarWidth 

func BarWidth(width int) BarOption

BarWidth sets bar width independent of the container.

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 PrependDecorators 

func PrependDecorators(decorators ...decor.Decorator) BarOption

PrependDecorators let you inject decorators to the bar's left side.

func SpinnerStyle 

func SpinnerStyle(frames []string) BarOption

SpinnerStyle sets custom spinner style. Effective when Filler type is spinner.

func TrimSpace 

func TrimSpace() BarOption

TrimSpace trims bar's edge spaces.

type ContainerOption added in v4.1.0 

type ContainerOption func(*pState)

ContainerOption is a function option which changes the default behavior of progress container, if passed to mpb.New(...ContainerOption).

func ContainerOptOn added in v4.12.1 

func ContainerOptOn(option ContainerOption, condition func() bool) ContainerOption

ContainerOptOn returns option when condition evaluates to true.

func PopCompletedMode added in v4.8.4 

func PopCompletedMode() ContainerOption

PopCompletedMode will pop and stop rendering completed bars.

func WithDebugOutput 

func WithDebugOutput(w io.Writer) ContainerOption

WithDebugOutput sets debug output.

func WithManualRefresh 

func WithManualRefresh(ch <-chan time.Time) ContainerOption

WithManualRefresh disables internal auto refresh time.Ticker. Refresh will occur upon receive value from provided ch.

func WithOutput 

func WithOutput(w io.Writer) ContainerOption

WithOutput overrides default os.Stdout output. Setting it to nil will effectively disable auto refresh rate and discard any output, useful if you want to disable progress bars with little overhead.

func WithRefreshRate 

func WithRefreshRate(d time.Duration) ContainerOption

WithRefreshRate overrides default 120ms refresh rate.

func WithRenderDelay added in v4.11.0 

func WithRenderDelay(ch <-chan struct{}) ContainerOption

WithRenderDelay delays rendering. By default rendering starts as soon as bar is added, with this option it's possible to delay rendering process by keeping provided chan unclosed. In other words rendering will start as soon as provided chan is closed.

func WithShutdownNotifier 

func WithShutdownNotifier(ch chan struct{}) ContainerOption

WithShutdownNotifier provided chanel will be closed, after all bars have been rendered.

func WithWaitGroup 

func WithWaitGroup(wg *sync.WaitGroup) ContainerOption

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) ContainerOption

WithWidth sets container width. Default is 80. Bars inherit this width, as long as no BarWidth is applied.

type Filler 

type Filler interface {
	Fill(w io.Writer, width int, stat *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 *Progress.Add method.

func NewBarFiller added in v4.9.4 

func NewBarFiller(style string, reverse bool) Filler

NewBarFiller constucts mpb.Filler, to be used with *Progress.Add(...) *Bar method.

func NewSpinnerFiller added in v4.9.4 

func NewSpinnerFiller(style []string, alignment SpinnerAlignment) Filler

NewSpinnerFiller constucts mpb.Filler, to be used with *Progress.Add(...) *Bar 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 ...ContainerOption) *Progress

New creates new Progress container instance. It's not possible to reuse instance after *Progress.Wait() method has been called.

func NewWithContext added in v4.5.0 

func NewWithContext(ctx context.Context, options ...ContainerOption) *Progress

NewWithContext creates new Progress container instance with provided context. It's not possible to reuse instance after *Progress.Wait() method has been called.

func (*Progress) Add 

func (p *Progress) Add(total int64, filler Filler, options ...BarOption) *Bar

Add creates a bar which renders itself by provided filler. Set total to 0, if you plan to update it later. Panics if *Progress instance is done, i.e. called after *Progress.Wait().

func (*Progress) AddBar 

func (p *Progress) AddBar(total int64, options ...BarOption) *Bar

AddBar creates a new progress bar and adds it to the rendering queue.

func (*Progress) AddSpinner 

func (p *Progress) AddSpinner(total int64, alignment SpinnerAlignment, options ...BarOption) *Bar

AddSpinner creates a new spinner bar and adds it to the rendering queue.

func (*Progress) BarCount 

func (p *Progress) BarCount() int

BarCount returns bars count

func (*Progress) UpdateBarPriority 

func (p *Progress) UpdateBarPriority(b *Bar, priority int)

UpdateBarPriority same as *Bar.SetPriority.

func (*Progress) Wait 

func (p *Progress) Wait()

Wait waits far all bars to complete and finally shutdowns container. After this method has been called, there is no way to reuse *Progress instance.

type SpinnerAlignment 

type SpinnerAlignment int

SpinnerAlignment enum. 

const (
	SpinnerOnLeft SpinnerAlignment = iota
	SpinnerOnMiddle
	SpinnerOnRight
)

SpinnerAlignment kinds.

type WrapFiller added in v4.12.1 

type WrapFiller interface {
	Base() Filler
}

WrapFiller interface. If you're implementing custom Filler by wrapping a built-in one, it is necessary to implement this interface to retain functionality of built-in Filler.

Source Files

View all Source files

Directories

Path Synopsis
Package decor provides common decorators for "github.com/vbauerster/mpb/v4" module.
 Package decor provides common decorators for "github.com/vbauerster/mpb/v4" module.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.