mpb

package module
v1.1.2 Latest Latest
Warning

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

 Go to latest Published: Feb 18, 2017 License: MIT Imports: 12 Imported by: 0

README

Multi Progress Bar for Go Build Status

Mutex free progress bar library, for console programs.

It is inspired by uiprogress library, but unlike the last one, implementation is mutex free, following Go's idiom:

Don't communicate by sharing memory, share memory by communicating.

Features

  • Multiple Bars: mpb can render multiple progress bars that can be tracked concurrently
  • Cancellable: cancel rendering goroutine at any time
  • Dynamic Addition: Add additional progress bar at any time
  • Dynamic Removal: Remove rendering progress bar at any time
  • Dynamic Sorting: Sort bars as you wish
  • Dynamic Resize: Resize bars on terminal width change
  • Custom Decorator Functions: Add custom functions around the bar along with helper functions
  • Predefined Decoratros: Elapsed time, Ewmaest based ETA, Percentage, Bytes counter

Usage

Following is the simplest use case:

	name := "Single bar:"
	// Star mpb's rendering goroutine.
	// If you don't plan to cancel, feed with nil
	// otherwise provide context.Context, see cancel example
	p := mpb.New(nil)
	// Set custom format, the default one is "[=>-]"
	p.Format("╢▌▌░╟")

	bar := p.AddBar(100).PrependName(name, 0).AppendPercentage()

	for i := 0; i < 100; i++ {
		time.Sleep(time.Duration(rand.Intn(100)) * time.Millisecond)
		bar.Incr(1)
	}

	p.Stop()

Running this, will produce:

gif

However mpb was designed with concurrency in mind. Each new bar renders in its own goroutine, therefore adding multiple bars is easy and safe:

	var wg sync.WaitGroup
	p := mpb.New(nil)
	for i := 0; i < 3; i++ {
		wg.Add(1) // add wg delta
		name := fmt.Sprintf("Bar#%d:", i)
		bar := p.AddBar(100).PrependName(name, len(name)).AppendPercentage()
		go func() {
			defer wg.Done()
			// you can p.AddBar() here, but ordering will be non deterministic
			// if you still need p.AddBar() here and maintain ordering, use
			// (*mpb.Progress).BeforeRenderFunc(f mpb.BeforeRender)
			for i := 0; i < 100; i++ {
				time.Sleep(time.Duration(rand.Intn(100)) * time.Millisecond)
				bar.Incr(1)
			}
		}()
	}
	wg.Wait() // Wait for goroutines to finish
	p.Stop()  // Stop mpb's rendering goroutine
	// p.AddBar(1) // panic: you cannot reuse p, create new one!
	fmt.Println("finish")

simple.gif

The source code: example/simple/main.go

Cancel

cancel.gif

The source code: example/cancel/main.go

Removing bar

remove.gif

The source code: example/remove/main.go

Sorting bars by progress

sort.gif

The source code: example/sort/main.go

Resizing bars on terminal width change

resize.gif

The source code: example/prependETA/main.go

Multiple io

io-multiple.gif

The source code: example/io/multiple/main.go

Custom Decorators

Here is example from getparty src code.

Installation

$ go get -u github.com/vbauerster/mpb

License

MIT

The typeface used in screen shots: Iosevka

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrCallAfterStop = errors.New("method call on stopped Progress instance")

ErrCallAfterStop thrown by panic, if Progress methods like AddBar() are called after Stop() has been called

Functions

func Format 

func Format(i int64) *formatter

func IsClosed 

func IsClosed(ch <-chan struct{}) bool

IsClosed check if ch closed caution see: http://www.tapirgames.com/blog/golang-channel-closing

Types

type Bar 

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

Bar represents a progress Bar

func (*Bar) AppendETA 

func (b *Bar) AppendETA(padding int) *Bar

func (*Bar) AppendElapsed 

func (b *Bar) AppendElapsed() *Bar

func (*Bar) AppendFunc 

func (b *Bar) AppendFunc(f DecoratorFunc) *Bar

AppendFunc appends DecoratorFunc

func (*Bar) AppendPercentage 

func (b *Bar) AppendPercentage() *Bar

func (*Bar) Completed 

func (b *Bar) Completed()

Completed signals to the bar, that process has been completed. You should call this method when total is unknown and you've reached the point of process completion.

func (*Bar) Format 

func (b *Bar) Format(format string) *Bar

Format overrides format of individual bar

func (*Bar) GetAppenders 

func (b *Bar) GetAppenders() []DecoratorFunc

GetAppenders returns slice of appender DecoratorFunc

func (*Bar) GetID 

func (b *Bar) GetID() int

GetID returs id of the bar

func (*Bar) GetPrependers 

func (b *Bar) GetPrependers() []DecoratorFunc

GetPrependers returns slice of prepender DecoratorFunc

func (*Bar) GetStatistics 

func (b *Bar) GetStatistics() *Statistics

