README
¶
ioprogress
ioprogress is a Go (golang) library with implementations of io.Reader
and io.Writer that draws progress bars. The primary use case for these
are for CLI applications but alternate progress bar writers can be supplied
for alternate environments.
Example
Installation
Standard go get:
$ go get github.com/mitchellh/ioprogress
Usage
Here is an example of outputting a basic progress bar to the CLI as
we're "downloading" from some other io.Reader (perhaps from a network
connection):
// Imagine this came from some external source, such as a network connection,
// and that we have the full size of it, such as from a Content-Length HTTP
// header.
var r io.Reader
// Create the progress reader
progressR := &ioprogress.Reader{
Reader: r,
Size: rSize,
}
// Copy all of the reader to some local file f. As it copies, the
// progressR will write progress to the terminal on os.Stdout. This is
// customizable.
io.Copy(f, progressR)
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrorProgressOutOfBounds is returned if the progress is set to a value // not between 0 and 1. ErrorProgressOutOfBounds = fmt.Errorf("progress is out of bounds (0 to 1)") // ErrorNoBarsAdded is returned when no progress bars have been added to a // ProgressBarPrinter before PrintAndWait is called. ErrorNoBarsAdded = fmt.Errorf("AddProgressBar hasn't been called yet") )
Functions ¶
func DrawTextFormatBytes ¶
DrawTextFormatBytes is a DrawTextFormatFunc that formats the progress and total into human-friendly byte formats.
Types ¶
type CopyProgressPrinter ¶
type CopyProgressPrinter struct {
// contains filtered or unexported fields
}
func (*CopyProgressPrinter) PrintAndWait ¶
type DrawFunc ¶
DrawFunc is the callback type for drawing progress.
func DrawTerminal ¶
DrawTerminal returns a DrawFunc that draws a progress bar to an io.Writer that is assumed to be a terminal (and therefore respects carriage returns).
func DrawTerminalf ¶
func DrawTerminalf(w io.Writer, f DrawTextFormatFunc) DrawFunc
DrawTerminalf returns a DrawFunc that draws a progress bar to an io.Writer that is formatted with the given formatting function.
type DrawTextFormatFunc ¶
DrawTextFormatFunc is a callback used by DrawFuncs that draw text in order to format the text into some more human friendly format.
func DrawTextFormatBar ¶
func DrawTextFormatBar(width int64) DrawTextFormatFunc
DrawTextFormatBar returns a DrawTextFormatFunc that draws a progress bar with the given width (in characters). This can be used in conjunction with another DrawTextFormatFunc to create a progress bar with bytes, for example:
bar := DrawTextFormatBar(20)
func(progress, total int64) string {
return fmt.Sprintf(
"%s %s",
bar(progress, total),
DrawTextFormatBytes(progress, total))
}
func DrawTextFormatBarForW ¶
func DrawTextFormatBarForW(width int64, w io.Writer) DrawTextFormatFunc
DrawTextFormatBarForW returns a DrawTextFormatFunc as described in the docs for DrawTextFormatBar, however if the io.Writer passed in is not a tty then the returned function will always return "".
type ProgressBar ¶
type ProgressBar struct {
// contains filtered or unexported fields
}
ProgressBar represents one progress bar in a ProgressBarPrinter. Should not be created directly, use the AddProgressBar on a ProgressBarPrinter to create these.
func (*ProgressBar) SetCurrentProgress ¶
func (pb *ProgressBar) SetCurrentProgress(progress float64) error
SetCurrentProgress sets the progress of this ProgressBar. The progress must be between 0 and 1 inclusive.
func (*ProgressBar) SetPrintAfter ¶
func (pb *ProgressBar) SetPrintAfter(after string)
SetPrintAfter sets the text printed on the line after the progress bar.
func (*ProgressBar) SetPrintBefore ¶
func (pb *ProgressBar) SetPrintBefore(before string)
SetPrintBefore sets the text printed on the line before the progress bar.
type ProgressBarPrinter ¶
type ProgressBarPrinter struct {
// DisplayWidth can be set to influence how large the progress bars are.
// The bars will be scaled to attempt to produce lines of this number of
// characters, but lines of different lengths may still be printed. When
// this value is 0 (aka unset), 80 character columns are assumed.
DisplayWidth int
// PadToBeEven, when set to true, will make Print pad the printBefore text
// with trailing spaces and the printAfter text with leading spaces to make
// the progress bars the same length.
PadToBeEven bool
// contains filtered or unexported fields
}
ProgressBarPrinter will print out the progress of some number of ProgressBars.
func (*ProgressBarPrinter) AddProgressBar ¶
func (pbp *ProgressBarPrinter) AddProgressBar() *ProgressBar
AddProgressBar will create a new ProgressBar, register it with this ProgressBarPrinter, and return it. This must be called at least once before PrintAndWait is called.
func (*ProgressBarPrinter) Print ¶
func (pbp *ProgressBarPrinter) Print(printTo io.Writer) (bool, error)
Print will print out progress information for each ProgressBar that has been added to this ProgressBarPrinter. The progress will be written to printTo, and if printTo is a terminal it will draw progress bars. AddProgressBar must be called at least once before Print is called. If printing to a terminal, all draws after the first one will move the cursor up to draw over the previously printed bars.
type Reader ¶
type Reader struct {
// Reader is the underlying reader to read from
Reader io.Reader
// Size is the total size of the data coming out of the reader.
Size int64
// DrawFunc is the callback to invoke to draw the progress bar. By
// default, this will be DrawTerminal(os.Stdout).
//
// DrawInterval is the minimum time to wait between reads to update the
// progress bar.
DrawFunc DrawFunc
DrawInterval time.Duration
// contains filtered or unexported fields
}
Reader is an implementation of io.Reader that draws the progress of reading some data.
Source Files