decor

package
v8.9.3 Latest Latest
Warning

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

 Go to latest Published: Feb 25, 2025 License: Unlicense Imports: 10 Imported by: 137

Documentation

Overview

Package decor provides common decorators for "github.com/vbauerster/mpb/v8" module.

Some decorators returned by this package might have a closure state. It is ok to use decorators concurrently, unless you share the same decorator among multiple *mpb.Bar instances. To avoid data races, create new decorator per *mpb.Bar instance.

Don't: 

p := mpb.New()
name := decor.Name("bar")
p.AddBar(100, mpb.AppendDecorators(name))
p.AddBar(100, mpb.AppendDecorators(name))

Do: 

p := mpb.New()
p.AddBar(100, mpb.AppendDecorators(decor.Name("bar1")))
p.AddBar(100, mpb.AppendDecorators(decor.Name("bar2")))

Index

Constants

View Source 
const (
	// DindentRight sets indentation from right to left.
	//
	//	|foo   |b     | DindentRight is set
	//	|   foo|     b| DindentRight is not set
	DindentRight = 1 << iota

	// DextraSpace bit adds extra indentation space.
	DextraSpace

	// DSyncWidth bit enables same column width synchronization.
	// Effective with multiple bars only.
	DSyncWidth

	// DSyncWidthR is shortcut for DSyncWidth|DindentRight
	DSyncWidthR = DSyncWidth | DindentRight

	// DSyncSpace is shortcut for DSyncWidth|DextraSpace
	DSyncSpace = DSyncWidth | DextraSpace

	// DSyncSpaceR is shortcut for DSyncWidth|DextraSpace|DindentRight
	DSyncSpaceR = DSyncWidth | DextraSpace | DindentRight
)

Variables

View Source 
var (
	WCSyncWidth  = WC{C: DSyncWidth}
	WCSyncWidthR = WC{C: DSyncWidthR}
	WCSyncSpace  = WC{C: DSyncSpace}
	WCSyncSpaceR = WC{C: DSyncSpaceR}
)

Global convenience instances of WC with sync width bit set. To be used with multiple bars only, i.e. not effective for single bar usage.

Functions

func FmtAsSpeed 

func FmtAsSpeed(input fmt.Formatter) fmt.Formatter

FmtAsSpeed adds "/s" to the end of the input formatter. To be used with SizeB1000 or SizeB1024 types, for example: 

fmt.Printf("%.1f", FmtAsSpeed(SizeB1024(2048)))

func NewMedian 

func NewMedian() ewma.MovingAverage

NewMedian is fixed last 3 samples median MovingAverage.

func NewThreadSafeMovingAverage 

func NewThreadSafeMovingAverage(average ewma.MovingAverage) ewma.MovingAverage

NewThreadSafeMovingAverage converts provided ewma.MovingAverage into thread safe ewma.MovingAverage.

Types

type AverageDecorator 

type AverageDecorator interface {
	AverageAdjust(time.Time)
}

AverageDecorator interface. Average decorators should implement this interface to provide start time adjustment facility, for resume-able tasks.

type DecorFunc 

type DecorFunc func(Statistics) string

DecorFunc func type. To be used with `func Any(DecorFunc, ...WC) Decorator`.

type Decorator 

type Decorator interface {
	Synchronizer
	Formatter
	Decor(Statistics) (str string, viewWidth int)
}

Decorator interface. Most of the time there is no need to implement this interface manually, as decor package already provides a wide range of decorators which implement this interface. If however built-in decorators don't meet your needs, you're free to implement your own one by implementing this particular interface. The easy way to go is to convert a `DecorFunc` into a `Decorator` interface by using provided `func Any(DecorFunc, ...WC) Decorator`.

func Any 

func Any(fn DecorFunc, wcc ...WC) Decorator

Any decorator. Converts DecorFunc into Decorator. 

`fn` DecorFunc callback
`wcc` optional WC config

func AverageETA 

func AverageETA(style TimeStyle, wcc ...WC) Decorator

AverageETA decorator. It's wrapper of NewAverageETA. 

`style` one of [ET_STYLE_GO|ET_STYLE_HHMMSS|ET_STYLE_HHMM|ET_STYLE_MMSS]

`wcc` optional WC config

func AverageSpeed 

func AverageSpeed(unit interface{}, format string, wcc ...WC) Decorator

