progress

package
v6.0.5 Latest Latest
Warning

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

 Go to latest Published: Oct 1, 2020 License: MIT Imports: 10 Imported by: 69

README

Progress

GoDoc

Track the Progress of one or more Tasks (like downloading multiple files in parallel).

  • Track one or more Tasks at the same time
  • Dynamically add one or more Task Trackers while Render() is in progress
  • Choose to have the Writer auto-stop the Render when no more Trackers are in queue, or manually stop using Stop()
  • Redirect output to an io.Writer object (like os.StdOut)
  • Completely customizable styles
    • Many ready-to-use styles: style.go
    • Colorize various parts of the Tracker using StyleColors
    • Customize how Trackers get rendered using StyleOptions

A demonstration of all the capabilities can be found here: ../cmd/demo-progress

Sample Progress Tracking

TODO

  • Optimize CPU and Memory Usage

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// DefaultLengthTracker defines a sane value for a Tracker's length.
	DefaultLengthTracker = 20

	// DefaultUpdateFrequency defines a sane value for the frequency with which
	// all the Tracker's get updated on the screen.
	DefaultUpdateFrequency = time.Millisecond * 250
)
View Source 
var (
	// StyleDefault uses ASCII text to render the Trackers.
	StyleDefault = Style{
		Name:    "StyleDefault",
		Chars:   StyleCharsDefault,
		Colors:  StyleColorsDefault,
		Options: StyleOptionsDefault,
	}

	// StyleBlocks uses UNICODE Block Drawing characters to render the Trackers.
	StyleBlocks = Style{
		Name:    "StyleBlocks",
		Chars:   StyleCharsBlocks,
		Colors:  StyleColorsDefault,
		Options: StyleOptionsDefault,
	}

	// StyleCircle uses UNICODE Circle runes to render the Trackers.
	StyleCircle = Style{
		Name:    "StyleCircle",
		Chars:   StyleCharsCircle,
		Colors:  StyleColorsDefault,
		Options: StyleOptionsDefault,
	}

	// StyleRhombus uses UNICODE Rhombus runes to render the Trackers.
	StyleRhombus = Style{
		Name:    "StyleRhombus",
		Chars:   StyleCharsRhombus,
		Colors:  StyleColorsDefault,
		Options: StyleOptionsDefault,
	}
)
View Source 
var (
	// StyleCharsDefault uses simple ASCII characters.
	StyleCharsDefault = StyleChars{
		BoxLeft:    "[",
		BoxRight:   "]",
		Finished:   "#",
		Finished25: ".",
		Finished50: ".",
		Finished75: ".",
		Unfinished: ".",
	}

	// StyleCharsBlocks uses UNICODE Block Drawing characters.
	StyleCharsBlocks = StyleChars{
		BoxLeft:    "║",
		BoxRight:   "║",
		Finished:   "█",
		Finished25: "░",
		Finished50: "▒",
		Finished75: "▓",
		Unfinished: "░",
	}

	// StyleCharsCircle uses UNICODE Circle characters.
	StyleCharsCircle = StyleChars{
		BoxLeft:    "(",
		BoxRight:   ")",
		Finished:   "●",
		Finished25: "○",
		Finished50: "○",
		Finished75: "○",
		Unfinished: "◌",
	}

	// StyleCharsRhombus uses UNICODE Rhombus characters.
	StyleCharsRhombus = StyleChars{
		BoxLeft:    "<",
		BoxRight:   ">",
		Finished:   "◆",
		Finished25: "◈",
		Finished50: "◈",
		Finished75: "◈",
		Unfinished: "◇",
	}
)
View Source 
var (
	// StyleColorsDefault defines sane color choices - None.
	StyleColorsDefault = StyleColors{}

	// StyleColorsExample defines a few choice color options. Use this is just as
	// an example to customize the Tracker/text colors.
	StyleColorsExample = StyleColors{
		Message: text.Colors{text.FgWhite, text.BgBlack},
		Percent: text.Colors{text.FgHiRed, text.BgBlack},
		Stats:   text.Colors{text.FgHiBlack, text.BgBlack},
		Time:    text.Colors{text.FgGreen, text.BgBlack},
		Tracker: text.Colors{text.FgYellow, text.BgBlack},
		Value:   text.Colors{text.FgCyan, text.BgBlack},
	}
)
View Source 
var (
	// UnitsDefault doesn't define any units. The value will be treated as any
	// other number.
	UnitsDefault = Units{
		Notation:  "",
		Formatter: FormatNumber,
	}

	// UnitsBytes defines the value as a storage unit. Values will be converted
	// and printed in one of these forms: B, KB, MB, GB, TB, PB
	UnitsBytes = Units{
		Notation:  "",
		Formatter: FormatBytes,
	}

	// UnitsCurrencyDollar defines the value as a Dollar amount. Values will be
	// converted and printed in one of these forms: $x.yz, $x.yzK, $x.yzM,
	// $x.yzB, $x.yzT
	UnitsCurrencyDollar = Units{
		Notation:  "$",
		Formatter: FormatNumber,
	}

	// UnitsCurrencyEuro defines the value as a Euro amount. Values will be
	// converted and printed in one of these forms: ₠x.yz, ₠x.yzK, ₠x.yzM,
	// ₠x.yzB, ₠x.yzT
	UnitsCurrencyEuro = Units{
		Notation:  "₠",
		Formatter: FormatNumber,
	}

	// UnitsCurrencyPound defines the value as a Pound amount. Values will be
	// converted and printed in one of these forms: £x.yz, £x.yzK, £x.yzM,
	// £x.yzB, £x.yzT
	UnitsCurrencyPound = Units{
		Notation:  "£",
		Formatter: FormatNumber,
	}
)
View Source 
var (
	// StyleOptionsDefault defines sane defaults for the Options. Use this as an
	// example to customize the Tracker rendering.
	StyleOptionsDefault = StyleOptions{
		DoneString:              "done!",
		PercentFormat:           "%5.2f%%",
		Separator:               " ... ",
		SnipIndicator:           "~",
		TimeDonePrecision:       time.Millisecond,
		TimeInProgressPrecision: time.Microsecond,
		TimeOverallPrecision:    time.Second,
	}
)

