progressbar

package module
v3.3.5-0...-125743e Latest Latest
Warning

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

 Go to latest Published: Jul 10, 2020 License: MIT Imports: 14 Imported by: 0

README

progressbar

travis go report card coverage godocs

Fork Changes

This fork adds a String() method to the progress bar, as well as other code that makes it easy to just get the rendered progress bar, but not output it anywhere.

Other new methods
  • Silent functions that initalize a progress bar that doesn't output anywhere
    • DefaultBytesSilent(maxBytes int64, description ...string) *ProgressBar
    • DefaultSilent(max int64, description ...string) *ProgressBar

It is currently not merged with the original project.

Original README

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.

Install

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

Usage

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

which looks like:

Example of basic bar

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.

req, _ := http.NewRequest("GET", "https://dl.google.com/go/go1.14.2.src.tar.gz", nil)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

f, _ := os.OpenFile("go1.14.2.src.tar.gz", os.O_CREATE|os.O_WRONLY, 0644)
defer f.Close()

bar := progressbar.DefaultBytes(
    resp.ContentLength,
    "downloading",
)
io.Copy(io.MultiWriter(f, bar), resp.Body)

which looks like:

Example of download bar

Progress bar with unknown length

A progressbar with unknown length is a spinner. Any bar with less than 1 length will automatically convert it to a spinner with a customizable spinner type. For example, the above code can be run and set the resp.ContentLength to 0.

which looks like:

Example of download bar with unknown length

Customization

There is a lot of customization that you can do - change the writer, the color, the width, description, theme, etc. See all the options.

bar := progressbar.NewOptions(1000,
    progressbar.OptionSetWriter(ansi.NewAnsiStdout()),
    progressbar.OptionEnableColorCodes(true),
    progressbar.OptionShowBytes(true),
    progressbar.OptionSetWidth(15),
    progressbar.OptionSetDescription("[cyan][1/3][reset] Writing moshable file..."),
    progressbar.OptionSetTheme(progressbar.Theme{
        Saucer:        "[green]=[reset]",
        SaucerHead:    "[green]>[reset]",
        SaucerPadding: " ",
        BarStart:      "[",
        BarEnd:        "]",
    }))
for i := 0; i < 1000; i++ {
    bar.Add(1)
    time.Sleep(5 * time.Millisecond)
}

which looks like:

Example of customized bar

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!

Thanks @Benzammour and @haseth for helping create v3!

Thanks @briandowns for compiling the list of spinners.

License

MIT

Documentation

Overview

Example (XOutOfY) 
bar := NewOptions(100, OptionSetPredictTime(true))

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

Output:

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 

func OptionClearOnFinish() Option

OptionClearOnFinish will clear the bar once its finished

Example 
bar := NewOptions(100, OptionSetWidth(10), OptionSetRenderBlankState(false), OptionClearOnFinish())
bar.Reset()
bar.Finish()
fmt.Println("Finished")

Output:

Finished

func OptionEnableColorCodes 

func OptionEnableColorCodes(colorCodes bool) Option

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

func OptionFullWidth 

func OptionFullWidth() Option

OptionFullWidth sets the bar to be full width

func OptionOnCompletion 

func OptionOnCompletion(cmpl func()) Option

OptionOnCompletion will invoke cmpl function once its finished

func OptionSetDescription 

func OptionSetDescription(description string) Option

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

func OptionSetPredictTime 

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

func OptionSetRenderBlankState 

func OptionSetRenderBlankState(r bool) Option

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

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

Output:

0% |          |  [0s:0s]

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 OptionShowBytes 

func OptionShowBytes(val bool) Option

OptionShowBytes will update the progress bar configuration settings to display/hide kBytes/Sec

func OptionShowCount 

func OptionShowCount() Option

OptionShowCount will also print current count out of total

func OptionShowIts 

func OptionShowIts() Option

OptionShowIts will also print the iterations/second

Example 
bar := NewOptions(100, OptionSetWidth(10), OptionShowIts(), OptionSetPredictTime(false))
bar.Reset()
time.Sleep(1 * time.Second)
bar.Add(10)

Output:

