DOCSEARCHbyAlgolia
Submit Docs

progressbar

repository·main·Indexed 26 days ago

https://github.com/schollz/progressbar

A simple, thread-safe, and OS-agnostic progress bar library for Go. It supports known and unknown task lengths (via spinners), I/O stream tracking by implementing io.Writer and io.Reader, and customizable themes (ASCII, Unicode, Default). Features include real-time state retrieval, an optional HTTP server to expose progress as JSON, and a variety of predefined spinner animations.

Tokens
2.3K
Snippets
5
Records
16
Agent score
89%

What's inside progressbar

  3. Initialize a ProgressBar

    main

    You can create a new progress bar using several constructors depending on your needs:

    • New(max int): Creates a basic progress bar with a specified maximum.
    • New64(max int64): Creates a progress bar with a 64-bit maximum.
    • NewOptions(max int, options ...Option): Creates a progress bar with custom configuration via functional options.
    • NewOptions64(max int64, options ...Option): Creates a progress bar with custom configuration via functional options.

    To create a progress bar for measuring byte throughput with recommended defaults, use DefaultBytes(maxBytes int64, description ...string). For a standard progress bar with recommended defaults, use Default(max int64, description ...string).

  4. Track I/O operations with progressbar

    main

    The progressbar implements the io.Writer interface. This allows you to use it to track progress during data streams (like file downloads) by wrapping your destination writer with io.MultiWriter. Use progressbar.DefaultBytes(int64, string) to create a bar specifically designed for byte counts.

    req, _ := http.NewRequest("GET", "https://dl.google.com/go/go1.14.2.src.tar.gz", nil)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

f, _ := os.OpenFile("go1.14.2.src.tar.gz", os.O_CREATE|os.O_WRONLY, 0644)
defer f.Close()

bar := progressbar.DefaultBytes(
    resp.ContentLength,
    "downloading",
)
io.Copy(io.MultiWriter(f, bar), resp.Body)

  5. Use basic progress bar functionality

    main

    You can create a simple progress bar with a known length using progressbar.Default(int). Use the .Add(int) method to increment the progress.

    bar := progressbar.Default(100)
for i := 0; i < 100; i++ {
    bar.Add(1)
    time.Sleep(40 * time.Millisecond)
}

  6. Customize the progress bar appearance

    main

    Use progressbar.NewOptions(int, ...Option) to configure advanced settings such as colors, width, description, and themes.

    Common options include:

    • progressbar.OptionSetWriter(io.Writer): Change the output destination (e.g., using ansi.NewAnsiStdout() from github.com/k0kubun/go-ansi).
    • progressbar.OptionEnableColorCodes(bool): Enable ANSI color support.
    • progressbar.OptionShowBytes(bool): Show progress in bytes.
    • progressbar.OptionSetWidth(int): Set the bar width.
    • progressbar.OptionSetDescription(string): Set the text description.
    • progressbar.OptionSetTheme(progressbar.Theme): Define custom characters for the bar components (Saucer, SaucerHead, SaucerPadding, BarStart, BarEnd).
    bar := progressbar.NewOptions(1000,
    progressbar.OptionSetWriter(ansi.NewAnsiStdout()), // you should install "github.com/k0kubun/go-ansi"
    progressbar.OptionEnableColorCodes(true),
    progressbar.OptionShowBytes(true),
    progressbar.OptionSetWidth(15),
    progressbar.OptionSetDescription("[cyan][1/3][reset] Writing moshable file..."),
    progressbar.OptionSetTheme(progressbar.Theme{
        Saucer:        "[green]=[reset]",
        SaucerHead:    "[green]>[reset]",
        SaucerPadding: " ",
        BarStart:      "[",
        BarEnd:        "]",
    }))
for i := 0; i < 1000; i++ {
    bar.Add(1)
    time.Sleep(5 * time.Millisecond)
}

  7. Use ProgressBar as an io.Writer or io.Reader

    main
    The ProgressBar type implements both io.Writer and io.Reader interfaces. When you write to or read from a ProgressBar, it automatically calls Add(n) to update the progress based on the number of bytes processed.

  8. Expose Progress via HTTP Server

    main

    You can start a dedicated HTTP server to expose the progress bar's state as JSON or plain text. This is useful for displaying progress in external UIs or OS status bars.

    Endpoints:

    • GET /state: Returns the full State object as JSON.
    • GET /desc: Returns a human-readable description string (e.g., 50/100, 50.00%, 10s left).

    When the progress bar is finished, you should manually call server.Shutdown() or server.Close().

  10. Update Progress with Add and Set

    main

    Use the following methods to advance or modify the progress bar state:

    • Add(num int) / Add64(num int64): Increments the current progress by the specified amount.
    • Set(num int) / Set64(num int64): Sets the current progress to an absolute value.
    • Finish(): Fills the bar to the maximum value and marks it as finished.
    • Reset(): Resets the internal clock used for time calculations.
    • ChangeMax(newMax int) / ChangeMax64(newMax int64): Dynamically updates the maximum value of the bar.

  11. Print to the progress bar buffer with Bprintf and Bprintln

    main
    To print messages without breaking the progress bar display, use Bprintf or Bprintln. These functions handle locking and ensure that output is either written to the terminal (if the bar is not finished/invisible) or buffered appropriately to avoid visual corruption of the progress bar.

  12. Retrieve Progress Bar State

    main

    The State() method returns a State struct containing real-time metrics:

    • Max: The total target value.
    • CurrentNum: The current progress value.
    • CurrentPercent: Progress as a float (0.0 to 1.0).
    • CurrentBytes: Total bytes processed.
    • SecondsSince: Elapsed time in seconds.
    • SecondsLeft: Estimated time remaining in seconds.
    • KBsPerSecond: Throughput in KB/s.
    • Description: The current description string.