progress

package
v3.2.4 Latest Latest
Warning

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

 Go to latest Published: Dec 12, 2024 License: MIT Imports: 10 Imported by: 6

README

Progress Display

Package progress provide terminal progress bar display. Such as: Txt, Bar, Loading, RoundTrip, DynamicText ...

  • progress bar
  • text progress bar
  • pending/loading progress bar
  • counter
  • dynamic Text

GoDoc

Please see https://pkg.go.dev/github.com/gookit/gcli/v3/progress

Install

go get github.com/gookit/gcli/v3/progress

Usage

Examples:

package main

import (
	"time"

	"github.com/gookit/gcli/v3/progress"
)

func main()  {
	speed := 100
	maxSteps := 110
	p := progress.Bar(maxSteps)
	p.Start()

	for i := 0; i < maxSteps; i++ {
		time.Sleep(time.Duration(speed) * time.Millisecond)
		p.Advance()
	}

	p.Finish()
}

More demos please see progress_demo.go

run demos:

go run ./_examples/cliapp.go prog txt
go run ./_examples/cliapp.go prog bar
go run ./_examples/cliapp.go prog roundTrip

Progress Bar

Internal Widgets
Widget Name Usage example Description
max {@max} Display max steps for progress bar
current {@current} Display current steps for progress bar
percent {@percent:4s} Display percent for progress run
elapsed {@elapsed:7s} Display has elapsed time for progress run
remaining {@remaining:7s} Display remaining time
estimated {@estimated:-7s} Display estimated time
memory {@memory:6s} Display memory consumption size
Custom Progress Bar

Allow you custom progress bar render format. There are internal format for Progress

// txt bar
MinFormat  = "{@message}{@current}"
TxtFormat  = "{@message}{@percent:4s}%({@current}/{@max})"
DefFormat  = "{@message}{@percent:4s}%({@current}/{@max})"
FullFormat = "{@percent:4s}%({@current}/{@max}) {@elapsed:7s}/{@estimated:-7s} {@memory:6s}"

// bar

DefBarFormat  = "{@bar} {@percent:4s}%({@current}/{@max}){@message}"
FullBarFormat = "{@bar} {@percent:4s}%({@current}/{@max}) {@elapsed:7s}/{@estimated:-7s} {@memory:6s}"

Examples:

package main
import "github.com/gookit/gcli/v3/progress"

// CustomBar create custom progress bar
func main() {
    maxSteps := 100
	// use special bar style: [==============>-------------]
	// barStyle := progress.BarStyles[0]
	// use random bar style
	barStyle := progress.RandomBarStyle()

	p: = progress.New(maxSteps).
	Config(func(p *Progress) {
		p.Format = progress.DefBarFormat
	}).
	AddWidget("bar", progress.BarWidget(60, barStyle))

	p.Start()

	for i := 0; i < maxStep; i++ {
		time.Sleep(80 * time.Millisecond)
		p.Advance()
	}

	p.Finish()
}
Progress Functions

Quick create progress bar:

func Bar(maxSteps ...int) *Progress
func Counter(maxSteps ...int) *Progress
func CustomBar(width int, cs BarChars, maxSteps ...int) *Progress
func DynamicText(messages map[int]string, maxSteps ...int) *Progress
func Full(maxSteps ...int) *Progress
func LoadBar(chars []rune, maxSteps ...int) *Progress
func LoadingBar(chars []rune, maxSteps ...int) *Progress
func New(maxSteps ...int) *Progress
func NewWithConfig(fn func(p *Progress), maxSteps ...int) *Progress
func RoundTrip(char rune, charNumAndBoxWidth ...int) *Progress
func RoundTripBar(char rune, charNumAndBoxWidth ...int) *Progress
func SpinnerBar(chars []rune, maxSteps ...int) *Progress
func Tape(maxSteps ...int) *Progress
func Txt(maxSteps ...int) *Progress

Spinner Bar

Spinner Functions

Quick create progress spinner:

func LoadingSpinner(chars []rune, speed time.Duration) *SpinnerFactory
func RoundTripLoading(char rune, speed time.Duration, charNumAndBoxWidth ...int) *SpinnerFactory
func RoundTripSpinner(char rune, speed time.Duration, charNumAndBoxWidth ...int) *SpinnerFactory
func Spinner(speed time.Duration) *SpinnerFactory

Documentation

Overview

Package progress provide terminal progress bar display. Such as: `Txt`, `Bar`, `Loading`, `RoundTrip`, `DynamicText` ...

Index

Examples

Constants