AverageSpeed decorator with dynamic unit measure adjustment. It's a wrapper of NewAverageSpeed.

func Conditional 

func Conditional(cond bool, a, b Decorator) Decorator

Conditional returns decorator `a` if condition is true, otherwise decorator `b`. 

`cond` bool

`a` Decorator

`b` Decorator

func Counters 

func Counters(unit interface{}, pairFmt string, wcc ...WC) Decorator

Counters decorator with dynamic unit measure adjustment. 

`unit` one of [0|SizeB1024(0)|SizeB1000(0)]

`pairFmt` printf compatible verbs for current and total

`wcc` optional WC config

pairFmt example if unit=SizeB1000(0): 

pairFmt="%d / %d"       output: "1MB / 12MB"
pairFmt="% d / % d"     output: "1 MB / 12 MB"
pairFmt="%.1f / %.1f"   output: "1.0MB / 12.0MB"
pairFmt="% .1f / % .1f" output: "1.0 MB / 12.0 MB"
pairFmt="%f / %f"       output: "1.000000MB / 12.000000MB"
pairFmt="% f / % f"     output: "1.000000 MB / 12.000000 MB"

func CountersKibiByte 

func CountersKibiByte(pairFmt string, wcc ...WC) Decorator

CountersKibiByte is a wrapper around Counters with predefined unit as SizeB1024(0).

func CountersKiloByte 

func CountersKiloByte(pairFmt string, wcc ...WC) Decorator

CountersKiloByte is a wrapper around Counters with predefined unit as SizeB1000(0).

func CountersNoUnit 

func CountersNoUnit(pairFmt string, wcc ...WC) Decorator

CountersNoUnit is a wrapper around Counters with no unit param.

func Current 

func Current(unit interface{}, format string, wcc ...WC) Decorator

Current decorator with dynamic unit measure adjustment. 

`unit` one of [0|SizeB1024(0)|SizeB1000(0)]

`format` printf compatible verb for Current

`wcc` optional WC config

format example if unit=SizeB1024(0): 

format="%d"    output: "12MiB"
format="% d"   output: "12 MiB"
format="%.1f"  output: "12.0MiB"
format="% .1f" output: "12.0 MiB"
format="%f"    output: "12.000000MiB"
format="% f"   output: "12.000000 MiB"

func CurrentKibiByte 

func CurrentKibiByte(format string, wcc ...WC) Decorator

CurrentKibiByte is a wrapper around Current with predefined unit as SizeB1024(0).

func CurrentKiloByte 

func CurrentKiloByte(format string, wcc ...WC) Decorator

CurrentKiloByte is a wrapper around Current with predefined unit as SizeB1000(0).

func CurrentNoUnit 

func CurrentNoUnit(format string, wcc ...WC) Decorator

CurrentNoUnit is a wrapper around Current with no unit param.

func Elapsed 

func Elapsed(style TimeStyle, wcc ...WC) Decorator

Elapsed decorator. It's wrapper of NewElapsed. 

`style` one of [ET_STYLE_GO|ET_STYLE_HHMMSS|ET_STYLE_HHMM|ET_STYLE_MMSS]

`wcc` optional WC config

func EwmaETA 

func EwmaETA(style TimeStyle, age float64, wcc ...WC) Decorator

EwmaETA exponential-weighted-moving-average based ETA decorator. For this decorator to work correctly you have to measure each iteration's duration and pass it to one of the (*Bar).EwmaIncr... family methods.

func EwmaNormalizedETA added in v8.8.0 

func EwmaNormalizedETA(style TimeStyle, age float64, normalizer TimeNormalizer, wcc ...WC) Decorator

EwmaNormalizedETA same as EwmaETA but with TimeNormalizer option.

func EwmaSpeed 

func EwmaSpeed(unit interface{}, format string, age float64, wcc ...WC) Decorator

EwmaSpeed exponential-weighted-moving-average based speed decorator. For this decorator to work correctly you have to measure each iteration's duration and pass it to one of the (*Bar).EwmaIncr... family methods.

func InvertedCurrent 

func InvertedCurrent(unit interface{}, format string, wcc ...WC) Decorator

InvertedCurrent decorator with dynamic unit measure adjustment. 

`unit` one of [0|SizeB1024(0)|SizeB1000(0)]

`format` printf compatible verb for InvertedCurrent

