Commit 8f7287a1 authored by Thorsten Alteholz's avatar Thorsten Alteholz

New upstream version 0.0~git20171218.25e98ff

parents
language: go
sudo: false
install:
- go get ./...
go:
- 1.4
- tip
MIT License
===========
Copyright (c) 2015, Greg Osuri
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
test:
@go test -race .
@go test -race ./util/strutil
examples:
go run -race example/full/full.go
go run -race example/incr/incr.go
go run -race example/multi/multi.go
go run -race example/simple/simple.go
.PHONY: test examples
# uiprogress [![GoDoc](https://godoc.org/github.com/gosuri/uiprogress?status.svg)](https://godoc.org/github.com/gosuri/uiprogress) [![Build Status](https://travis-ci.org/gosuri/uiprogress.svg?branch=master)](https://travis-ci.org/gosuri/uiprogress)
A Go library to render progress bars in terminal applications. It provides a set of flexible features with a customizable API.
![example](doc/example_full.gif)
Progress bars improve readability for terminal applications with long outputs by providing a concise feedback loop.
## Features
* __Multiple Bars__: uiprogress can render multiple progress bars that can be tracked concurrently
* __Dynamic Addition__: Add additional progress bars any time, even after the progress tracking has started
* __Prepend and Append Functions__: Append or prepend completion percent and time elapsed to the progress bars
* __Custom Decorator Functions__: Add custom functions around the bar along with helper functions
## Usage
To start listening for progress bars, call `uiprogress.Start()` and add a progress bar using `uiprogress.AddBar(total int)`. Update the progress using `bar.Incr()` or `bar.Set(n int)`. Full source code for the below example is available at [example/simple/simple.go](example/simple/simple.go)
```go
uiprogress.Start() // start rendering
bar := uiprogress.AddBar(100) // Add a new bar
// optionally, append and prepend completion and elapsed time
bar.AppendCompleted()
bar.PrependElapsed()
for bar.Incr() {
time.Sleep(time.Millisecond * 20)
}
```
This will render the below in the terminal
![example](doc/example_simple.gif)
### Using Custom Decorators
You can also add a custom decorator function in addition to default `bar.AppendCompleted()` and `bar.PrependElapsed()` decorators. The below example tracks the current step for an application deploy progress. Source code for the below example is available at [example/full/full.go](example/full/full.go)
```go
var steps = []string{"downloading source", "installing deps", "compiling", "packaging", "seeding database", "deploying", "staring servers"}
bar := uiprogress.AddBar(len(steps))
// prepend the current step to the bar
bar.PrependFunc(func(b *uiprogress.Bar) string {
return "app: " + steps[b.Current()-1]
})
for bar.Incr() {
time.Sleep(time.Millisecond * 10)
}
```
### Rendering Multiple bars
You can add multiple bars using `uiprogress.AddBar(n)`. The below example demonstrates updating multiple bars concurrently and adding a new bar later in the pipeline. Source for this example is available at [example/multi/multi.go](example/multi/multi.go)
```go
waitTime := time.Millisecond * 100
uiprogress.Start()
// start the progress bars in go routines
var wg sync.WaitGroup
bar1 := uiprogress.AddBar(20).AppendCompleted().PrependElapsed()
wg.Add(1)
go func() {
defer wg.Done()
for bar1.Incr() {
time.Sleep(waitTime)
}
}()
bar2 := uiprogress.AddBar(40).AppendCompleted().PrependElapsed()
wg.Add(1)
go func() {
defer wg.Done()
for bar2.Incr() {
time.Sleep(waitTime)
}
}()
time.Sleep(time.Second)
bar3 := uiprogress.AddBar(20).PrependElapsed().AppendCompleted()
wg.Add(1)
go func() {
defer wg.Done()
for i := 1; i <= bar3.Total; i++ {
bar3.Set(i)
time.Sleep(waitTime)
}
}()
// wait for all the go routines to finish
wg.Wait()
```
This will produce
![example](doc/example_multi.gif)
### `Incr` counter
[Bar.Incr()](https://godoc.org/github.com/gosuri/uiprogress#Bar.Incr) is an atomic counter and can be used as a general tracker, making it ideal for tracking progress of work fanned out to a lots of go routines. The source code for the below example is available at [example/incr/incr.go](example/incr/incr.go)
```go
runtime.GOMAXPROCS(runtime.NumCPU()) // use all available cpu cores
// create a new bar and prepend the task progress to the bar and fanout into 1k go routines
count := 1000
bar := uiprogress.AddBar(count).AppendCompleted().PrependElapsed()
bar.PrependFunc(func(b *uiprogress.Bar) string {
return fmt.Sprintf("Task (%d/%d)", b.Current(), count)
})
uiprogress.Start()
var wg sync.WaitGroup
// fanout into go routines
for i := 0; i < count; i++ {
wg.Add(1)
go func() {
defer wg.Done()
time.Sleep(time.Millisecond * time.Duration(rand.Intn(500)))
bar.Incr()
}()
}
time.Sleep(time.Second) // wait for a second for all the go routines to finish
wg.Wait()
uiprogress.Stop()
```
## Installation
```sh
$ go get -v github.com/gosuri/uiprogress
```
## Todos
- [ ] Resize bars and decorators by auto detecting window's dimensions
- [ ] Handle more progress bars than vertical screen allows
## License
uiprogress is released under the MIT License. See [LICENSE](https://github.com/gosuri/uiprogress/blob/master/LICENSE).
package uiprogress
import (
"bytes"
"errors"
"fmt"
"sync"
"time"
"github.com/gosuri/uiprogress/util/strutil"
)
var (
// Fill is the default character representing completed progress
Fill byte = '='
// Head is the default character that moves when progress is updated
Head byte = '>'
// Empty is the default character that represents the empty progress
Empty byte = '-'
// LeftEnd is the default character in the left most part of the progress indicator
LeftEnd byte = '['
// RightEnd is the default character in the right most part of the progress indicator
RightEnd byte = ']'
// Width is the default width of the progress bar
Width = 70
// ErrMaxCurrentReached is error when trying to set current value that exceeds the total value
ErrMaxCurrentReached = errors.New("errors: current value is greater total value")
)
// Bar represents a progress bar
type Bar struct {
// Total of the total for the progress bar
Total int
// LeftEnd is character in the left most part of the progress indicator. Defaults to '['
LeftEnd byte
// RightEnd is character in the right most part of the progress indicator. Defaults to ']'
RightEnd byte
// Fill is the character representing completed progress. Defaults to '='
Fill byte
// Head is the character that moves when progress is updated. Defaults to '>'
Head byte
// Empty is the character that represents the empty progress. Default is '-'
Empty byte
// TimeStated is time progress began
TimeStarted time.Time
// Width is the width of the progress bar
Width int
// timeElased is the time elapsed for the progress
timeElapsed time.Duration
current int
mtx *sync.RWMutex
appendFuncs []DecoratorFunc
prependFuncs []DecoratorFunc
}
// DecoratorFunc is a function that can be prepended and appended to the progress bar
type DecoratorFunc func(b *Bar) string
// NewBar returns a new progress bar
func NewBar(total int) *Bar {
return &Bar{
Total: total,
Width: Width,
LeftEnd: LeftEnd,
RightEnd: RightEnd,
Head: Head,
Fill: Fill,
Empty: Empty,
mtx: &sync.RWMutex{},
}
}
// Set the current count of the bar. It returns ErrMaxCurrentReached when trying n exceeds the total value. This is atomic operation and concurancy safe.
func (b *Bar) Set(n int) error {
b.mtx.Lock()
defer b.mtx.Unlock()
if n > b.Total {
return ErrMaxCurrentReached
}
if b.TimeStarted.IsZero() {
b.TimeStarted = time.Now()
}
b.timeElapsed = time.Since(b.TimeStarted)
b.current = n
return nil
}
// Incr increments the current value by 1, time elapsed to current time and returns true. It returns false if the cursor has reached or exceeds total value.
func (b *Bar) Incr() bool {
b.mtx.Lock()
defer b.mtx.Unlock()
n := b.current + 1
if n > b.Total {
return false
}
if b.TimeStarted.IsZero() {
b.TimeStarted = time.Now()
}
b.timeElapsed = time.Since(b.TimeStarted)
b.current = n
return true
}
// Current returns the current progress of the bar
func (b *Bar) Current() int {
b.mtx.RLock()
defer b.mtx.RUnlock()
return b.current
}
// AppendFunc runs the decorator function and renders the output on the right of the progress bar
func (b *Bar) AppendFunc(f DecoratorFunc) *Bar {
b.mtx.Lock()
defer b.mtx.Unlock()
b.appendFuncs = append(b.appendFuncs, f)
return b
}
// AppendCompleted appends the completion percent to the progress bar
func (b *Bar) AppendCompleted() *Bar {
b.AppendFunc(func(b *Bar) string {
return b.CompletedPercentString()
})
return b
}
// AppendElapsed appends the time elapsed the be progress bar
func (b *Bar) AppendElapsed() *Bar {
b.AppendFunc(func(b *Bar) string {
return strutil.PadLeft(b.TimeElapsedString(), 5, ' ')
})
return b
}
// PrependFunc runs decorator function and render the output left the progress bar
func (b *Bar) PrependFunc(f DecoratorFunc) *Bar {
b.mtx.Lock()
defer b.mtx.Unlock()
b.prependFuncs = append(b.prependFuncs, f)
return b
}
// PrependCompleted prepends the precent completed to the progress bar
func (b *Bar) PrependCompleted() *Bar {
b.PrependFunc(func(b *Bar) string {
return b.CompletedPercentString()
})
return b
}
// PrependElapsed prepends the time elapsed to the begining of the bar
func (b *Bar) PrependElapsed() *Bar {
b.PrependFunc(func(b *Bar) string {
return strutil.PadLeft(b.TimeElapsedString(), 5, ' ')
})
return b
}
// Bytes returns the byte presentation of the progress bar
func (b *Bar) Bytes() []byte {
completedWidth := int(float64(b.Width) * (b.CompletedPercent() / 100.00))
// add fill and empty bits
var buf bytes.Buffer
for i := 0; i < completedWidth; i++ {
buf.WriteByte(b.Fill)
}
for i := 0; i < b.Width-completedWidth; i++ {
buf.WriteByte(b.Empty)
}
// set head bit
pb := buf.Bytes()
if completedWidth > 0 && completedWidth < b.Width {
pb[completedWidth-1] = b.Head
}
// set left and right ends bits
pb[0], pb[len(pb)-1] = b.LeftEnd, b.RightEnd
// render append functions to the right of the bar
for _, f := range b.appendFuncs {
pb = append(pb, ' ')
pb = append(pb, []byte(f(b))...)
}
// render prepend functions to the left of the bar
for _, f := range b.prependFuncs {
args := []byte(f(b))
args = append(args, ' ')
pb = append(args, pb...)
}
return pb
}
// String returns the string representation of the bar
func (b *Bar) String() string {
return string(b.Bytes())
}
// CompletedPercent return the percent completed
func (b *Bar) CompletedPercent() float64 {
return (float64(b.Current()) / float64(b.Total)) * 100.00
}
// CompletedPercentString returns the formatted string representation of the completed percent
func (b *Bar) CompletedPercentString() string {
return fmt.Sprintf("%3.f%%", b.CompletedPercent())
}
// TimeElapsed returns the time elapsed
func (b *Bar) TimeElapsed() time.Duration {
b.mtx.RLock()
defer b.mtx.RUnlock()
return b.timeElapsed
}
// TimeElapsedString returns the formatted string represenation of the time elapsed
func (b *Bar) TimeElapsedString() string {
return strutil.PrettyTime(b.TimeElapsed())
}
package uiprogress
import (
"math/rand"
"runtime"
"strings"
"sync"
"testing"
"time"
)
func TestBarPrepend(t *testing.T) {
b := NewBar(100)
b.PrependCompleted()
b.Set(50)
if !strings.Contains(b.String(), "50") {
t.Fatal("want", "50%", "in", b.String())
}
}
func TestBarIncr(t *testing.T) {
b := NewBar(10000)
runtime.GOMAXPROCS(runtime.NumCPU())
var wg sync.WaitGroup
for i := 0; i < 10000; i++ {
wg.Add(1)
go func() {
defer wg.Done()
b.Incr()
time.Sleep(time.Millisecond * time.Duration(rand.Intn(10)))
}()
}
wg.Wait()
if b.Current() != 10000 {
t.Fatal("need", 10000, "got", b.Current())
}
}
// Package uiprogress is a library to render progress bars in terminal applications
package uiprogress
package main
import (
"fmt"
"sync"
"time"
"github.com/gosuri/uiprogress"
)
func main() {
waitTime := time.Millisecond * 200
p := uiprogress.New()
p.Start()
var wg sync.WaitGroup
bar1 := p.AddBar(20).AppendCompleted().PrependElapsed()
wg.Add(1)
go func() {
defer wg.Done()
for bar1.Incr() {
time.Sleep(waitTime)
}
fmt.Fprintln(p.Bypass(), "Bar1 finished")
}()
bar2 := p.AddBar(40).AppendCompleted().PrependElapsed()
wg.Add(1)
go func() {
defer wg.Done()
for bar2.Incr() {
time.Sleep(waitTime)
}
fmt.Fprintln(p.Bypass(), "Bar2 finished")
}()
time.Sleep(time.Second)
bar3 := p.AddBar(20).PrependElapsed().AppendCompleted()
wg.Add(1)
go func() {
defer wg.Done()
for bar3.Incr() {
time.Sleep(waitTime)
}
fmt.Fprintln(p.Bypass(), "Bar3 finished")
}()
wg.Wait()
}
package main
import (
"fmt"
"math/rand"
"sync"
"time"
"github.com/gosuri/uiprogress"
"github.com/gosuri/uiprogress/util/strutil"
)
var steps = []string{
"downloading source",
"installing deps",
"compiling",
"packaging",
"seeding database",
"deploying",
"staring servers",
}
func main() {
fmt.Println("apps: deployment started: app1, app2")
uiprogress.Start()
var wg sync.WaitGroup
wg.Add(1)
go deploy("app1", &wg)
wg.Add(1)
go deploy("app2", &wg)
wg.Wait()
fmt.Println("apps: successfully deployed: app1, app2")
}
func deploy(app string, wg *sync.WaitGroup) {
defer wg.Done()
bar := uiprogress.AddBar(len(steps)).AppendCompleted().PrependElapsed()
bar.Width = 50
// prepend the deploy step to the bar
bar.PrependFunc(func(b *uiprogress.Bar) string {
return strutil.Resize(app+": "+steps[b.Current()-1], 22)
})
rand.Seed(500)
for bar.Incr() {
time.Sleep(time.Millisecond * time.Duration(rand.Intn(2000)))
}
}
package main
import (
"fmt"
"math/rand"
"runtime"
"sync"
"time"
"github.com/gosuri/uiprogress"
)
func main() {
runtime.GOMAXPROCS(runtime.NumCPU()) // use all available cpu cores
// create a new bar and prepend the task progress to the bar and fanout into 1k go routines
count := 1000
bar := uiprogress.AddBar(count).AppendCompleted().PrependElapsed()
bar.PrependFunc(func(b *uiprogress.Bar) string {
return fmt.Sprintf("Task (%d/%d)", b.Current(), count)
})
uiprogress.Start()
var wg sync.WaitGroup
// fanout into 1k go routines
for i := 0; i < count; i++ {
wg.Add(1)
go func() {
defer wg.Done()
time.Sleep(time.Millisecond * time.Duration(rand.Intn(500)))
bar.Incr()
}()
}
time.Sleep(time.Second) // wait for a second for all the go routines to finish
wg.Wait()
uiprogress.Stop()
}
package main
import (
"sync"
"time"
"github.com/gosuri/uiprogress"
)
func main() {
waitTime := time.Millisecond * 100
uiprogress.Start()
var wg sync.WaitGroup
bar1 := uiprogress.AddBar(20).AppendCompleted().PrependElapsed()
wg.Add(1)
go func() {
defer wg.Done()
for bar1.Incr() {
time.Sleep(waitTime)
}
}()
bar2 := uiprogress.AddBar(40).AppendCompleted().PrependElapsed()
wg.Add(1)
go func() {
defer wg.Done()
for bar2.Incr() {
time.Sleep(waitTime)
}
}()
time.Sleep(time.Second)
bar3 := uiprogress.AddBar(20).PrependElapsed().AppendCompleted()
wg.Add(1)
go func() {
defer wg.Done()
for bar3.Incr() {
time.Sleep(waitTime)
}
}()
wg.Wait()
}
package main
import (
"time"
"github.com/gosuri/uiprogress"
)
func main() {
uiprogress.Start() // start rendering
bar := uiprogress.AddBar(100) // Add a new bar
// optionally, append and prepend completion and elapsed time
bar.AppendCompleted()
bar.PrependElapsed()
for bar.Incr() {
time.Sleep(time.Millisecond * 20)
}
}
package uiprogress_test
import (
"fmt"
"math/rand"
"runtime"
"sync"
"time"
"github.com/gosuri/uiprogress"
)
func Example() {
uiprogress.Start() // start rendering
bar := uiprogress.AddBar(100) // Add a new bar
// optionally, append and prepend completion and elapsed time
bar.AppendCompleted()
bar.PrependElapsed()
for bar.Incr() {
time.Sleep(time.Millisecond * 20)
}
}
func ExampleProgress_AddBar() {
waitTime := time.Millisecond * 100
uiprogress.Start()
// start the progress bars in go routines
var wg sync.WaitGroup
bar1 := uiprogress.AddBar(20).AppendCompleted().PrependElapsed()
wg.Add(1)
go func() {
defer wg.Done()
for bar1.Incr() {
time.Sleep(waitTime)
}
}()
bar2 := uiprogress.AddBar(40).AppendCompleted().PrependElapsed()
wg.Add(1)
go func() {
defer wg.Done()
for bar2.Incr() {
time.Sleep(waitTime)
}
}()
time.Sleep(time.Second)
bar3 := uiprogress.AddBar(20).PrependElapsed().AppendCompleted()
wg.Add(1)
go func() {
defer wg.Done()
for i := 1; i <= bar3.Total; i++ {
bar3.Set(i)
time.Sleep(waitTime)
}
}()
// wait for all the go routines to finish
wg.Wait()
}
func ExampleDecoratorFunc() {
var steps = []string{"downloading source", "installing deps", "compiling", "packaging", "seeding database", "deploying", "staring servers"}
bar := uiprogress.AddBar(len(steps))
// prepend the current step to the bar
bar.PrependFunc(func(b *uiprogress.Bar) string {
return "app: " + steps[b.Current()-1]
})
for bar.Incr() {