progressbar

package module
v2.14.1 Latest Latest
Warning

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

 Go to latest Published: Nov 17, 2019 License: MIT Imports: 10 Imported by: 66

README

progressbar

travis go report card coverage godocs

A very simple thread-safe progress bar which should work on every OS without problems. I needed a progressbar for croc and everything I tried had problems, so I made another one. In order to be OS agnostic I do not plan to support multi-line outputs.

Example of progress bar

Install

go get -u github.com/schollz/progressbar/v2

Usage

Basic usage
bar := progressbar.New(100)
for i := 0; i < 100; i++ {
    bar.Add(1)
    time.Sleep(10 * time.Millisecond)
}

which looks like:

 100% |████████████████████████████████████████| [1s:0s]

The times at the end show the elapsed time and the remaining time, respectively.

Long running processes

For long running processes, you might want to render from a 0% state.

// Renders the bar right on construction
bar := progressbar.NewOptions(100, progressbar.OptionSetRenderBlankState(true))

Alternatively, when you want to delay rendering, but still want to render a 0% state

bar := progressbar.NewOptions(100)

// Render the current state, which is 0% in this case
bar.RenderBlank()

// Emulate work
for i := 0; i < 10; i++ {
    time.Sleep(10 * time.Minute)
    bar.Add(10)
}
Use a custom writer

The default writer is standard output (os.Stdout), but you can set it to whatever satisfies io.Writer.

bar := NewOptions(
    10,
    OptionSetTheme(Theme{Saucer: "#", SaucerPadding: "-", BarStart: ">", BarEnd: "<"}),
    OptionSetWidth(10),
    OptionSetWriter(&buf),
)

bar.Add(5)
result := strings.TrimSpace(buf.String())

// Result equals:
// 50% >#####-----< [0s:0s]
Progress for I/O operations

The progressbar implements an io.Writer so it can automatically detect the number of bytes written to a stream, so you can use it as a progressbar for an io.Reader.

urlToGet := "https://github.com/schollz/croc/releases/download/v4.1.4/croc_v4.1.4_Windows-64bit_GUI.zip"
req, _ := http.NewRequest("GET", urlToGet, nil)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var out io.Writer
f, _ := os.OpenFile("croc_v4.1.4_Windows-64bit_GUI.zip", os.O_CREATE|os.O_WRONLY, 0644)
out = f
defer f.Close()

bar := progressbar.NewOptions(
    int(resp.ContentLength), 
    progressbar.OptionSetBytes(int(resp.ContentLength)),
)
out = io.MultiWriter(out, bar)
io.Copy(out, resp.Body)

See the tests for another example.

Changing max value

The progressbar implements ChangeMax and ChangeMax64 functions to change the max value of the progress bar.

bar := progressbar.New(100)
bar.ChangeMax(200) // Change the max of the progress bar to 200, not 100

You can also use ChangeMax64 to minimize casting in the library. See the tests for another example.

Displaying Total Increment Over Predicted Time

By default the progress bar will attempt to predict the remaining amount of time left. This can be change to just show the current increment over the total maximum amount set for the progress bar. Do this by using the OptionSetPredictTime option during progress bar creation.

bar := progressbar.NewOptions(100, progressbar.OptionSetPredictTime(false))
bar.Add(20)

// this result equals:
// "20% |██        |  [20:100]"

// default result equals:
// "20% |██        |  [3s:15s]"

Contributing

Pull requests are welcome. Feel free to...

  • Revise documentation
  • Add new features
  • Fix bugs
  • Suggest improvements

Thanks

Thanks @Dynom for massive improvements in version 2.0!

Thanks @CrushedPixel for adding descriptions and color code support!

Thanks @MrMe42 for adding some minor features!

Thanks @tehstun for some great PRs!

License

MIT

Documentation

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Option 

type Option func(p *ProgressBar)

Option is the type all options need to adhere to

func OptionClearOnFinish added in v2.11.0 

func OptionClearOnFinish() Option

OptionClearOnFinish will clear the bar once its finished

func OptionEnableColorCodes added in v2.3.0 

func OptionEnableColorCodes(colorCodes bool) Option

OptionEnableColorCodes enables or disables support for color codes using mitchellh/colorstring

func OptionOnCompletion added in v2.12.0 

func OptionOnCompletion(cmpl func()) Option

func OptionSetBytes added in v2.4.0 

func OptionSetBytes(maxBytes int) Option

OptionSetBytes will also print the bytes/second

func OptionSetBytes64 added in v2.9.1 

func OptionSetBytes64(maxBytes int64) Option

OptionSetBytes64 will also print the bytes/second

func OptionSetDescription added in v2.2.0 

func OptionSetDescription(description string) Option

OptionSetDescription sets the description of the bar to render in front of it

func OptionSetPredictTime added in v2.14.0 

func OptionSetPredictTime(predictTime bool) Option

OptionSetPredictTime will also attempt to predict the time remaining.