`wcc` optional WC config

format example if unit=SizeB1024(0): 

format="%d"    output: "12MiB"
format="% d"   output: "12 MiB"
format="%.1f"  output: "12.0MiB"
format="% .1f" output: "12.0 MiB"
format="%f"    output: "12.000000MiB"
format="% f"   output: "12.000000 MiB"

func InvertedCurrentKibiByte 

func InvertedCurrentKibiByte(format string, wcc ...WC) Decorator

InvertedCurrentKibiByte is a wrapper around InvertedCurrent with predefined unit as SizeB1024(0).

func InvertedCurrentKiloByte 

func InvertedCurrentKiloByte(format string, wcc ...WC) Decorator

InvertedCurrentKiloByte is a wrapper around InvertedCurrent with predefined unit as SizeB1000(0).

func InvertedCurrentNoUnit 

func InvertedCurrentNoUnit(format string, wcc ...WC) Decorator

InvertedCurrentNoUnit is a wrapper around InvertedCurrent with no unit param.

func Meta added in v8.5.0 

func Meta(decorator Decorator, fn func(string) string) Decorator

Meta wrap decorator. Provided fn is supposed to wrap output of given decorator with meta information like ANSI escape codes for example. Primary usage intention is to set SGR display attributes. 

`decorator` Decorator to wrap
`fn` func to apply meta information

func MovingAverageETA 

func MovingAverageETA(style TimeStyle, average ewma.MovingAverage, normalizer TimeNormalizer, wcc ...WC) Decorator

MovingAverageETA decorator relies on MovingAverage implementation to calculate its average. 

`style` one of [ET_STYLE_GO|ET_STYLE_HHMMSS|ET_STYLE_HHMM|ET_STYLE_MMSS]

`average` implementation of MovingAverage interface

`normalizer` available implementations are [FixedIntervalTimeNormalizer|MaxTolerateTimeNormalizer]

`wcc` optional WC config

func MovingAverageSpeed 

func MovingAverageSpeed(unit interface{}, format string, average ewma.MovingAverage, wcc ...WC) Decorator

MovingAverageSpeed decorator relies on MovingAverage implementation to calculate its average. 

`unit` one of [0|SizeB1024(0)|SizeB1000(0)]

`format` printf compatible verb for value, like "%f" or "%d"

`average` MovingAverage implementation

`wcc` optional WC config

format examples: 

unit=SizeB1024(0), format="%.1f"  output: "1.0MiB/s"
unit=SizeB1024(0), format="% .1f" output: "1.0 MiB/s"
unit=SizeB1000(0), format="%.1f"  output: "1.0MB/s"
unit=SizeB1000(0), format="% .1f" output: "1.0 MB/s"

func Name 

func Name(str string, wcc ...WC) Decorator

Name decorator displays text that is set once and can't be changed during decorator's lifetime. 

`str` string to display

`wcc` optional WC config

func NewAverageETA 

func NewAverageETA(style TimeStyle, start time.Time, normalizer TimeNormalizer, wcc ...WC) Decorator

NewAverageETA decorator with user provided start time. 

`style` one of [ET_STYLE_GO|ET_STYLE_HHMMSS|ET_STYLE_HHMM|ET_STYLE_MMSS]

`start` start time

`normalizer` available implementations are [FixedIntervalTimeNormalizer|MaxTolerateTimeNormalizer]

`wcc` optional WC config

func NewAverageSpeed 

func NewAverageSpeed(unit interface{}, format string, start time.Time, wcc ...WC) Decorator

NewAverageSpeed decorator with dynamic unit measure adjustment and user provided start time. 

`unit` one of [0|SizeB1024(0)|SizeB1000(0)]

`format` printf compatible verb for value, like "%f" or "%d"

`start` start time

`wcc` optional WC config

format examples: 

unit=SizeB1024(0), format="%.1f"  output: "1.0MiB/s"
unit=SizeB1024(0), format="% .1f" output: "1.0 MiB/s"
unit=SizeB1000(0), format="%.1f"  output: "1.0MB/s"
unit=SizeB1000(0), format="% .1f" output: "1.0 MB/s"

func NewElapsed 

func NewElapsed(style TimeStyle, start time.Time, wcc ...WC) Decorator

NewElapsed returns elapsed time decorator. 

`style` one of [ET_STYLE_GO|ET_STYLE_HHMMSS|ET_STYLE_HHMM|ET_STYLE_MMSS]

`start` start time

`wcc` optional WC config

func NewPercentage 

func NewPercentage(format string, wcc ...WC) Decorator

NewPercentage percentage decorator with custom format string. 

`format` printf compatible verb

`wcc` optional WC config

format examples: 

format="%d"    output: "1%"
format="% d"   output: "1 %"
format="%.1f"  output: "1.0%"
format="% .1f" output: "1.0 %"
format="%f"    output: "1.000000%"
format="% f"   output: "1.000000 %"

func OnAbort 

func OnAbort(decorator Decorator, message string) Decorator

OnAbort wrap decorator. Displays provided message on abort event. Has no effect if bar.Abort(true) is called. 

`decorator` Decorator to wrap
`message` message to display

func OnAbortMeta added in v8.5.0 

func OnAbortMeta(decorator Decorator, fn func(string) string) Decorator

OnAbortMeta wrap decorator. Provided fn is supposed to wrap output of given decorator with meta information like ANSI escape codes for example. Primary usage intention is to set SGR display attributes. 

`decorator` Decorator to wrap
`fn` func to apply meta information

func OnComplete 

func OnComplete(decorator Decorator, message string) Decorator

OnComplete wrap decorator. Displays provided message on complete event. 

`decorator` Decorator to wrap
`message` message to display

func OnCompleteMeta added in v8.5.0 

func OnCompleteMeta(decorator Decorator, fn func(string) string) Decorator

OnCompleteMeta wrap decorator. Provided fn is supposed to wrap output of given decorator with meta information like ANSI escape codes for example. Primary usage intention is to set SGR display attributes. 

`decorator` Decorator to wrap
`fn` func to apply meta information

func OnCompleteMetaOrOnAbortMeta added in v8.6.1 

func OnCompleteMetaOrOnAbortMeta(decorator Decorator, fn func(string) string) Decorator

OnCompleteMetaOrOnAbortMeta wrap decorator. Provided fn is supposed to wrap output of given decorator with meta information like ANSI escape codes for example. Primary usage intention is to set SGR display attributes. 

`decorator` Decorator to wrap
`fn` func to apply meta information

func OnCompleteOrOnAbort added in v8.6.0 

func OnCompleteOrOnAbort(decorator Decorator, message string) Decorator

OnCompleteOrOnAbort wrap decorator. Displays provided message on complete or on abort event. 

`decorator` Decorator to wrap
`message` message to display

func OnCondition 

func OnCondition(decorator Decorator, cond bool) Decorator

OnCondition applies decorator only if a condition is true. 

`decorator` Decorator

`cond` bool

func OnPredicate 

func OnPredicate(decorator Decorator, predicate func() bool) Decorator

OnPredicate applies decorator only if a predicate evaluates to true. 

`decorator` Decorator

`predicate` func() bool

func Percentage 

func Percentage(wcc ...WC) Decorator

Percentage returns percentage decorator. It's a wrapper of NewPercentage.

func Predicative 

func Predicative(predicate func() bool, a, b Decorator) Decorator

Predicative returns decorator `a` if predicate evaluates to true, otherwise decorator `b`. 

`predicate` func() bool

`a` Decorator

`b` Decorator

func Spinner 

func Spinner(frames []string, wcc ...WC) Decorator

Spinner returns spinner decorator. 

`frames` spinner frames, if nil or len==0, default is used

`wcc` optional WC config

func Total 

func Total(unit interface{}, format string, wcc ...WC) Decorator

Total decorator with dynamic unit measure adjustment. 

`unit` one of [0|SizeB1024(0)|SizeB1000(0)]

`format` printf compatible verb for Total

`wcc` optional WC config

format example if unit=SizeB1024(0): 

format="%d"    output: "12MiB"
format="% d"   output: "12 MiB"
format="%.1f"  output: "12.0MiB"
format="% .1f" output: "12.0 MiB"
format="%f"    output: "12.000000MiB"
format="% f"   output: "12.000000 MiB"

func TotalKibiByte 

func TotalKibiByte(format string, wcc ...WC) Decorator

TotalKibiByte is a wrapper around Total with predefined unit as SizeB1024(0).

func TotalKiloByte 

func TotalKiloByte(format string, wcc ...WC) Decorator