View Source 
const (
	CharStar    rune = '*'
	CharPlus    rune = '+'
	CharWell    rune = '#'
	CharEqual   rune = '='
	CharEqual1  rune = '═'
	CharSpace   rune = ' '
	CharCenter  rune = '●'
	CharSquare  rune = '■'
	CharSquare1 rune = '▇'
	CharSquare2 rune = '▉'
	CharSquare3 rune = '░'
	CharSquare4 rune = '▒'
	CharSquare5 rune = '▢'
	// Hyphen Minus
	CharHyphen      rune = '-'
	CharCNHyphen    rune = '—'
	CharUnderline   rune = '_'
	CharLeftArrow   rune = '<'
	CharRightArrow  rune = '>'
	CharRightArrow1 rune = '▶'
)

some built in chars

View Source 
const (
	MinFormat  = "{@message}{@current}"
	TxtFormat  = "{@message}{@percent:4s}%({@current}/{@max})"
	DefFormat  = "{@message}{@percent:4s}%({@current}/{@max})"
	FullFormat = "{@percent:4s}%({@current}/{@max}) {@elapsed:7s}/{@estimated:-7s} {@memory:6s}"
)

internal format for text progress

View Source 
const (
	// BarWidth default bar width
	BarWidth  = 40
	BarFormat = "{@bar} {@percent:4s}%({@current}/{@max}){@message}"

	// MdlBarFormat more format
	MdlBarFormat  = "{@bar} {@percent:4s}%({@current}/{@max}) {@elapsed:7s}/{@estimated:-7s}"
	FullBarFormat = "{@bar} {@percent:4s}%({@current}/{@max}) {@elapsed:7s}/{@estimated:-7s} {@memory:6s}"
)

internal format for ProgressBar

Variables

View Source 
var BarStyles = []BarChars{
	{'=', '>', ' '},
	{'=', '>', '-'},
	{'#', '>', ' '},
	{'#', '>', '-'},
	{'*', '>', '-'},
	{'▉', '▉', '░'},
	{'■', '■', ' '},
	{'■', '■', '▢'},
	{'■', '▶', ' '},
}

BarStyles some built in BarChars style collection

View Source 
var CharThemes = []rune{
	CharEqual,
	CharCenter,
	CharSquare,
	CharSquare1,
	CharSquare2,
}

CharThemes collection. can use for Progress bar, RoundTripSpinner

View Source 
var CharsThemes = [][]rune{
	{'卍', '卐'},
	{'☺', '☻'},
	{'░', '▒', '▓'},
	{'⊘', '⊖', '⊕', '⊗'},
	{'◐', '◒', '◓', '◑'},
	{'✣', '✤', '✥', '❉'},
	{'-', '\\', '|', '/'},
	{'▢', '■', '▢', '■'},
	[]rune("▖▘▝▗"),
	[]rune("◢◣◤◥"),
	[]rune("⌞⌟⌝⌜"),
	[]rune("◎●◯◌○⊙"),
	[]rune("◡◡⊙⊙◠◠"),
	[]rune("⇦⇧⇨⇩"),
	[]rune("✳✴✵✶✷✸✹"),
	[]rune("←↖↑↗→↘↓↙"),
	[]rune("➩➪➫➬➭➮➯➱"),
	[]rune("①②③④"),
	[]rune("㊎㊍㊌㊋㊏"),
	[]rune("⣾⣽⣻⢿⡿⣟⣯⣷"),
	[]rune("⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"),
	[]rune("▉▊▋▌▍▎▏▎▍▌▋▊▉"),
	[]rune("🌍🌎🌏"),
	[]rune("☰☱☲☳☴☵☶☷"),
	[]rune("⠋⠙⠚⠒⠂⠂⠒⠲⠴⠦⠖⠒⠐⠐⠒⠓⠋"),
	[]rune("🕐🕑🕒🕓🕔🕕🕖🕗🕘🕙🕚🕛"),
}

CharsThemes collection. can use for LoadingBar, LoadingSpinner

Functions

func GetCharTheme 

func GetCharTheme(index int) rune

GetCharTheme by index number. if index not exist, will return a random theme

func GetCharsTheme 

func GetCharsTheme(index int) []rune

GetCharsTheme by index number

func MaxSteps 

func MaxSteps(maxStep int) func(p *Progress)

MaxSteps setting max steps

func RandomCharTheme 

func RandomCharTheme() rune

RandomCharTheme get

func RandomCharsTheme 

func RandomCharsTheme() []rune

RandomCharsTheme get

func RenderFormat 

func RenderFormat(f string) func(p *Progress)

RenderFormat set rendered format option

Types

type BarChars 

type BarChars struct {
	Completed, Processing, Remaining rune
}

BarChars setting for a progress bar. default {'#', '>', ' '}

func RandomBarStyle 

func RandomBarStyle() BarChars

RandomBarStyle get random bar style

type BuilderFunc 

