README.md
1# Terminal progress bar for Go
2[![Coverage Status](https://coveralls.io/repos/github/cheggaaa/pb/badge.svg)](https://coveralls.io/github/cheggaaa/pb)
3
4## Installation
5
6```
7go get github.com/cheggaaa/pb/v3
8```
9
10Documentation for v1 bar available [here](README_V1.md)
11
12## Quick start
13
14```Go
15package main
16
17import (
18 "time"
19
20 "github.com/cheggaaa/pb/v3"
21)
22
23func main() {
24 count := 100000
25 // create and start new bar
26 bar := pb.StartNew(count)
27
28 // start bar from 'default' template
29 // bar := pb.Default.Start(count)
30
31 // start bar from 'simple' template
32 // bar := pb.Simple.Start(count)
33
34 // start bar from 'full' template
35 // bar := pb.Full.Start(count)
36
37 for i := 0; i < count; i++ {
38 bar.Increment()
39 time.Sleep(time.Millisecond)
40 }
41 bar.Finish()
42}
43
44```
45
46Result will be like this:
47
48```
49> go run test.go
5037158 / 100000 [================>_______________________________] 37.16% 1m11s
51```
52
53## Settings
54
55```Go
56// create bar
57bar := pb.New(count)
58
59// refresh info every second (default 200ms)
60bar.SetRefreshRate(time.Second)
61
62// force set io.Writer, by default it's os.Stderr
63bar.SetWriter(os.Stdout)
64
65// bar will format numbers as bytes (B, KiB, MiB, etc)
66bar.Set(pb.Byte, true)
67
68// bar use SI bytes prefix names (B, kB) instead of IEC (B, KiB)
69bar.Set(pb.SIBytesPrefix, true)
70
71// set custom bar template
72bar.SetTemplateString(myTemplate)
73
74// check for error after template set
75if err = bar.Err(); err != nil {
76 return
77}
78
79// start bar
80bar.Start()
81
82```
83
84## Progress bar for IO Operations
85```go
86package main
87
88import (
89 "crypto/rand"
90 "io"
91 "io/ioutil"
92
93 "github.com/cheggaaa/pb/v3"
94)
95
96func main() {
97
98 var limit int64 = 1024 * 1024 * 500
99 // we will copy 200 Mb from /dev/rand to /dev/null
100 reader := io.LimitReader(rand.Reader, limit)
101 writer := ioutil.Discard
102
103 // start new bar
104 bar := pb.Full.Start64(limit)
105 // create proxy reader
106 barReader := bar.NewProxyReader(reader)
107 // copy from proxy reader
108 io.Copy(writer, barReader)
109 // finish bar
110 bar.Finish()
111}
112
113```
114
115## Custom Progress Bar templates
116
117Rendering based on builtin text/template package. You can use existing pb's elements or create you own.
118
119All available elements are described in element.go file.
120
121#### All in one example:
122```go
123tmpl := `{{ red "With funcs:" }} {{ bar . "<" "-" (cycle . "↖" "↗" "↘" "↙" ) "." ">"}} {{speed . | rndcolor }} {{percent .}} {{string . "my_green_string" | green}} {{string . "my_blue_string" | blue}}`
124// start bar based on our template
125bar := pb.ProgressBarTemplate(tmpl).Start64(limit)
126// set values for string elements
127bar.Set("my_green_string", "green").
128 Set("my_blue_string", "blue")
129```
README_V1.md
1# Terminal progress bar for Go
2
3Simple progress bar for console programs.
4
5## Installation
6
7```
8go get github.com/cheggaaa/pb
9```
10
11## Usage
12
13```Go
14package main
15
16import (
17 "github.com/cheggaaa/pb"
18 "time"
19)
20
21func main() {
22 count := 100000
23 bar := pb.StartNew(count)
24 for i := 0; i < count; i++ {
25 bar.Increment()
26 time.Sleep(time.Millisecond)
27 }
28 bar.FinishPrint("The End!")
29}
30
31```
32
33Result will be like this:
34
35```
36> go run test.go
3737158 / 100000 [================>_______________________________] 37.16% 1m11s
38```
39
40## Customization
41
42```Go
43// create bar
44bar := pb.New(count)
45
46// refresh info every second (default 200ms)
47bar.SetRefreshRate(time.Second)
48
49// show percents (by default already true)
50bar.ShowPercent = true
51
52// show bar (by default already true)
53bar.ShowBar = true
54
55// no counters
56bar.ShowCounters = false
57
58// show "time left"
59bar.ShowTimeLeft = true
60
61// show average speed
62bar.ShowSpeed = true
63
64// sets the width of the progress bar
65bar.SetWidth(80)
66
67// sets the width of the progress bar, but if terminal size smaller will be ignored
68bar.SetMaxWidth(80)
69
70// convert output to readable format (like KB, MB)
71bar.SetUnits(pb.U_BYTES)
72
73// and start
74bar.Start()
75```
76
77## Progress bar for IO Operations
78
79```go
80// create and start bar
81bar := pb.New(myDataLen).SetUnits(pb.U_BYTES)
82bar.Start()
83
84// my io.Reader
85r := myReader
86
87// my io.Writer
88w := myWriter
89
90// create proxy reader
91reader := bar.NewProxyReader(r)
92
93// and copy from pb reader
94io.Copy(w, reader)
95
96```
97
98```go
99// create and start bar
100bar := pb.New(myDataLen).SetUnits(pb.U_BYTES)
101bar.Start()
102
103// my io.Reader
104r := myReader
105
106// my io.Writer
107w := myWriter
108
109// create multi writer
110writer := io.MultiWriter(w, bar)
111
112// and copy
113io.Copy(writer, r)
114
115bar.Finish()
116```
117
118## Custom Progress Bar Look-and-feel
119
120```go
121bar.Format("<.- >")
122```
123
124## Multiple Progress Bars (experimental and unstable)
125
126Do not print to terminal while pool is active.
127
128```go
129package main
130
131import (
132 "math/rand"
133 "sync"
134 "time"
135
136 "github.com/cheggaaa/pb"
137)
138
139func main() {
140 // create bars
141 first := pb.New(200).Prefix("First ")
142 second := pb.New(200).Prefix("Second ")
143 third := pb.New(200).Prefix("Third ")
144 // start pool
145 pool, err := pb.StartPool(first, second, third)
146 if err != nil {
147 panic(err)
148 }
149 // update bars
150 wg := new(sync.WaitGroup)
151 for _, bar := range []*pb.ProgressBar{first, second, third} {
152 wg.Add(1)
153 go func(cb *pb.ProgressBar) {
154 for n := 0; n < 200; n++ {
155 cb.Increment()
156 time.Sleep(time.Millisecond * time.Duration(rand.Intn(100)))
157 }
158 cb.Finish()
159 wg.Done()
160 }(bar)
161 }
162 wg.Wait()
163 // close pool
164 pool.Stop()
165}
166```
167
168The result will be as follows:
169
170```
171$ go run example/multiple.go
172First 34 / 200 [=========>---------------------------------------------] 17.00% 00m08s
173Second 42 / 200 [===========>------------------------------------------] 21.00% 00m06s
174Third 36 / 200 [=========>---------------------------------------------] 18.00% 00m08s
175```
176