TotalKiloByte is a wrapper around Total with predefined unit as SizeB1000(0).

func TotalNoUnit 

func TotalNoUnit(format string, wcc ...WC) Decorator

TotalNoUnit is a wrapper around Total with no unit param.

type EwmaDecorator 

type EwmaDecorator interface {
	EwmaUpdate(int64, time.Duration)
}

EwmaDecorator interface. EWMA based decorators should implement this one.

type Formatter added in v8.5.0 

type Formatter interface {
	Format(string) (_ string, width int)
}

Formatter interface. Format method needs to be called from within Decorator.Decor method in order to format string according to decor.WC settings. No need to implement manually as long as decor.WC is embedded.

type ShutdownListener 

type ShutdownListener interface {
	OnShutdown()
}

ShutdownListener interface. If decorator needs to be notified once upon bar shutdown event, so this is the right interface to implement.

type SizeB1000 

type SizeB1000 int64

SizeB1000 named type, which implements fmt.Formatter interface. It adjusts its value according to byte size multiple by 1000 and appends appropriate size marker (KB, MB, GB, TB).

func (SizeB1000) Format 

func (s SizeB1000) Format(f fmt.State, verb rune)

func (SizeB1000) String 

func (i SizeB1000) String() string

type SizeB1024 

type SizeB1024 int64

SizeB1024 named type, which implements fmt.Formatter interface. It adjusts its value according to byte size multiple by 1024 and appends appropriate size marker (KiB, MiB, GiB, TiB).

func (SizeB1024) Format 

func (s SizeB1024) Format(f fmt.State, verb rune)

func (SizeB1024) String 

func (i SizeB1024) String() string

type Statistics 

type Statistics struct {
	AvailableWidth int // calculated width initially equal to terminal width
	RequestedWidth int // width set by `mpb.WithWidth`
	ID             int
	Total          int64
	Current        int64
	Refill         int64
	Completed      bool
	Aborted        bool
}

Statistics contains fields which are necessary for implementing `decor.Decorator` and `mpb.BarFiller` interfaces.

type Synchronizer 

type Synchronizer interface {
	Sync() (chan int, bool)
}

Synchronizer interface. All decorators implement this interface implicitly. Its Sync method exposes width sync channel, if DSyncWidth bit is set.

type TimeNormalizer 

type TimeNormalizer interface {
	Normalize(time.Duration) time.Duration
}

TimeNormalizer interface. Implementers could be passed into MovingAverageETA, in order to affect i.e. normalize its output.

func FixedIntervalTimeNormalizer 

func FixedIntervalTimeNormalizer(updInterval int) TimeNormalizer

FixedIntervalTimeNormalizer returns implementation of TimeNormalizer.

func MaxTolerateTimeNormalizer 

func MaxTolerateTimeNormalizer(maxTolerate time.Duration) TimeNormalizer

MaxTolerateTimeNormalizer returns implementation of TimeNormalizer.

type TimeNormalizerFunc 

type TimeNormalizerFunc func(time.Duration) time.Duration

TimeNormalizerFunc is function type adapter to convert function into TimeNormalizer.

func (TimeNormalizerFunc) Normalize 

func (f TimeNormalizerFunc) Normalize(src time.Duration) time.Duration

type TimeStyle 

type TimeStyle int

TimeStyle enum. 

const (
	ET_STYLE_GO TimeStyle = iota
	ET_STYLE_HHMMSS
	ET_STYLE_HHMM
	ET_STYLE_MMSS
)

TimeStyle kinds.

type WC 

type WC struct {
	W int
	C int
	// contains filtered or unexported fields
}

WC is a struct with two public fields W and C, both of int type. W represents width and C represents bit set of width related config. A decorator should embed WC, to enable width synchronization.

func (WC) Format added in v8.5.0 

func (wc WC) Format(str string) (string, int)

Format should be called by any Decorator implementation. Returns formatted string and its view (visual) width.

func (*WC) Init 

func (wc *WC) Init() WC

Init initializes width related config.

func (WC) Sync 

func (wc WC) Sync() (chan int, bool)

Sync is implementation of Synchronizer interface.

type Wrapper 

type Wrapper interface {
	Unwrap() Decorator
}

Wrapper interface. If you're implementing custom Decorator by wrapping a built-in one, it is necessary to implement this interface to retain functionality of built-in Decorator.

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.