pb

README

Terminal progress bar for Go

Simple progress bar for console programms.

Installation

go get github.com/cheggaaa/pb

Usage

package main

import (
	"github.com/cheggaaa/pb"
	"time"
)

func main() {
	count := 100000
	bar := pb.StartNew(count)
	for i := 0; i < count; i++ {
		bar.Increment()
		time.Sleep(time.Millisecond)
	}
	bar.FinishPrint("The End!")
}

Result will be like this:

> go run test.go
37158 / 100000 [================>_______________________________] 37.16% 1m11s

More functions?

// create bar
bar := pb.New(count)

// refresh info every second (default 200ms)
bar.SetRefreshRate(time.Second)

// show percents (by default already true)
bar.ShowPercent = true

// show bar (by default already true)
bar.ShowBar = true

// no need counters
bar.ShowCounters = false

// show "time left"
bar.ShowTimeLeft = true

// show average speed    
bar.ShowSpeed = true

// sets the width of the progress bar
bar.SetWidth(80)

// sets the width of the progress bar, but if terminal size smaller will be ignored
bar.SetMaxWidth(80)

// convert output to readable format (like KB, MB)     
bar.SetUnits(pb.U_BYTES)

// and start
bar.Start()

Want handle progress of io operations?

// create and start bar
bar := pb.New(myDataLen).SetUnits(pb.U_BYTES)
bar.Start()

// my io.Reader
r := myReader

// my io.Writer
w := myWriter

// create multi writer
writer := io.MultiWriter(w, bar)

// and copy
io.Copy(writer, r)

// show example/copy/copy.go for advanced example

Not like the looks?

bar.Format("<.- >")

Documentation

Index

• Constants
• Variables
• func Format(i int64, units Units) string
• func FormatBytes(i int64) (result string)
• type Callback
• type ProgressBar
  • func New(total int) *ProgressBar
  • func New64(total int64) *ProgressBar
  • func StartNew(total int) *ProgressBar
  • func (pb *ProgressBar) Add(add int) int
  • func (pb *ProgressBar) Add64(add int64) int64
  • func (pb *ProgressBar) Finish()
  • func (pb *ProgressBar) FinishPrint(str string)
  • func (pb *ProgressBar) Format(format string) *ProgressBar
  • func (pb *ProgressBar) Increment() int
  • func (pb *ProgressBar) NewProxyReader(r io.Reader) *Reader
  • func (pb *ProgressBar) Postfix(postfix string) *ProgressBar
  • func (pb *ProgressBar) Prefix(prefix string) *ProgressBar
  • func (pb *ProgressBar) Read(p []byte) (n int, err error)
  • func (pb *ProgressBar) Set(current int) *ProgressBar
  • func (pb *ProgressBar) Set64(current int64) *ProgressBar
  • func (pb *ProgressBar) SetMaxWidth(width int) *ProgressBar
  • func (pb *ProgressBar) SetRefreshRate(rate time.Duration) *ProgressBar
  • func (pb *ProgressBar) SetUnits(units Units) *ProgressBar
  • func (pb *ProgressBar) SetWidth(width int) *ProgressBar
  • func (pb *ProgressBar) Start() *ProgressBar
  • func (pb *ProgressBar) Update()
  • func (pb *ProgressBar) Write(p []byte) (n int, err error)
• type Reader
  • func (r *Reader) Read(p []byte) (n int, err error)
• type Units

Constants

const (
	// Default refresh rate - 200ms
	DEFAULT_REFRESH_RATE = time.Millisecond * 200
	FORMAT               = "[=>-]"
)

const (
	TIOCGWINSZ     = 0x5413
	TIOCGWINSZ_OSX = 1074295912
)

Variables

var (
	DefaultRefreshRate                         = DEFAULT_REFRESH_RATE
	BarStart, BarEnd, Empty, Current, CurrentN string
)

DEPRECATED variables for backward compatibility, from now do not work use pb.Format and pb.SetRefreshRate

Functions

func Format

func Format(i int64, units Units) string

Format integer

func FormatBytes

func FormatBytes(i int64) (result string)

Convert bytes to human readable string. Like a 2 MB, 64.2 KB, 52 B

Types

type Callback

type Callback func(out string)

Callback for custom output For example:

bar.Callback = func(s string) {
    mySuperPrint(s)
}

type ProgressBar

type ProgressBar struct {
	Total                            int64
	RefreshRate                      time.Duration
	ShowPercent, ShowCounters        bool
	ShowSpeed, ShowTimeLeft, ShowBar bool
	ShowFinalTime                    bool
	Output                           io.Writer
	Callback                         Callback
	NotPrint                         bool
	Units                            Units
	Width                            int
	ForceWidth                       bool
	ManualUpdate                     bool

	BarStart string
	BarEnd   string
	Empty    string
	Current  string
	CurrentN string
	// contains filtered or unexported fields
}

func New

func New(total int) *ProgressBar

Create new progress bar object

func New64

func New64(total int64) *ProgressBar

Create new progress bar object uding int64 as total

func StartNew

func StartNew(total int) *ProgressBar

Create new object and start

func (*ProgressBar) Add

func (pb *ProgressBar) Add(add int) int

Add to current value

func (*ProgressBar) Add64

func (pb *ProgressBar) Add64(add int64) int64

func (*ProgressBar) Finish

func (pb *ProgressBar) Finish()

End print

func (*ProgressBar) FinishPrint

func (pb *ProgressBar) FinishPrint(str string)

End print and write string 'str'

func (*ProgressBar) Format

func (pb *ProgressBar) Format(format string) *ProgressBar

Set custom format for bar Example: bar.Format("[=>_]")

func (*ProgressBar) Increment

func (pb *ProgressBar) Increment() int

Increment current value

func (*ProgressBar) NewProxyReader

func (pb *ProgressBar) NewProxyReader(r io.Reader) *Reader

Create new proxy reader over bar

func (*ProgressBar) Postfix

func (pb *ProgressBar) Postfix(postfix string) *ProgressBar

Set postfix string

func (*ProgressBar) Prefix

func (pb *ProgressBar) Prefix(prefix string) *ProgressBar

Set prefix string

func (*ProgressBar) Read

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

implement io.Reader

func (*ProgressBar) Set

func (pb *ProgressBar) Set(current int) *ProgressBar

Set current value

func (*ProgressBar) Set64

func (pb *ProgressBar) Set64(current int64) *ProgressBar

Set64 sets the current value as int64

func (*ProgressBar) SetMaxWidth

func (pb *ProgressBar) SetMaxWidth(width int) *ProgressBar

Set max width, if width is bigger than terminal width, will be ignored

func (*ProgressBar) SetRefreshRate

func (pb *ProgressBar) SetRefreshRate(rate time.Duration) *ProgressBar

Set bar refresh rate

func (*ProgressBar) SetUnits

func (pb *ProgressBar) SetUnits(units Units) *ProgressBar

Set units bar.SetUnits(U_NO) - by default bar.SetUnits(U_BYTES) - for Mb, Kb, etc

func (*ProgressBar) SetWidth

func (pb *ProgressBar) SetWidth(width int) *ProgressBar

Set bar width

func (*ProgressBar) Start

func (pb *ProgressBar) Start() *ProgressBar

Start print

func (*ProgressBar) Update

func (pb *ProgressBar) Update()

Write the current state of the progressbar

func (*ProgressBar) Write

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

implement io.Writer

type Reader

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

It's proxy reader, implement io.Reader

func (*Reader) Read

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

type Units

type Units int

const (
	// By default, without type handle
	U_NO Units = iota
	// Handle as b, Kb, Mb, etc
	U_BYTES
)