Functions

func FormatBytes 

func FormatBytes(value int64) string

FormatBytes formats the given value as a "Byte".

func FormatNumber 

func FormatNumber(value int64) string

FormatNumber formats the given value as a "regular number".

Types

type Position 

type Position int

Position defines the position of the Tracker with respect to the Tracker's Message. 

const (
	// PositionLeft will make the Tracker be displayed first before the Message.
	PositionLeft Position = iota

	// PositionRight will make the Tracker be displayed after the Message.
	PositionRight
)

type Progress 

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

Progress helps track progress for one or more tasks.

func (*Progress) AppendTracker 

func (p *Progress) AppendTracker(t *Tracker)

AppendTracker appends a single Tracker for tracking. The Tracker gets added to a queue, which gets picked up by the Render logic in the next rendering cycle.

func (*Progress) AppendTrackers 

func (p *Progress) AppendTrackers(trackers []*Tracker)

AppendTrackers appends one or more Trackers for tracking.

func (*Progress) IsRenderInProgress 

func (p *Progress) IsRenderInProgress() bool

IsRenderInProgress returns true if a call to Render() was made, and is still in progress and has not ended yet.

func (*Progress) Length 

func (p *Progress) Length() int

Length returns the number of Trackers tracked overall.

func (*Progress) LengthActive 

func (p *Progress) LengthActive() int

LengthActive returns the number of Trackers actively tracked (not done yet).

func (*Progress) LengthDone 

func (p *Progress) LengthDone() int

LengthDone returns the number of Trackers that are done tracking.

func (*Progress) LengthInQueue 

func (p *Progress) LengthInQueue() int

LengthInQueue returns the number of Trackers in queue to be actively tracked (not tracking yet).

func (*Progress) Render 

func (p *Progress) Render()

Render renders the Progress tracker and handles all existing trackers and those that are added dynamically while render is in progress.

func (*Progress) SetAutoStop 

func (p *Progress) SetAutoStop(autoStop bool)

SetAutoStop toggles the auto-stop functionality. Auto-stop set to true would mean that the Render() function will automatically stop once all currently active Trackers reach their final states. When set to false, the client code will have to call Progress.Stop() to stop the Render() logic. Default: false.

func (*Progress) SetMessageWidth 

func (p *Progress) SetMessageWidth(width int)

SetMessageWidth sets the (printed) length of the tracker message. Any message longer the specified width will be snipped abruptly. Any message shorter than the specified width will be padded with spaces.

func (*Progress) SetNumTrackersExpected 

func (p *Progress) SetNumTrackersExpected(numTrackers int)

SetNumTrackersExpected sets the expected number of trackers to be tracked. This helps calculate the overall progress with better accuracy.

func (*Progress) SetOutputWriter 

func (p *Progress) SetOutputWriter(writer io.Writer)

SetOutputWriter redirects the output of Render to an io.writer object like os.Stdout or os.Stderr or a file. Warning: redirecting the output to a file may not work well as the Render() logic moves the cursor around a lot.

func (*Progress) SetSortBy 

func (p *Progress) SetSortBy(sortBy SortBy)

SetSortBy defines the sorting mechanism to use to sort the Active Trackers before rendering the. Default: no-sorting == sort-by-insertion-order.

func (*Progress) SetStyle 

func (p *Progress) SetStyle(style Style)

SetStyle sets the Style to use for rendering.

func (*Progress) SetTrackerLength 

func (p *Progress) SetTrackerLength(length int)

SetTrackerLength sets the text-length of all the Trackers.

func (*Progress) SetTrackerPosition 

func (p *Progress) SetTrackerPosition(position Position)

SetTrackerPosition sets the position of the tracker with respect to the Tracker message text.

func (*Progress) SetUpdateFrequency 

func (p *Progress) SetUpdateFrequency(frequency time.Duration)

SetUpdateFrequency sets the update frequency while rendering the trackers. the lower the value, the more number of times the Trackers get refreshed. A sane value would be 250ms.

func (*Progress) ShowOverallTracker 

func (p *Progress) ShowOverallTracker(show bool)

ShowOverallTracker toggles showing the Overall progress tracker.

func (*Progress) ShowPercentage 

func (p *Progress) ShowPercentage(show bool)

ShowPercentage toggles showing the Percent complete for each Tracker.

func (*Progress) ShowTime 

func (p *Progress) ShowTime(show bool)

ShowTime toggles showing the Time taken by each Tracker.

func (*Progress) ShowTracker 

func (p *Progress) ShowTracker(show bool)

ShowTracker toggles showing the Tracker (the progress bar).

func (*Progress) ShowValue 

func (p *Progress) ShowValue(show bool)

ShowValue toggles showing the actual Value of the Tracker.

func (*Progress) Stop 

func (p *Progress) Stop()

Stop stops the Render() logic that is in progress.

func (*Progress) Style 

func (p *Progress) Style() *Style

Style returns the current Style.

type SortBy 

type SortBy int

SortBy helps sort a list of Trackers by various means. 

const (
	// SortByNone doesn't do any sorting == sort by insertion order.
	SortByNone SortBy = iota

	// SortByMessage sorts by the Message alphabetically in ascending order.
	SortByMessage

	// SortByMessageDsc sorts by the Message alphabetically in descending order.
	SortByMessageDsc

	// SortByPercent sorts by the Percentage complete in ascending order.
	SortByPercent

	// SortByPercentDsc sorts by the Percentage complete in descending order.
	SortByPercentDsc

	// SortByValue sorts by the Value in ascending order.
	SortByValue

	// SortByValueDsc sorts by the Value in descending order.
	SortByValueDsc
)

func (SortBy) Sort 

func (sb SortBy) Sort(trackers []*Tracker)

Sort applies the sorting method defined by SortBy.

type Style 

type Style struct {
	Name    string       // name of the Style
	Chars   StyleChars   // characters to use on the progress bar
	Colors  StyleColors  // colors to use on the progress bar
	Options StyleOptions // misc. options for the progress bar
}

Style declares how to render the Progress/Trackers.

type StyleChars 

