liveprogress

package module
v2.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 6, 2024 License: MIT Imports: 14 Imported by: 0

README

liveprogress

PkgGoDev

liveprogress is a golang library allowing to print and update progress bars on a terminal. It is heavily inspired by uiprogress but redone on top of the forked liveterm library in order to take advantage of its enhancements.

In addition of the features of liveterm, it also add (or changes):

  • Automatic bar length if its width is 0
  • Bars characters are runes (Unicode support thru liveterm)
  • Remove unecessary mutexes
    • usage of atomic operations for bar progress
    • decorators can be added only when instanciating the bar
  • Custom (dynamic) lines that can be anything (not necessarly a progress bar)
  • Main line concept: a bar or a custom line that will always be printed last (usefull for global progress when others lines above it indicate specific progress)
  • Ability to style the bar and decorators using termenv styles

Examples

Simple

Code available here.

if err := liveprogress.Start(); err != nil {
	panic(err)
}
bar := liveprogress.AddBar(
	liveprogress.WithPrependPercent(liveprogress.BaseStyle()),
	liveprogress.WithAppendDecorator(func(bar *liveprogress.Bar) string {
		return " Remaining:"
	}),
	liveprogress.WithAppendTimeRemaining(liveprogress.BaseStyle()),
)
// By default a bar total is set to 100
for i := 0; i < liveprogress.DefaultTotal; i++ {
	// Wait a random time
	time.Sleep(time.Duration(rand.Intn(300)) * time.Millisecond)
	// Increment the bar
	bar.CurrentIncrement()
}
if err := liveprogress.Stop(true); err != nil {
	panic(err)
}
fmt.Println("By setting the Stop() bool parameter to true, the progress bar is cleared at stop.")

Simple example output animation

Advanced

See full source code here.

Advanced example output animation

Installation

go get -v github.com/hekmon/liveprogress/v2

Documentation

Index

Constants

View Source 
const (
	DefaultTotal = 100 // DefaultTotal is the default total value of a progress bar. See WithTotal() to change a bar total at creation.

)

Variables

View Source 
var (
	// Config values (used by Start())
	RefreshInterval = 100 * time.Millisecond // RefreshInterval is the time between each refresh of the terminal. Recommended value, setting it lower might flicker the terminal and increase CPU usage.
	Output          = os.Stdout              // Output is the writer the live progress will write to.
	// BarAutoSizeSameSize sets progress bars with automatic width (width of 0) to automatically adjust theirs width (and center themself) to all others automatic width bars.
	// By default left and right decorators will have external padding to center all the automatic length bars, eaning that white spaces will be added to the left for left
	// decorators group and to the right for right decorators group. See WithInternalPadding() at bar creation to change the padding position.
	BarsAutoSizeSameSize = true
)

Functions

func BaseStyle 

func BaseStyle() termenv.Style

BaseStyle returns a base termenv style with its terminal profile correctly set. You can use it to create your own styles by modifying the returned style and use it in decorators. You should call this function after Start() if you have changed default Output value.

func Bypass 

func Bypass() io.Writer

Bypass returns a writer that will bypass the live progress and write directly to the output without being wiped by the next refresh.

func GetTermProfile 

func GetTermProfile() termenv.Profile

GetTermProfile returns the termenv profile used by liveprogress (actually by liveterm). It can be used to create styles and colors that will be compatible with the terminal. See BaseStyle() for a more high level helper. You should call this function after Start() if you have changed default Output value.

func HasDarkBackground 

func HasDarkBackground() bool

HasDarkBackground returns whether terminal uses a dark-ish background. You should call this function after Start() if you have changed default Output value. 

func Hyperlink(link string, name string) string

Hyperlink creates a hyperlink that can be printed to the terminal.

func Notify 

func Notify(title, body string)

Notify triggers a notification. You should call this function after Start() if you have changed default Output value.

func RemoveAll 

func RemoveAll()

RemoveAll removes all bars and custom lines from the live progress but does not stop the liveprogress itself.

func RemoveBar 

func RemoveBar(pb *Bar)

RemoveBar removes a bar from the live progress. This is needed only if you want to remove a bar while leaving liveprogress running, otherwise use Stop(true).

func RemoveCustomLine 

func RemoveCustomLine(cl *CustomLine)

RemoveCustomLine removes a custom line from the live progress.

func Start 

func Start() (err error)

Start starts the live progress. It will render every bars and custom lines added after. It is important to note that Output (default to os.Stdout) should not be used directly (for example with fmt.Print*()) after Start() is called and until Stop() is called. See ByPass() to get a writer that will bypass the live progress and write definitive lines directly to the output without disrupting live progress.

func Stop 

func Stop(clear bool) (err error)

Stop stops the live progress and remove all registered bars and custom lines from its internal state. Set clear to true to clear the liveprogress output. After this call, Output can be used directly again (no need to use ByPass() anymore).

Types

type Bar 

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

Bar is a progress bar that can be added to the live progress. Do not instanciate it directly, use AddBar() instead.

func AddBar 

func AddBar(opts ...BarOption) (pb *Bar)

AddBar adds a new progress bar to the live progress. Only call it after Start() has been called.

func SetMainLineAsBar 

func SetMainLineAsBar(opts ...BarOption) (pb *Bar)

SetMainLineAsBar sets the main line as a bar. MainLine will always be the last line. Only call it after Start() has been called.

func (*Bar) Current 

func (pb *Bar) Current() uint64

Current returns the current value of the progress bar.

func (*Bar) CurrentAdd 

func (pb *Bar) CurrentAdd(value uint64)

CurrentAdd adds a value to the current value of the progress bar.

func (*Bar) CurrentIncrement 