type BuilderFunc func() string

BuilderFunc build char string

type Progress 

type Progress struct {
	// Format string the bar format
	Format string
	// Newline render progress on newline
	Newline bool
	// MaxSteps maximal steps.
	MaxSteps uint
	// StepWidth the width for display "{@current}". default is 2
	StepWidth uint8
	// Overwrite prev output. default is True
	Overwrite bool
	// RedrawFreq redraw freq. default is 1
	RedrawFreq uint8
	// Widgets for build the progress bar
	Widgets map[string]WidgetFunc
	// Messages named messages for build progress bar
	// Example:
	// 	{"msg": "downloading ..."}
	// 	"{@percent}% {@msg}" -> "83% downloading ..."
	Messages map[string]string
	// contains filtered or unexported fields
}

Progress definition Refer: 

https://github.com/inhere/php-console/blob/master/src/utils/ProgressBar.php

func Bar 

func Bar(maxSteps ...int) *Progress

Bar create a default progress bar. Preview: 

	1 [->--------------------------]
	3 [■■■>------------------------]
25/50 [==============>-------------]  50%
Example 
maxStep := 105
p := CustomBar(60, BarStyles[0], maxStep)
p.MaxSteps = uint(maxStep)
p.Format = FullBarFormat

p.Start()
for i := 0; i < maxStep; i++ {
	time.Sleep(80 * time.Millisecond)
	p.Advance()
}
p.Finish()

Output:

func Counter 

func Counter(maxSteps ...int) *Progress

Counter progress bar create

func CustomBar 

func CustomBar(width int, cs BarChars, maxSteps ...int) *Progress

CustomBar create a custom progress bar.

func DynamicText 

func DynamicText(messages map[int]string, maxSteps ...int) *Progress

DynamicText progress bar create

Example 
messages := map[int]string{
	// key is percent, range is 0 - 100.
	20:  " Prepare ...",
	40:  " Request ...",
	65:  " Transport ...",
	95:  " Saving ...",
	100: " Handle Complete.",
}

maxStep := 105
p := DynamicText(messages, maxStep)

p.Start()

for i := 0; i < maxStep; i++ {
	time.Sleep(80 * time.Millisecond)
	p.Advance()
}

p.Finish()

Output:

func Full 

func Full(maxSteps ...int) *Progress

Full text progress bar create.

func LoadBar 

func LoadBar(chars []rune, maxSteps ...int) *Progress

LoadBar create loading progress bar

func LoadingBar 

func LoadingBar(chars []rune, maxSteps ...int) *Progress

LoadingBar alias of load bar LoadBar()

func New 

func New(maxSteps ...int) *Progress

New Progress instance

func NewWithConfig 

func NewWithConfig(fn func(p *Progress), maxSteps ...int) *Progress

NewWithConfig create new Progress

func RoundTrip 

func RoundTrip(char rune, charNumAndBoxWidth ...int) *Progress

RoundTrip create a RoundTrip progress bar.

Usage: 

p := RoundTrip(CharEqual)
// p := RoundTrip('*') // custom char
p.Start()
....
p.Finish()

func RoundTripBar 

func RoundTripBar(char rune, charNumAndBoxWidth ...int) *Progress

RoundTripBar alias of RoundTrip()

func SpinnerBar 

func SpinnerBar(chars []rune, maxSteps ...int) *Progress

SpinnerBar alias of load bar LoadBar()

func Tape 

func Tape(maxSteps ...int) *Progress

Tape create new tape progress bar. is alias of Bar()

func Txt 

func Txt(maxSteps ...int) *Progress

Txt progress bar create.

func (*Progress) AddMessage 

func (p *Progress) AddMessage(name, message string)

AddMessage to progress instance

func (*Progress) AddMessages 

func (p *Progress) AddMessages(msgMap map[string]string)

AddMessages to progress instance

func (*Progress) AddWidget 

func (p *Progress) AddWidget(name string, handler WidgetFunc) *Progress

AddWidget to progress instance

func (*Progress) AddWidgets 

func (p *Progress) AddWidgets(widgets map[string]WidgetFunc)

AddWidgets to progress instance

func (*Progress) Advance 

func (p *Progress) Advance(steps ...uint)

Advance specified step size. default is 1

func (*Progress) AdvanceTo 

func (p *Progress) AdvanceTo(step uint)

AdvanceTo specified number of steps

func (*Progress) Binding 

func (p *Progress) Binding(data any) *Progress

Binding user custom data to instance

func (*Progress) Bound 

func (p *Progress) Bound() any

Bound get bound sub struct instance

func (*Progress) Config 

func (p *Progress) Config(fn func(p *Progress)) *Progress

Config the progress instance

func (*Progress) Destroy 

