mpb

package module
v3.4.0+incompatible Latest Latest
Warning

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

 Go to latest Published: Mar 19, 2019 License: BSD-3-Clause Imports: 16 Imported by: 0

README

Multi Progress Bar

GoDoc Build Status Go Report Card codecov

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

dynamic total

Complex example

complex

Bytes counters

byte 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

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 

func (b *Bar) Completed() bool

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

func (b *Bar) Increment()

Increment is a shorthand for b.IncrBy(1).

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.

func (*Bar) SetRefill 

func (b *Bar) SetRefill(amount int64)

SetRefill sets refill, if supported by underlying Filler.

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.

type BarOption 

type BarOption func(*bState)

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

func AppendDecorators 

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

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 BarID 

func BarID(id int) BarOption

BarID sets bar id.

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 BarParkTo 

func BarParkTo(runningBar *Bar) BarOption

BarParkTo same as BarReplaceOnComplete

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

func BarReplaceOnComplete(runningBar *Bar) BarOption

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 

func BarStyle(style string) BarOption

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 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 OptionOnCondition 

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

OptionOnCondition returns option when condition evaluates to true.

func PrependDecorators 

func PrependDecorators(prependers ...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 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 

func (p *Progress) Abort(b *Bar, remove bool)

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

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

Add creates a bar which renders itself by provided filler.

func (*Progress) AddBar 

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

AddBar creates a new progress bar and adds to the container.

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

func (p *Progress) BarCount() int

BarCount returns bars count

func (*Progress) UpdateBarPriority 

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

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 user provided *sync.WaitGroup, if any, then waits far all bars to complete and finally shutdowns master goroutine. After this method has been called, there is no way to reuse *Progress instance.

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

View all 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
barNewLineExtend
cancel
complex
differentWidth
dynTotal
io/multiple
io/single
panic
remove
simple
singleBar
sort
spinner
stress

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.