progress

package module
v0.0.1 Latest Latest
Warning

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

 Go to latest Published: May 30, 2024 License: MIT Imports: 9 Imported by: 0

README

progress

A thread-safe progress bar printing program, which is designed for printing multiple bars simultaneously with a highly efficient. This package is powered by single-line-print

This Golang package is cross-platform which works perfectly on Linux, Windows and MacOS. It provides many very simple apis to render the progress bar with diverse styles that you want, in addition, you can also combine these different styles of progress bars in any format. ssss


Install

go get github.com/loveuer/progress

Basic usage

import "github.com/loveuer/progress"

func main(){
	p := progress.Start()
	bar := progress.NewBar()
	p.AddBar(bar)
	
	for i := 0; i <= 100; i++ {
		bar.Inc()
		time.Sleep(time.Millisecond * 10)
	}
}

Customization

If the example above is not the style you want, you can use method Custom to get progress bar with custom style.

import "github.com/loveuer/progress"

func main() {
	p := progress.Start()
	b := progress.NewBar().Custom(
		progress.BarSetting{
			StartText:       "[",
			EndText:         "]",
			PassedText:      "-",
			FirstPassedText: ">",
			NotPassedText:   "=",
		},
	)
	p.AddBar(b)

	for i := 0; i <= 100; i++ {
		b.Percent(float64(i))
		time.Sleep(time.Millisecond * 30)
	}
}

The BarSetting structure contains rich customization related properties to modify the style of progress bar:

  • LeftSpace, RightSpace(string): the spacings at left and right
  • Total(uint16): the total count of inner characters of the progress bar
  • Hidden(bool): if set to true, the bar will be hidden and not rendered
  • Inline(bool): if set to true, there will not be a line break at the end place of the bar
  • HidePercent(bool): if set to true, there will be a percent value be displayed at the end place of progress bar
  • UseFloat(bool): if set to true, progress bar will have a precision of 0.01%
  • StartText, EndText(bool): text at start and end place
  • PassedText, NotPassedText(string): text passed and not passed
  • FirstPassedText(string): the first passed text
  • PercentColor(uint8): the color of percent value, accept a value like progress.Green, you can see more details at Change the color

Change the color

If you want to change the color of the progress bar, you can use built-in color realted method to generate ANSI color characters:

import "github.com/loveuer/progress"

// Both progress.ColorText(str, progress.Xxx) and progress.XxxText(str) is okay
// Xxx may be Black, Red, Green, Yellow, Blue, Purple, Cyan, White
func main() {
	p := progress.Start()
	b := progress.NewBar().Custom(progress.BarSetting{
		NotPassedText: progress.WhiteText("▇"),
		PassedText:    progress.ColorText("▇", progress.Green),
	})
	p.AddBar(b)

	for i := 0; i <= 100; i++ {
		b.Inc()
		time.Sleep(time.Millisecond * 50)
	}
}

LoadingBar, TextBar

The above examples have demonstrated the method of how to utilize the default progress bar. However this package includes not only default progress bar but also two additional UI formats: TextBar and LoadingBar.

import "github.com/loveuer/progress"

func main(){
	p := progress.Start()

	// TextBar with green text
	tb := progress.NewTextBar(progress.GreenText("start successfully!"))
	p.AddBar(tb)

	// LoadingBar with RedColor
	lb := progress.NewLoadingBar(300, "Loading", "Loading.", "Loading..", "Loading...")
	p.AddBar(lb.SetColor(progress.Red))

	<-time.After(time.Second * 3)
	lb.Hide()

	p.AddBar(progress.NewTextBar("Done, exiting!"))
	p.Stop()
}

The first parameter of NewLoadingBar is the interval of each render, and the remaining parameters are the texts will be printed at each render. You may have noticed that when we creating a LoadingBar, we need write "Loading" three times. While this is fine for short text, if the text is longer, it can cause significant inconvenience. At this point, we can use hyphen(-) to represent the previous text in steps parameter, just like the following(see more parsing rules of custom syntax at FAQ):

lb := progress.NewLoadingBar(300, "Loading", "-.", "-.", "-.")

It should be noted that TextBarSetting and LoadingBarSetting have fewer properties than BarSetting:

  • properties of TextBarSetting:
    • Inline, Hidden (they has the same effect as properties in BarSetting)
  • properties of LoadingBarSetting:
    • Hide, Inline, StartText, EndText (they has the same effect as properties in BarSetting)
    • FixedWidth(bool): if set to true, the LoadingBar will use a fixed width (equal to the length of the longest string)

Combine multiple bars

As mentioned at the beginning, you can combine different styles of bar in any format, the following is an example for combining the bars:

import "github.com/loveuer/progress"

func main() {
	p := progress.Start()

	// create a custom bar
	b1 := progress.NewBar().Custom(progress.BarSetting{
		Total:           50,
		StartText:       "[",
		EndText:         "]",
		PassedText:      "-",
		FirstPassedText: ">",
		NotPassedText:   "=",
	})

	// create a custom inline bar
	b2 := progress.NewBar().Custom(progress.BarSetting{
		UseFloat:        true,
		Inline:          true,
		StartText:       "|",
		EndText:         "|",
		FirstPassedText: ">",
		PassedText:      "=",
		NotPassedText:   " ",
	})

	// create a custom bar with emoji character
	b3 := progress.NewBar().Custom(progress.BarSetting{
		LeftSpace:     10,
		Total:         10,
		StartText:     "|",
		EndText:       "|",
		PassedText:    "⚡",
		NotPassedText: "  ",
	})

	// add bars in progress
	p.AddBar(b2)
	p.AddBar(b3)
	p.AddBar(b1)

	for i := 0; i <= 100; i++ {
		b1.Inc()
		b2.Add(1.4)
		b3.Percent(float64(i))
		time.Sleep(time.Millisecond * 40)
	}
}

FAQ

  1. How could i use actual "-" in NewLoadingBar?
    If you want to use actual "-", use "--" instead. But "---" will be parsed as "-[the previous string]", if you want the last two hyphens be parsed as "-", you could use "()" to change priority, likes following:"-(--)" will be parsed as "[the previous string]-"

  2. How to disable auto-stopping feature?
    You could use progress.StartWithFlag method to initialize progress. Three are five flags can be choosed(the fist three inherit from single-line-print):

    • HideCursor: if set, the cursor will be hidden during printing or writing

    • DisableInput: if set, input will be disabled during printing or writing

    • ResizeReactively: if set, terminal window size will be got before each printing or writing

    • PercentOverflow: if set, the percent value displayed will be able to exceed 100%

    • AutoStop: if set, Progress will automatically stopped when all DefaultBars' percent value >= 100 and all LoadingBars are stopped. it requires PercentOverflow flag not be set.

     p := progress.StartWithFlag(progress.HideCursor | progress.DisableInput | progress.AutoStop)

Documentation

Index

Constants

View Source 
const (
	// HideCursor DisableInput ResizeReactively are flags that inherit from single-line-print
	// see more detail: https://github.com/loveuer/single-line-print
	HideCursor       uint8 = 0x01 // if set, the cursor will be hidden during printing or writing
	DisableInput     uint8 = 0x02 // if set, input will be disabled during printing or writing
	ResizeReactively uint8 = 0x04 // if set, terminal window size will be got before each printing or writing

	PercentOverflow uint8 = 0x10 // if set, the percent value displayed will be able to exceed 100%
	AutoStop        uint8 = 0x08 // if set, progress will stopped when all DefaultBars' percent value >= 100 and all LoadingBars are stopped
)

define flags

View Source 
const (
	Black uint8 = 30 + iota
	Red
	Green
	Yellow
	Blue
	Purple
	Cyan
	White
)

define colors

Variables

This section is empty.

Functions

func BlackText 

func BlackText(s string) string

BlackText generate string that describes black text

func BlueText 

func BlueText(s string) string

BlueText generate string that describes blue text

func ColorText 

func ColorText(s string, color uint8) string

ColorText generates string that describe colored text

func CyanText 

func CyanText(s string) string

CyanText generate string that describes cyan text

func GreenText 

func GreenText(s string) string

GreenText generate string that describes green text

func PurpleText 

func PurpleText(s string) string

PurpleText generate string that describes purple text

func RedText 

func RedText(s string) string

RedText generate string that describes red text

func WhiteText 

func WhiteText(s string) string

WhiteText generate string that describes white text

func YellowText 

func YellowText(s string) string

YellowText generate string that describes yellow text

Types

type Bar 

type Bar interface {
	Hide()
	Show()

	IsHidden() bool
	// contains filtered or unexported methods
}

type BarSetting 

