bar

This package is a port of the progress package, written in Golang.

Installation

go get github.com/superhawk610/bar github.com/superhawk610/terminal

Getting Started

package main

import (
	"time"

	"github.com/superhawk610/bar"
)

func main() {
	n := 20
	b := bar.New(30)

	for i := 0; i < n; i++ {
		b.Tick()
		time.Sleep(500 * time.Millisecond)
	}

	b.Done()
}

There are additional examples of more advanced usage in the examples directory.

Colored Output

This package works well with color libraries like ttacon/chalk. In order to get the output displayed in the GIF above, you'd use it like so:

package main

import (
	"time"
	"fmt"
	"github.com/superhawk610/bar"
	"github.com/ttacon/chalk"
)

func main() {
	n := 20
	b := bar.NewWithOpts(
		bar.WithDimensions(20, 20),
		bar.WithFormat(
			fmt.Sprintf(
				" %sloading...%s :percent :bar %s:rate ops/s%s ",
				chalk.Blue,
				chalk.Reset,
				chalk.Green,
				chalk.Reset,
			),
		),
	)

	for i := 0; i < n; i++ {
		b.Tick()
		time.Sleep(500 * time.Millisecond)
	}

	b.Done()
}

Configuration

This package uses the functional options pattern to support incremental configuration. To create a new instance of bar with options, use the bar.NewWithOpts function and provide any number of configuration augments (listed below).

WithCallback(cb func())

Provide a callback function to be executed when the bar is completed via b.Done().

WithDisplay(start, complete, head, incomplete, end string)

Provide display characters to be used when outputting the bar to the terminal.

[ xxx >    ]
| |   | |  |- end
| |   | |- incomplete
| |   |- head
| |- complete
|- start

WithDimensions(total, width int)

Provide dimensions for the total value of the progress bar and its output width.

WithOutput(out Output)

Provide an output stream for displaying the progress bar. Output is essentially an io.Writer, but it also exposes a ClearLine() function to clear the current line of output and return the cursor to the first index. By default, this uses os.Stdout.

WithContext(ctx Context)

Provide an initial value for the bar's context (read more about how to use context with custom verbs below).

WithFormat(f string)

Provide an ordering of verbs to be used when outputting the progress bar. You can choose from the standard included verbs :bar, :progress, :rate, and :eta, or you can provide your own verbs using the Ctx helper. Verbs must always be prefixed with :.

Standard Verbs

The following verbs are included:

:bar

Output the progress bar visual.

[------>           ]

:percent

Output the total progress percentage.

38.4%

:rate

Output the total progress rate (in completed ticks per second).

2.1 ops/s

NOTE: This verb does not display a unit by default, so you'll need to provide your own units (eg - ops/s).

:eta

Output the estimated time remaining before completion (formatted by time.Duration.String()).

16m28s

Until the bar has established a rate of progress, this verb won't display anything.

Custom Verbs

You can provide your own verbs when defining a format. Custom verbs must be prefixed with a colon :. You may not use any of the standard verbs as custom verbs.

First, include the verb when defining your format:

b := bar.NewWithOpts(
	bar.WithDimensions(n, 30),
	bar.WithFormat(" :bar :hello :world "),
)

You'll also probably want to include a default value for each custom verb using the WithContext helper mentioned above.

Then, whenever ticking or updating your progress bar, provide a Context slice with the value(s) you'd like to have displayed in their place. Use the Ctx helper to clean up the syntax:

b.TickAndUpdate(bar.Context{
	bar.Ctx("hello", "Hello,"),
	bar.Ctx("world", "world!"),
})

This will produce the following output:

[----->            ] Hello, world!

WithDebug()

Debugging crowded layouts can be difficult, so this helper swaps each bar component's print() method for its debug() method, displaying its internal state and type.

 <barToken p={4} t={10}> <percentToken "40.0%"> <customVerbToken verb="hello" value="Hello!">

Changelog

See CHANGELOG.md.

License

Copyright © 2019 Aaron Ross, all rights reserved. View the ISC license here.