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 ¶
- Variables
- func DebugSleep(ctx context.Context)
- 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 Colors
- type Opt
- type Progress
- func (p *Progress) NewByteCounter(msg string, size int64, opts ...Opt) *Bar
- func (p *Progress) NewTimeoutWaiter(msg string, expires time.Time, opts ...Opt) *Bar
- func (p *Progress) NewUnitCounter(msg, unit string, opts ...Opt) *Bar
- func (p *Progress) NewUnitTotalCounter(msg, unit string, total int64, opts ...Opt) *Bar
- func (p *Progress) NewWaiter(msg string, clock bool, opts ...Opt) *Bar
- func (p *Progress) Stop()
- type Writer
Constants ¶
This section is empty.
Variables ¶
var OptDebugSleep = options.NewDuration(
"debug.progress.sleep",
"",
0,
0,
"DEBUG: Sleep during operations to facilitate testing progress bars",
`DEBUG: Sleep during operations to facilitate testing progress bars.`,
)
OptDebugSleep configures DebugSleep. It should be removed when the progress impl is stable.
var OptMemUsage = optMemUsage{}
OptMemUsage is an Opt that causes the bar to display program memory usage.
Functions ¶
func DebugSleep ¶
DebugSleep sleeps for a period of time to facilitate testing the progress impl. It uses the value from OptDebugSleep. This function (and OptDebugSleep) should be removed when the progress impl is stable.
func Incr ¶
Incr increments the progress of the outermost bar (if any) in ctx by amount n. 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 a bit hesitant in going even 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 struct {
// contains filtered or unexported fields
}
Bar represents a single progress bar. The caller should invoke Bar.Incr as necessary to increment the bar's progress. When the bar is complete, the caller should invoke Bar.Stop. All methods are safe to call on a nil Bar.
type Colors ¶
type Colors struct {
Error *color.Color
Filler *color.Color
MemUsage *color.Color
Message *color.Color
Percent *color.Color
Size *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 Opt ¶
type Opt interface {
// contains filtered or unexported methods
}
Opt is a functional option for Bar creation.
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 ¶
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 public 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.NewX methods.
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) 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