type BarSetting struct {
	PercentColor              uint8  // the color of percent value
	LeftSpace, RightSpace     uint16 // the spacings at left and right
	Total                     uint16 // the total count of inner characters of the progress bar
	Hidden                    bool   // if set to true, the bar will be hidden and not rendered
	Inline                    bool   // if set to true, there will not be a line break at the end place of the bar
	HidePercent               bool   // if set to true, there will be a percent value be displayed at the end place of progress bar
	UseFloat                  bool   // if set to true, progress bar will have a precision of 0.01%
	StartText, EndText        string // text at start and end place
	PassedText, NotPassedText string // text passed and not passed
	FirstPassedText           string // the first passed text
}

BarSetting describes the setting of Bar

type Conf 

type Conf struct {
	Debug    bool // if set to true, the percent value displayed will be able to exceed 100%
	AutoStop bool // if set to true, this Progress will be set as a stopped state when all Bars' N-property >= 100. Need: Debug=false
}

Conf includes all customizable configurations

type DefaultBar 

type DefaultBar struct {
	N       float64
	Setting BarSetting
	Message string
	// contains filtered or unexported fields
}

func NewBar 

func NewBar() *DefaultBar

NewBar returns an instance pointer of Bar

func (*DefaultBar) Add 

func (b *DefaultBar) Add(n float64, messages ...string) error

Add can add specified value to Bar.N and then render the progress bar

func (*DefaultBar) Custom 

func (b *DefaultBar) Custom(setting BarSetting) *DefaultBar

Custom changes attributes and display form of Bar

func (*DefaultBar) Hide 

func (b *DefaultBar) Hide()

func (*DefaultBar) Inc 

func (b *DefaultBar) Inc(messages ...string) error

Inc will increase Bar.N by 1 and then render the progress bar

func (*DefaultBar) IsHidden 

func (b *DefaultBar) IsHidden() bool

func (*DefaultBar) Percent 

func (b *DefaultBar) Percent(n float64, messages ...string) (err error)

Percent sets the percent of Bar

func (*DefaultBar) Show 

func (b *DefaultBar) Show()

type LoadingBar 

type LoadingBar struct {
	Setting LoadingBarSetting
	// contains filtered or unexported fields
}

func NewLoadingBar 

func NewLoadingBar(milli time.Duration, steps ...string) *LoadingBar

NewLoadingBar returns an instance pointer of a loading bar

func (*LoadingBar) Custom 

func (b *LoadingBar) Custom(setting LoadingBarSetting) *LoadingBar

Custom changes the setting of LoadingBar

func (*LoadingBar) Hide 

func (b *LoadingBar) Hide()

func (*LoadingBar) IsHidden 

func (b *LoadingBar) IsHidden() bool

func (*LoadingBar) SetColor 

func (b *LoadingBar) SetColor(color uint8) *LoadingBar

SetColor will change the color of all strings in LoadingBar.loadingText

func (*LoadingBar) Show 

func (b *LoadingBar) Show()

func (*LoadingBar) Stop 

func (b *LoadingBar) Stop() error

Stop clean the timer of LoadingBar

type LoadingBarSetting 

type LoadingBarSetting struct {
	Hidden             bool
	Inline             bool
	StartText, EndText string // text at start and end place
	FixedWidth         bool   // if set to true, the LoadingBar will use a fixed width (equal to the length of the longest string)
}

LoadingBarSetting describes the setting of LoadingBar

type Progress 

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

func Start 

func Start() *Progress

Start returns an instance pointer of Progress

func StartWithFlag 

func StartWithFlag(flag uint8) *Progress

StartWithFlag instantiate an instance of Progress with flags and returns the instance

func (*Progress) AddBar 

func (p *Progress) AddBar(b Bar)

AddBar adds a Bar into Progress

func (*Progress) Stop 

func (p *Progress) Stop() error

Stop will unregister Progress and close renderSig channel

type TextBar 

type TextBar struct {
	Setting TextBarSetting
	// contains filtered or unexported fields
}

func NewTextBar 

func NewTextBar(content string) *TextBar

NewTextBar returns an instance pointer of a static content bar

func (*TextBar) Custom 

func (b *TextBar) Custom(setting TextBarSetting) *TextBar

Custom changes the setting of TextBar

func (*TextBar) Hide 

func (b *TextBar) Hide()

func (*TextBar) IsHidden 

func (b *TextBar) IsHidden() bool

func (*TextBar) Show 

func (b *TextBar) Show()

type TextBarSetting 

type TextBarSetting struct {
	Inline bool
	Hidden bool
}

TextBarSetting describes the setting of TextBar

Source Files

View all Source files

Directories

Path Synopsis
examples
color command
combine command
loading 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.