10% |█         | (10 it/s)
Example (Count) 
bar := NewOptions(100, OptionSetWidth(10), OptionShowIts(), OptionShowCount())
bar.Reset()
time.Sleep(1 * time.Second)
bar.Add(10)

Output:

10% |█         | (10/100, 10 it/s) [1s:9s]

func OptionSpinnerType 

func OptionSpinnerType(spinnerType int) Option

OptionSpinnerType sets the type of spinner used for indeterminate bars

func OptionThrottle 

func OptionThrottle(duration time.Duration) Option

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

Example 
bar := NewOptions(100, OptionSetWidth(10), OptionSetRenderBlankState(false), OptionThrottle(100*time.Millisecond))
bar.Reset()
bar.Add(5)
time.Sleep(150 * time.Millisecond)
bar.Add(5)
bar.Add(10)

Output:

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

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]
Example (Basic) 
bar := NewOptions(100, OptionSetWidth(10), OptionSetRenderBlankState(false))
bar.Reset()
time.Sleep(1 * time.Second)
bar.Add(10)

Output:

10% |█         |  [1s:9s]

func Default 

func Default(max int64, description ...string) *ProgressBar

Default provides a progressbar with recommended defaults. Set max to -1 to use as a spinner.

Example 
bar := Default(100)
for i := 0; i < 50; i++ {
	bar.Add(1)
	time.Sleep(10 * time.Millisecond)
}

Output:

func DefaultBytes 

func DefaultBytes(maxBytes int64, description ...string) *ProgressBar

DefaultBytes provides a progressbar to measure byte throughput with recommended defaults. Set maxBytes to -1 to use as a spinner.

func DefaultBytesSilent 

func DefaultBytesSilent(maxBytes int64, description ...string) *ProgressBar

DefaultBytesSilent is the same as DefaultBytes, but does not output anywhere. String() can be used to get the output instead.

func DefaultSilent 

func DefaultSilent(max int64, description ...string) *ProgressBar

DefaultSilent is the same as Default, but does not output anywhere. String() can be used to get the output instead.

func New 

func New(max int) *ProgressBar

New returns a new ProgressBar with the specified maximum

func New64 

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 

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 

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

Add64 will add the specified amount to the progressbar

func (*ProgressBar) ChangeMax 

func (p *ProgressBar) ChangeMax(newMax int)

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

func (*ProgressBar) ChangeMax64 

func (p *ProgressBar) ChangeMax64(newMax int64)

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

func (*ProgressBar) Clear 

func (p *ProgressBar) Clear() error

Clear erases the progress bar from the current line

func (*ProgressBar) Describe 

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

Example 
bar := NewOptions(100, OptionSetWidth(10), OptionSetRenderBlankState(false))
bar.Reset()
time.Sleep(1 * time.Second)
bar.Describe("performing axial adjustements")
bar.Add(10)

Output:

performing axial adjustements  10% |█         |  [1s:9s]

func (*ProgressBar) Finish 

func (p *ProgressBar) Finish() error

Finish will fill the bar to full

Example 
bar := NewOptions(100, OptionSetWidth(10), OptionSetRenderBlankState(false))
bar.Finish()

Output:

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

func (*ProgressBar) GetMax 

func (p *ProgressBar) GetMax() int

GetMax returns the max of a bar

func (*ProgressBar) GetMax64 

func (p *ProgressBar) GetMax64() int64

GetMax64 returns the current max

func (*ProgressBar) Read 

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

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

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

Set wil set the bar to a current number

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

Output:

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

func (*ProgressBar) Set64 

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

Set64 wil set the bar to a current number

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

Output:

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

func (*ProgressBar) State 

func (p *ProgressBar) State() State

State returns the current state

func (*ProgressBar) String 

func (p *ProgressBar) String() string

String returns the current rendered version of the progress bar. It will never return an empty string while the progress bar is running.

func (*ProgressBar) Write 

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

Write implement io.Writer

type Reader 

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

Reader is the progressbar io.Reader struct

func (*Reader) Close 

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

Close the reader when it implements io.Closer

func (*Reader) Read 

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 

type State struct {
	CurrentPercent float64
	CurrentBytes   float64
	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

Directories

Path Synopsis
examples
basic
customization
download
download-unknown

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.