Example 
bar := NewOptions(100, OptionSetWidth(10), OptionSetPredictTime(false))
_ = bar.Add(10)

Output:

10% |█         |  [10:100]

func OptionSetRenderBlankState 

func OptionSetRenderBlankState(r bool) Option

OptionSetRenderBlankState sets whether or not to render a 0% bar on construction

func OptionSetTheme 

func OptionSetTheme(t Theme) Option

OptionSetTheme sets the elements the bar is constructed of

func OptionSetWidth 

func OptionSetWidth(s int) Option

OptionSetWidth sets the width of the bar

func OptionSetWriter 

func OptionSetWriter(w io.Writer) Option

OptionSetWriter sets the output writer (defaults to os.StdOut)

func OptionShowCount added in v2.8.0 

func OptionShowCount() Option

OptionShowCount will also print current count out of total

func OptionShowIts added in v2.5.0 

func OptionShowIts() Option

OptionShowIts will also print the iterations/second

func OptionThrottle added in v2.7.0 

func OptionThrottle(duration time.Duration) Option

OptionThrottle will wait the specified duration before updating again. The default duration is 0 seconds.

type ProgressBar 

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

ProgressBar is a thread-safe, simple progress bar

Example 
bar := New(100)
bar.Add(10)

Output:

10% |████                                    |  [0s:0s]

func New 

func New(max int) *ProgressBar

New returns a new ProgressBar with the specified maximum

func New64 added in v2.13.0 

func New64(max int64) *ProgressBar

New64 returns a new ProgressBar with the specified maximum

func NewOptions 

func NewOptions(max int, options ...Option) *ProgressBar

NewOptions constructs a new instance of ProgressBar, with any options you specify

func NewOptions64 added in v2.9.1 

func NewOptions64(max int64, options ...Option) *ProgressBar

NewOptions64 constructs a new instance of ProgressBar, with any options you specify

func (*ProgressBar) Add 

func (p *ProgressBar) Add(num int) error

Add will add the specified amount to the progressbar

func (*ProgressBar) Add64 added in v2.9.1 

func (p *ProgressBar) Add64(num int64) error

Add64 will add the specified amount to the progressbar

func (*ProgressBar) ChangeMax added in v2.14.0 

func (p *ProgressBar) ChangeMax(newMax int)

ChangeMax takes in a int and changes the max value of the progress bar

func (*ProgressBar) ChangeMax64 added in v2.14.0 

func (p *ProgressBar) ChangeMax64(newMax int64)

ChangeMax64 is basically the same as ChangeMax, but takes in a int64 to avoid casting

func (*ProgressBar) Clear added in v2.3.0 

func (p *ProgressBar) Clear() error

Clear erases the progress bar from the current line

func (*ProgressBar) Describe added in v2.10.0 

func (p *ProgressBar) Describe(description string)

Describe will change the description shown before the progress, which can be changed on the fly (as for a slow running process).

func (*ProgressBar) Finish added in v2.4.0 

func (p *ProgressBar) Finish() error

Finish will fill the bar to full

func (*ProgressBar) GetMax added in v2.14.0 

func (p *ProgressBar) GetMax() int

Get the max of a bar

func (*ProgressBar) GetMax64 added in v2.14.0 

func (p *ProgressBar) GetMax64() int64

Same as GetMax, but returns int64

func (*ProgressBar) Read added in v2.9.0 

func (p *ProgressBar) Read(b []byte) (n int, err error)

Read implement io.Reader

func (*ProgressBar) RenderBlank 

func (p *ProgressBar) RenderBlank() error

RenderBlank renders the current bar state, you can use this to render a 0% state

Example 
NewOptions(10, OptionSetWidth(10), OptionSetRenderBlankState(true))

Output:

0% |          |  [0s:0s]

func (*ProgressBar) Reset 

func (p *ProgressBar) Reset()

Reset will reset the clock that is used to calculate current time and the time left.

func (*ProgressBar) State added in v2.6.0 

func (p *ProgressBar) State() State

State returns the current state

func (*ProgressBar) Write added in v2.9.0 

func (p *ProgressBar) Write(b []byte) (n int, err error)

Write implement io.Writer

type Reader added in v2.9.0 

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

Reader is the progressbar io.Reader struct

func (*Reader) Close added in v2.9.0 

func (r *Reader) Close() (err error)

Close the reader when it implements io.Closer

func (*Reader) Read added in v2.9.0 

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

Read will read the data and add the number of bytes to the progressbar

type State added in v2.6.0 

type State struct {
	CurrentPercent float64
	CurrentBytes   float64
	MaxBytes       int64
	SecondsSince   float64
	SecondsLeft    float64
	KBsPerSecond   float64
}

State is the basic properties of the bar

type Theme 

type Theme struct {
	Saucer        string
	SaucerHead    string
	SaucerPadding string
	BarStart      string
	BarEnd        string
}

Theme defines the elements of the bar

Source Files

View all Source files

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.