func (p *Progress) Destroy()

Destroy removes the progress bar from the current line.

This is useful if you wish to write some output while a progress bar is running. Call display() to show the progress bar again.

func (*Progress) Display 

func (p *Progress) Display()

Display outputs the current progress string.

func (*Progress) Finish 

func (p *Progress) Finish(message ...string)

Finish the progress output. if provide finish message, will delete progress bar then print the message.

func (*Progress) FinishedAt 

func (p *Progress) FinishedAt() time.Time

FinishedAt time get

func (*Progress) Handler 

func (p *Progress) Handler(name string) WidgetFunc

Handler get widget handler by widget name

func (*Progress) Percent 

func (p *Progress) Percent() float32

Percent gets the current percent

func (*Progress) Progress 

func (p *Progress) Progress() uint

Progress alias of the Step()

func (*Progress) SetWidget 

func (p *Progress) SetWidget(name string, handler WidgetFunc) *Progress

SetWidget to progress instance

func (*Progress) Start 

func (p *Progress) Start(maxSteps ...int)

Start the progress bar

func (*Progress) StartedAt 

func (p *Progress) StartedAt() time.Time

StartedAt time get

func (*Progress) Step 

func (p *Progress) Step() uint

Step gets the current step position.

func (*Progress) WithMaxSteps 

func (p *Progress) WithMaxSteps(maxSteps ...int) *Progress

WithMaxSteps setting max steps

func (*Progress) WithOptions 

func (p *Progress) WithOptions(fns ...func(p *Progress)) *Progress

WithOptions add more option at once for the progress instance

type Progresser 

type Progresser interface {
	Start(maxSteps ...int)
	Advance(steps ...uint)
	AdvanceTo(step uint)
	Finish(msg ...string)
	Bound() any
}

Progresser progress interface

type SpinnerFactory 

type SpinnerFactory struct {
	// Speed is the running speed
	Speed time.Duration
	// Format setting display format
	Format string
	// Builder build custom spinner text
	Builder BuilderFunc
	// contains filtered or unexported fields
}

SpinnerFactory definition. ref https://github.com/briandowns/spinner

func LoadingSpinner 

func LoadingSpinner(chars []rune, speed time.Duration) *SpinnerFactory

LoadingSpinner instance create

Example 
s := LoadingSpinner(RandomCharsTheme(), 100*time.Millisecond)

s.Start("%s work handling ... ...")
// Run for some time to simulate work
time.Sleep(4 * time.Second)
s.Stop("work handle complete")

Output:

func RoundTripLoading 

func RoundTripLoading(char rune, speed time.Duration, charNumAndBoxWidth ...int) *SpinnerFactory

RoundTripLoading create

func RoundTripSpinner 

func RoundTripSpinner(char rune, speed time.Duration, charNumAndBoxWidth ...int) *SpinnerFactory

RoundTripSpinner instance create

Example 
s := RoundTripSpinner(RandomCharTheme(), 100*time.Millisecond)

s.Start("%s work handling ... ...")
// Run for some time to simulate work
time.Sleep(4 * time.Second)
s.Stop("work handle complete")

Output:

func Spinner 

func Spinner(speed time.Duration) *SpinnerFactory

Spinner instance

func (*SpinnerFactory) Active 

func (s *SpinnerFactory) Active() bool

Active status

func (*SpinnerFactory) Restart 

func (s *SpinnerFactory) Restart()

Restart will stop and start the spinner

func (*SpinnerFactory) Start 

func (s *SpinnerFactory) Start(format ...string)

Start run spinner

func (*SpinnerFactory) Stop 

func (s *SpinnerFactory) Stop(finalMsg ...string)

Stop run spinner

func (*SpinnerFactory) WithBuilder 

func (s *SpinnerFactory) WithBuilder(builder BuilderFunc) *SpinnerFactory

WithBuilder set spinner text builder

type WidgetFunc 

type WidgetFunc func(p *Progress) string

WidgetFunc handler func for progress widget

func BarWidget 

func BarWidget(width int, cs BarChars) WidgetFunc

BarWidget create a progress bar widget.

Output like `[==============>-------------]`

func DynamicTextWidget 

func DynamicTextWidget(messages map[int]string) WidgetFunc

DynamicTextWidget dynamic text message widget for progress bar. for param messages: int is percent, range is 0 - 100. value is message string. Usage please example.

func LoadingWidget 

func LoadingWidget(chars []rune) WidgetFunc

LoadingWidget create loading progress widget

func RoundTripWidget 

func RoundTripWidget(char rune, charNum, boxWidth int) WidgetFunc

RoundTripWidget create a round-trip widget for progress bar.

Output like `[ ==== ]`

Source Files

View all Source files

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.