type StyleChars struct {
	BoxLeft    string // left-border
	BoxRight   string // right-border
	Finished   string // finished block
	Finished25 string // 25% finished block
	Finished50 string // 50% finished block
	Finished75 string // 75% finished block
	Unfinished string // 0% finished block
}

StyleChars defines the characters/strings to use for rendering the Tracker.

type StyleColors 

type StyleColors struct {
	Message text.Colors // message text colors
	Percent text.Colors // percentage text colors
	Stats   text.Colors // stats text (time, value) colors
	Time    text.Colors // time text colors (overrides Stats)
	Tracker text.Colors // tracker text colors
	Value   text.Colors // value text colors (overrides Stats)
}

StyleColors defines what colors to use for various parts of the Progress and Tracker texts.

type StyleOptions 

type StyleOptions struct {
	DoneString              string        // "done!" string
	Separator               string        // text between message and tracker
	SnipIndicator           string        // text denoting message snipping
	PercentFormat           string        // formatting to use for percentage
	TimeDonePrecision       time.Duration // precision for time when done
	TimeInProgressPrecision time.Duration // precision for time when in progress
	TimeOverallPrecision    time.Duration // precision for overall time
}

StyleOptions defines misc. options to control how the Tracker or its parts gets rendered.

type Tracker 

type Tracker struct {
	// Message should contain a short description of the "task"
	Message string
	// ExpectedDuration tells how long this task is expected to take; and will
	// be used in calculation of the ETA value
	ExpectedDuration time.Duration
	// Total should be set to the (expected) Total/Final value to be reached
	Total int64
	// Units defines the type of the "value" being tracked
	Units Units
	// contains filtered or unexported fields
}

Tracker helps track the progress of a single task. The way to use it is to instantiate a Tracker with a valid Message, a valid (expected) Total, and Units values. This should then be fed to the Progress Writer with the Writer.AppendTracker() method. When the task that is being done has progress, increment the value using the Tracker.Increment(value) method.

func (*Tracker) ETA 

func (t *Tracker) ETA() time.Duration

ETA returns the expected time of "arrival" or completion of this tracker. It is an estimate and is not guaranteed.

func (*Tracker) Increment 

func (t *Tracker) Increment(value int64)

Increment updates the current value of the task being tracked.

func (*Tracker) IsDone 

func (t *Tracker) IsDone() bool

IsDone returns true if the tracker is done (value has reached the expected Total set during initialization).

func (*Tracker) MarkAsDone 

func (t *Tracker) MarkAsDone()

MarkAsDone forces completion of the tracker by updating the current value as the expected Total value.

func (*Tracker) PercentDone 

func (t *Tracker) PercentDone() float64

PercentDone returns the currently completed percentage value.

func (*Tracker) Reset 

func (t *Tracker) Reset()

Reset resets the tracker to its initial state.

func (*Tracker) SetValue 

func (t *Tracker) SetValue(value int64)

SetValue sets the value of the tracker and re-calculates if the tracker is "done".

type Units 

type Units struct {
	Notation  string
	Formatter func(value int64) string
}

Units defines the "type" of the value being tracked by the Tracker.

func (Units) Sprint 

func (tu Units) Sprint(value int64) string

Sprint prints the value as defined by the Units.

type Writer 

type Writer interface {
	AppendTracker(tracker *Tracker)
	AppendTrackers(trackers []*Tracker)
	IsRenderInProgress() bool
	Length() int
	LengthActive() int
	LengthDone() int
	LengthInQueue() int
	SetAutoStop(autoStop bool)
	SetMessageWidth(width int)
	SetNumTrackersExpected(numTrackers int)
	SetOutputWriter(output io.Writer)
	SetSortBy(sortBy SortBy)
	SetStyle(style Style)
	SetTrackerLength(length int)
	SetTrackerPosition(position Position)
	ShowOverallTracker(show bool)
	ShowPercentage(show bool)
	ShowTime(show bool)
	ShowTracker(show bool)
	ShowValue(show bool)
	SetUpdateFrequency(frequency time.Duration)
	Stop()
	Style() *Style
	Render()
}

Writer declares the interfaces that can be used to setup and render a Progress tracker with one or more trackers.

func NewWriter 

func NewWriter() Writer

NewWriter initializes and returns a Writer.

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.