GetStatistics returs *Statistics, which contains information like Tottal, Current, TimeElapsed and TimePerItemEstimate

func (*Bar) InProgress 

func (b *Bar) InProgress() bool

InProgress returns true, while progress is running Can be used as condition in for loop

func (*Bar) Incr 

func (b *Bar) Incr(n int)

Incr increments progress bar

func (*Bar) IncrWithReFill 

func (b *Bar) IncrWithReFill(n int, r rune)

IncrWithReFill increments pb with different fill character

func (*Bar) PrependCounters 

func (b *Bar) PrependCounters(unit Units, padding int) *Bar

func (*Bar) PrependETA 

func (b *Bar) PrependETA(padding int) *Bar

func (*Bar) PrependElapsed 

func (b *Bar) PrependElapsed(padding int) *Bar

func (*Bar) PrependFunc 

func (b *Bar) PrependFunc(f DecoratorFunc) *Bar

PrependFunc prepends DecoratorFunc

func (*Bar) PrependName 

func (b *Bar) PrependName(name string, padding int) *Bar

func (*Bar) PrependPercentage 

func (b *Bar) PrependPercentage(padding int) *Bar

func (*Bar) ProxyReader 

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

ProxyReader wrapper for io operations, like io.Copy

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

func (b *Bar) SetEtaAlpha(a float64) *Bar

SetEtaAlpha sets alfa for exponential-weighted-moving-average ETA estimator Defaults to 0.25 Normally you shouldn't touch this

func (*Bar) SetWidth 

func (b *Bar) SetWidth(n int) *Bar

SetWidth overrides width of individual bar

func (*Bar) TrimLeftSpace 

func (b *Bar) TrimLeftSpace() *Bar

TrimLeftSpace removes space befor LeftEnd charater

func (*Bar) TrimRightSpace 

func (b *Bar) TrimRightSpace() *Bar

TrimRightSpace removes space after RightEnd charater

type BeforeRender 

type BeforeRender func([]*Bar)

BeforeRender is a func, which gets called before render process

type DecoratorFunc 

type DecoratorFunc func(s *Statistics) string

DecoratorFunc is a function that can be prepended and appended to the progress bar

type Progress 

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

Progress represents the container that renders Progress bars

func New 

func New(ctx context.Context) *Progress

New creates new Progress instance, which will orchestrate bars rendering process. It acceepts context.Context, for cancellation. If you don't plan to cancel, it is safe to feed with nil

func (*Progress) AddBar 

func (p *Progress) AddBar(total int64) *Bar

AddBar creates a new progress bar and adds to the container pancis, if called on stopped Progress instance, i.e after Stop()

func (*Progress) AddBarWithID 

func (p *Progress) AddBarWithID(id int, total int64) *Bar

AddBarWithID creates a new progress bar and adds to the container pancis, if called on stopped Progress instance, i.e after Stop()

func (*Progress) BarCount 

func (p *Progress) BarCount() int

BarCount returns bars count in the container. Pancis if called on stopped Progress instance, i.e after Stop()

func (*Progress) BeforeRenderFunc 

func (p *Progress) BeforeRenderFunc(f BeforeRender) *Progress

BeforeRenderFunc accepts a func, which gets called before render process.

func (*Progress) Format 

func (p *Progress) Format(format string) *Progress

Format sets custom format for underlying bar(s). The default one is "[=>-]"

func (*Progress) RefreshRate 

func (p *Progress) RefreshRate(d time.Duration) *Progress

RefreshRate overrides default (100ms) refresh rate value pancis, if called on stopped Progress instance, i.e after Stop()

func (*Progress) RemoveBar 

func (p *Progress) RemoveBar(b *Bar) bool

RemoveBar removes bar at any time pancis, if called on stopped Progress instance, i.e after Stop()

func (*Progress) SetOut 

func (p *Progress) SetOut(w io.Writer) *Progress

SetOut sets underlying writer of progress. Default is os.Stdout pancis, if called on stopped Progress instance, i.e after Stop()

func (*Progress) SetWidth 

func (p *Progress) SetWidth(n int) *Progress

SetWidth overrides default (70) width of bar(s)

func (*Progress) Stop 

func (p *Progress) Stop()

Stop waits for bars to finish rendering and stops the rendering goroutine

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)

type Statistics 

type Statistics struct {
	Total, Current                   int64
	TimeElapsed, TimePerItemEstimate time.Duration
}

Statistics represents statistics of the progress bar. Cantains: Total, Current, TimeElapsed, TimePerItemEstimate

func (*Statistics) Eta 

func (s *Statistics) Eta() time.Duration

Eta returns exponential-weighted-moving-average ETA estimator

type Units 

type Units uint
const (
	UnitNone Units = iota
	UnitBytes
)

Source Files

View all Source files

Directories

Path Synopsis
example
cancel
hang
io/multiple
io/single
prependETA
prependElapsed
remove
simple
singleBar
sort
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.