ioprogress

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

• func ByteUnitStr(n int64) string
• func DrawTextFormatBytes(progress, total int64) string
• type DrawFunc
  • func DrawTerminal(w io.Writer) DrawFunc
  • func DrawTerminalf(w io.Writer, f DrawTextFormatFunc) DrawFunc
• type DrawTextFormatFunc
  • func DrawTextFormatBar(width int64) DrawTextFormatFunc
  • func DrawTextFormatBarForW(width int64, w io.Writer) DrawTextFormatFunc
• type Reader
  • func (r *Reader) Read(p []byte) (int, error)

Functions

func ByteUnitStr

func ByteUnitStr(n int64) string

ByteUnitStr pretty prints a number of bytes.

func DrawTextFormatBytes

func DrawTextFormatBytes(progress, total int64) string

DrawTextFormatBytes is a DrawTextFormatFunc that formats the progress and total into human-friendly byte formats.

Types

type DrawFunc

type DrawFunc func(int64, int64) error

DrawFunc is the callback type for drawing progress.

func DrawTerminal

func DrawTerminal(w io.Writer) DrawFunc

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

type DrawTextFormatFunc func(int64, int64) string

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 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.

func (*Reader) Read

func (r *Reader) Read(p []byte) (int, error)

Read reads from the underlying reader and invokes the DrawFunc if appropriate. The DrawFunc is executed when there is data that is read (progress is made) and at least DrawInterval time has passed.