mpb

package module
v3.3.0+incompatible Latest Latest
Warning

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

Go to latest
Published: Jun 17, 2018 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 "[=>-]" format
        mpb.WithFormat("╢▌▌░╟"),
        // override default 120ms refresh rate
        mpb.WithRefreshRate(180*time.Millisecond),
    )

    total := 100
    name := "Single Bar:"
    sbEta := make(chan time.Time)
    // 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.ETA(decor.ET_STYLE_GO, 60, sbEta, decor.WC{W: 4}), "done",
            ),
        ),
        mpb.AppendDecorators(decor.Percentage()),
    )
    // simulating some work
    max := 100 * time.Millisecond
    for i := 0; i < total; i++ {
        // update start block time, required for ETA calculation
        sbEta <- time.Now()
        time.Sleep(time.Duration(rand.Intn(10)+1) * max / 10)
        // increment by 1 (there is bar.IncrBy(int) method, if needed)
        bar.Increment()
    }
    // 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)
        sbEta := make(chan time.Time)
        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.ETA(decor.ET_STYLE_GO, 60, sbEta), "done",
                ),
            ),
        )
        // simulating some work
        go func() {
            defer wg.Done()
            max := 100 * time.Millisecond
            for i := 0; i < total; i++ {
                sbEta <- time.Now()
                time.Sleep(time.Duration(rand.Intn(10)+1) * max / 10)
                bar.Increment()
            }
        }()
    }
    // 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 "[=>-]" format
		mpb.WithFormat("╢▌▌░╟"),
		// override default 120ms refresh rate
		mpb.WithRefreshRate(180*time.Millisecond),
	)

	total := 100
	name := "Single Bar:"
	sbEta := make(chan time.Time)
	// 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.ETA(decor.ET_STYLE_GO, 60, sbEta, decor.WC{W: 4}), "done",
			),
		),
		mpb.AppendDecorators(decor.Percentage()),
	)
	// simulating some work
	max := 100 * time.Millisecond
	for i := 0; i < total; i++ {
		// update start block time, required for ETA calculation
		sbEta <- time.Now()
		time.Sleep(time.Duration(rand.Intn(10)+1) * max / 10)
		// increment by 1 (there is bar.IncrBy(int) method, if needed)
		bar.Increment()
	}
	// 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)

IncrBy increments progress bar by amount of n

func (*Bar) Increment

func (b *Bar) Increment()

Increment is a shorthand for b.IncrBy(1)

func (*Bar) NumOfAppenders

func (b *Bar) NumOfAppenders() int

NumOfAppenders returns current number of append decorators

func (*Bar) NumOfPrependers

func (b *Bar) NumOfPrependers() int

NumOfPrependers returns current number of prepend decorators

func (*Bar) ProxyReader

func (b *Bar) ProxyReader(r io.Reader, sbChannels ...chan<- time.Time) *Reader

ProxyReader wrapper for io operations, like io.Copy

`r` io.Reader to be wrapped

`sbChannels` optional start block channels
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) ResumeFill

func (b *Bar) ResumeFill(r rune, till int64)

ResumeFill fills bar with different r rune, from 0 to till amount of progress.

func (*Bar) SetTotal

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

SetTotal sets total dynamically. The final param indicates the very last set, in other words you should set it to true when total is determined.

func (*Bar) Total

func (b *Bar) Total() int64

Total returns bar's total number.

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.Decorator) BarOption

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

func BarAutoIncrTotal

func BarAutoIncrTotal(trigger, n int64) BarOption

BarAutoIncrTotal auto increment total by n, 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 %. Effective only if BarDynamicTotal option is set.

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 BarDynamicTotal

func BarDynamicTotal() BarOption

BarDynamicTotal is a flag, if set enables dynamic total behaviour. If provided total <= 0, it is set implicitly.

func BarID

func BarID(id int) BarOption

BarID overwrites internal bar id

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 BarTrim

func BarTrim() BarOption

BarTrim trims both left and right spaces of the bar

func BarTrimLeft

func BarTrimLeft() BarOption

BarTrimLeft trims left side space of the bar

func BarTrimRight

func BarTrimRight() BarOption

BarTrimRight trims right space of the bar

func PrependDecorators

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

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

func (p *Progress) Abort(b *Bar)

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

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

AddBar creates a new progress 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 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 WithInterceptors

func WithInterceptors(interseptors ...func(io.Writer)) ProgressOption

WithInterceptors 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 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 overrides default width 80

type Reader

type Reader struct {
	io.Reader
	// contains filtered or unexported fields
}

Reader is io.Reader wrapper, for proxy read bytes

func (*Reader) Close

func (r *Reader) Close() error

Close the reader when it implements io.Closer

func (*Reader) Read

func (r *Reader) Read(p []byte) (int, error)

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL