pogs

README

pogs

A thread-safe go library for displaying multiple progress bars in unix terminals.

Progress bars typically clear and redraw the line as they update. Using a progress bar library not designed to display multiple progress bars to do so would cause each progress bar to rewrite each other.

The pogs library supports displaying multiple progress bars by moving and keeping track of the cursor position.

Additionally, the pogs library separates the method for creating a progress bar into NewBar and Start to support use cases where the jobs of the progress bar may complete before we know the number of the jobs (see example below).

Installation

The pogs library depends on golang.org/x/sys, which hangs forever if you have GOPROXY=direct in your environment. Install with the cache proxy instead:

GOPROXY="" go get -u git.sr.ht/~liliace/pogs

Example

In this example, we don't know the size of each progress bar until after we have finished each inner loop. We are still able to advance the progress bar data with bars.Add before displaying it with bars.Start.

bars, err := pogs.NewBars()
if err != nil {
	log.Fatal(err)
}

for _ = range 5 {
	id, _ := bars.NewBar()
	size := 0
	// consider root a pre-defined node of some linked-list
	for curr := root; curr != nil; curr = curr.Next {
		bars.Add(id)
		size += 1
	}
	bars.Start(id, size)
}
bars.Done()

The id returned by bars.NewBar is the id-th bar created, so the loop above can be simplified to:

for i = range 5 {
	bars.NewBar()
	size := 0
	for curr := root; curr != nil; curr = curr.Next {
		bars.Add(i)
		size += 1
	}
	bars.Start(i, size)
}

Documentation

Overview

Package pogs provides thread-safe methods for displaying multiple progress bars in unix terminals.

Index

• type Bars
  • func NewBars() (*Bars, error)
  • func (b *Bars) Add(i int)
  • func (b *Bars) Done()
  • func (b *Bars) NewBar() (i int, err error)
  • func (b *Bars) Start(i, total int)

Types

type Bars

type Bars struct {
	// contains filtered or unexported fields
}

Bars controls a group of progress bars.

func NewBars

func NewBars() (*Bars, error)

NewBars instanciates a Bars struct. NewBars returns an error if it is unable to get the terminal width.

func (*Bars) Add

func (b *Bars) Add(i int)

Add increments the i-th progress bar by one unit.

func (*Bars) Done

func (b *Bars) Done()

Done tells the Bars struct that the user is done creating progress bars with Bars.NewBar. When all progress bars are complete, the cursor will move to the bottom and print a newline character for the next write to stdout to appear on a new line.

func (*Bars) NewBar

func (b *Bars) NewBar() (i int, err error)

NewBar creates a new progress bar and returns an index to pass to Bars.Add and Bars.Start. The progress bar is created but not displayed until called with Bars.Start.

The index is always the i-th progress bar created, starting at 0. If your program already keeps track of an index per progress bar (eg. creating one progress bar per iteration in an index-based loop), you may use it instead.

NewBar returns an error if Bars.Done has been called.

func (*Bars) Start

func (b *Bars) Start(i, total int)

Start sets the total units of the i-th progress bar and starts displaying it.