Documentation
¶
Overview ¶
Package progress contains progress bar widget functionality. Use progress.New to create a new progress widget container. That widget should be added to a context using progress.NewContext, and retrieved via progress.FromContext. Invoke one of the Progress.NewX methods to create a new progress.Bar. Invoke Bar.Incr to increment the bar's progress, and invoke Bar.Stop to stop the bar. Be sure to invoke Progress.Stop when the progress widget is no longer needed.
You can use the progress.NewReader and progress.NewWriter functions to wrap an io.Reader or io.Writer, respectively, with a progress bar. Both functions expect the supplied ctx arg to contain a *progress.Progress. Note also that both wrappers are context-aware; that is, they will stop the reading/writing process when the context is canceled. Be sure to call Close on the wrappers when done.
Index ¶
- Constants
- Variables
- func Incr(ctx context.Context, n int)
- func NewBarContext(ctx context.Context, bar Bar) context.Context
- func NewContext(ctx context.Context, p *Progress) context.Context
- func NewReader(ctx context.Context, msg string, size int64, r io.Reader) io.Reader
- type Bar
- type BarOpt
- type Colors
- type Progress
- func (p *Progress) HideOnWriter(w io.Writer) io.Writer
- func (p *Progress) NewByteCounter(msg string, size int64, opts ...BarOpt) Bar
- func (p *Progress) NewFilesizeCounter(msg string, f *os.File, fp string, opts ...BarOpt) Bar
- func (p *Progress) NewTimeoutWaiter(msg string, expires time.Time, opts ...BarOpt) Bar
- func (p *Progress) NewUnitCounter(msg, unit string, opts ...BarOpt) Bar
- func (p *Progress) NewUnitTotalCounter(msg, unit string, total int64, opts ...BarOpt) Bar
- func (p *Progress) NewWaiter(msg string, opts ...BarOpt) Bar
- func (p *Progress) Stop()
- type Writer
Constants ¶
const ( // DefaultMaxBars is the default threshold at which any further bars are // combined into a group bar. DefaultMaxBars = 5 )
Variables ¶
var OptMemUsage = optMemUsage{}
OptMemUsage is an BarOpt that causes the bar to display program memory usage.
var OptTimer = optTimer{}
OptTimer is an BarOpt that causes the bar to display elapsed seconds.
Functions ¶
func Incr ¶
Incr invokes [Bar.Incr] with amount n on the outermost Bar in ctx. Use in conjunction with a context returned from NewBarContext. It safe to invoke Incr on a nil context or a context that doesn't contain a Bar.
NOTE: This context-based incrementing is a bit of an experiment. I'm hesitant in going further with context-based logic, as it's not clear to me that it's a good idea to lean on context so much. So, it's possible this mechanism may be removed in the future.
func NewBarContext ¶
NewBarContext returns ctx with bar added as a value. This context can be used in conjunction with progress.Incr to increment the progress bar.
func NewContext ¶
NewContext returns ctx with p added as a value.
func NewReader ¶
NewReader returns an io.Reader that wraps r, is context-aware, and generates a progress bar as bytes are read from r. It is expected that ctx contains a *progress.Progress, as returned by progress.FromContext. If not, this function delegates to contextio.NewReader: the returned reader will still be context-ware. See the contextio package for more details.
Context state is checked BEFORE every Read.
The returned io.Reader also implements io.Closer, even if the underlying reader does not. This is necessary because we need a means of stopping the progress bar when writing is complete. If the underlying reader does implement io.Closer, it will be closed when the returned reader is closed.
Types ¶
type Bar ¶
type Bar interface {
// Incr increments the progress bar by amount n.
Incr(n int)
// Stop stops and removes the bar, preventing further use of the bar.
Stop()
// contains filtered or unexported methods
}
Bar represents a single progress bar, owned by a Progress instance. The caller invokes Incr as necessary to increment the bar's progress. When the bar is complete, the caller should invoke Bar.Stop.
type BarOpt ¶ added in v0.48.0
type BarOpt interface {
// contains filtered or unexported methods
}
BarOpt is a functional option for Bar creation.
type Colors ¶
type Colors struct {
Error *color.Color
Filler *color.Color
MemUsage *color.Color
Message *color.Color
Percent *color.Color
Size *color.Color
Timer *color.Color
Waiting *color.Color
Warning *color.Color
}
Colors is the set of colors used for the progress bars.
func DefaultColors ¶
func DefaultColors() *Colors
DefaultColors returns the default colors used for the progress bars.
func (*Colors) EnableColor ¶
EnableColor enables or disables color for the progress bars.
type Progress ¶
type Progress struct {
// contains filtered or unexported fields
}
Progress represents a container that renders one or more progress bars. The caller is responsible for calling Progress.Stop to indicate completion.
func FromContext ¶
FromContext returns the Progress added to ctx via NewContext, or returns nil. Note that it is safe to invoke the methods of a nil Progress.
func New ¶
func New(ctx context.Context, out io.Writer, maxBars int, delay time.Duration, colors *Colors) *Progress
New returns a new Progress instance, which is a container for progress bars. The returned Progress instance is safe for concurrent use, and all of its exported methods can be safely invoked on a nil Progress. The caller is responsible for calling Progress.Stop on the returned Progress.
Arg delay specifies a duration to wait before rendering the progress bar. The Progress is lazily initialized, and thus the delay clock doesn't start ticking until the first call to one of the Progress.NewXBar functions.
Arg maxBars specifies the threshold at which any further bars are combined into a group bar. This is useful for UX, to avoid flooding the terminal with progress bars, and for performance, as the progress widgets don't scale well. If maxBars is <= 0, a nil Progress is returned, which won't render any UX.
func (*Progress) HideOnWriter ¶ added in v0.48.0
HideOnWriter returns an io.Writer that hides the Progress when w is written to. Note that the Progress may show itself again after its render delay has elapsed anew. HideOnWriter is typically called with os.Stdout, to hide the Progress when the main program writes to stdout.
func (*Progress) NewByteCounter ¶
NewByteCounter returns a new determinate bar whose label metric is the size in bytes of the data being processed. The caller is ultimately responsible for calling Bar.Stop on the returned Bar.
func (*Progress) NewFilesizeCounter ¶ added in v0.47.4
NewFilesizeCounter returns a new indeterminate bar whose label metric is a filesize, or "-" if it can't be read. If f is non-nil, its size is used; else the file at path fp is used. The caller is ultimately responsible for calling Bar.Stop on the returned Bar.
func (*Progress) NewTimeoutWaiter ¶
NewTimeoutWaiter returns a new indeterminate bar whose label is the amount of time remaining until expires. It produces output similar to:
Locking @sakila ●∙∙ timeout in 7s
The caller is ultimately responsible for calling Bar.Stop on the returned bar, although the bar will also be stopped when the parent Progress stops.
func (*Progress) NewUnitCounter ¶
NewUnitCounter returns a new indeterminate bar whose label metric is the plural of the provided unit. The caller is ultimately responsible for calling Bar.Stop on the returned Bar.
bar := p.NewUnitCounter("Ingest records", "rec")
defer bar.Stop()
for i := 0; i < 100; i++ {
bar.Incr(1)
time.Sleep(100 * time.Millisecond)
}
This produces output similar to:
Ingesting records ∙∙● 87 recs
Note that the unit arg is automatically pluralized.
func (*Progress) NewUnitTotalCounter ¶
NewUnitTotalCounter returns a new determinate bar whose label metric is the plural of the provided unit. The caller is ultimately responsible for calling Bar.Stop on the returned Bar.
This produces output similar to:
Ingesting sheets ∙∙∙∙∙● 4 / 16 sheets
Note that the unit arg is automatically pluralized.
type Writer ¶
type Writer interface {
io.WriteCloser
// Stop stops and removes the progress bar. Typically this is accomplished
// by invoking Writer.Close, but there are circumstances where it may
// be desirable to stop the progress bar without closing the underlying
// writer.
Stop()
}
Writer is an io.WriteCloser as returned by NewWriter.
func NewWriter ¶
NewWriter returns a progress.Writer that wraps w, is context-aware, and generates a progress bar as bytes are written to w. It is expected that ctx contains a *progress.Progress, as returned by progress.FromContext. If not, this function delegates to contextio.NewWriter: the returned writer will still be context-aware. See the contextio package for more details.
Context state is checked BEFORE every Write.
The returned progress.Writer implements io.ReaderFrom to allow io.Copy to select the best strategy while still checking the context state before every chunk transfer.
The returned progress.Writer also implements io.Closer, even if the underlying writer does not. This is necessary because we need a means of stopping the progress bar when writing is complete. If the underlying writer does implement io.Closer, it will be closed when the returned writer is closed.
The caller is expected to close the returned writer, which results in the progress bar being removed. However, the progress bar can also be removed independently of closing the writer by invoking Writer.Stop.
If size is unknown, set to -1; this will result in an indeterminate progress spinner instead of a bar.
Source Files