func (pb *Bar) CurrentIncrement()

CurrentIncrement increments the current value of the progress bar by 1.

func (*Bar) CurrentSet 

func (pb *Bar) CurrentSet(value uint64)

CurrentSet sets the current value of the progress bar.

func (*Bar) GetCreationTime 

func (pb *Bar) GetCreationTime() time.Time

GetCreationTime returns the time at which the progress bar was created.

func (*Bar) Progress 

func (pb *Bar) Progress() float64

Progress returns the progress of the bar as a float64 between 0 and 1.

func (*Bar) String 

func (pb *Bar) String() (line string)

String returns a naive (does not support the AutoSizeSameSize) string representation of the progress bar.

func (*Bar) Total 

func (pb *Bar) Total() uint64

Total returns the total value of the progress bar.

type BarOption 

type BarOption func(*Bar)

BarOption is a function that can be used to configure a progress bar at creation, see AddBar() or SetMainLineAsBar().

func WithASCIIRunes 

func WithASCIIRunes() BarOption

WithASCIIRunes sets the style of the progress bar to an ASCII style. This is applied by default.

func WithAppendDecorator 

func WithAppendDecorator(decorators ...DecoratorFunc) BarOption

WithAppendDecorator adds a decorator function to the end of the progress bar.

func WithAppendPercent 

func WithAppendPercent(style termenv.Style) BarOption

WithAppendPercent adds the percentage of the progress bar to the end of the bar. Use BaseStyle() if you do not want any particular style.

func WithAppendTimeElapsed 

func WithAppendTimeElapsed(style termenv.Style) BarOption

WithAppendTimeElapsed adds the time elapsed since the creation of the progress bar to the end of the bar. Use BaseStyle() if you do not want any particular style.

func WithAppendTimeRemaining 

func WithAppendTimeRemaining(style termenv.Style) BarOption

WithAppendTimeRemaining adds the time remaining until the end of the progress bar to the end of the bar. Use BaseStyle() if you do not want any particular style.

func WithBarStyle 

func WithBarStyle(style termenv.Style) BarOption

WithBarStyle sets the style of the progress bar. See advanced example for style usage.

func WithLineFillRunes 

func WithLineFillRunes() BarOption

WithLineFillRunes sets the style of the progress bar to an box drawing lines style.

func WithMultiplyRunes 

func WithMultiplyRunes() BarOption

func WithPlainRunes 

func WithPlainRunes() BarOption

WithPlainRunes sets the style of the progress bar to a plain style.

func WithPrependDecorator 

func WithPrependDecorator(decorators ...DecoratorFunc) BarOption

WithPrependDecorator adds a decorator function to the beginning of the progress bar.

func WithPrependPercent 

func WithPrependPercent(style termenv.Style) BarOption

WithPrependPercent adds the percentage of the progress bar to the beginning of the bar. Use BaseStyle() if you do not want any particular style.

func WithPrependTimeElapsed 

func WithPrependTimeElapsed(style termenv.Style) BarOption

WithPrependTimeElapsed adds the time elapsed since the creation of the progress bar to the beginning of the bar. Use BaseStyle() if you do not want any particular style.

func WithPrependTimeRemaining 

func WithPrependTimeRemaining(style termenv.Style) BarOption

WithPrependTimeRemaining adds the time remaining until the end of the progress bar to the beginning of the bar. Use BaseStyle() if you do not want any particular style.

func WithRunes 

func WithRunes(runes BarRunes) BarOption

WithRunes sets the runes used by the progress bar.

func WithSameAutoSizeInternalPadding added in v2.1.0 

func WithSameAutoSizeInternalPadding(left, right bool) BarOption

WithInternalPadding sets the padding to be internal instead of external for left and right decorators. Only usefull if WithSameAutoSize() has been set too.

func WithTotal 

func WithTotal(total uint64) BarOption

WithTotal sets the total value of the progress bar.

func WithWidth 

func WithWidth(width int) BarOption

WithWidth sets the width of the progress bar. By default the width is set to 0: the bar will take the full terminal width (minus decorators). Auto width can be aligned with others auto width bars with WithSameAutoSize().

type BarRunes 

type BarRunes struct {
	LeftEnd  rune
	Fill     rune
	Head     rune
	Empty    rune
	RightEnd rune
}

BarRunes is the composition of a progress bar.

func (BarRunes) Valid 

func (b BarRunes) Valid() bool

Valid returns true if all the mandatory runes are set (Fill, Head and Empty).

type CustomLine 

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

CustomLine is a custom line to add to the live progress. Do not instantiate it directly, use AddCustomLine() instead.

func AddCustomLine 

func AddCustomLine(generator func() string) (cl *CustomLine)

AddCustomLine adds a custom line to the live progress. Only call it after Start() has been called.

func SetMainLineAsCustomLine 

func SetMainLineAsCustomLine(generator func() string) (cl *CustomLine)

SetMainLineAsCustomLine sets the main line as a custom line. MainLine will always be the last line. Only call it after Start() has been called.

func (*CustomLine) String 

func (cl *CustomLine) String() string

Implements fmt.Stringer needed as a liveprogress item.

type DecoratorFunc 

type DecoratorFunc func(pb *Bar) string

DecoratorFunc is a function that can be used to decorate the progress bar.

type Spinner 

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

Spinner is a custom item that can be added as custom DecoratorFunc.

func (*Spinner) Next 

func (s *Spinner) Next() string

Next returns the next spinner state, call it in a loop to animate the spinner.

func (*Spinner) String 

func (s *Spinner) String() string

String implements the fmt.Stringer interface

Source Files

View all Source files

Directories

Path Synopsis
examples
advanced command
simple command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.