bargo

README

bargo

bargo is a small Go library for rendering single-line terminal progress bars with an optional centered percentage label.

Installation

go get github.com/dmundt/bargo

Quick Start

package main

import (
	"fmt"

	"github.com/dmundt/bargo"
)

func main() {
	b := bargo.New()
	fmt.Println(b.Render(88.2, 60))
}

Example output:

[===========================88.2%===================       ]

API

• bargo.New(opts ...bargo.Option) *bargo.Bar
• (*Bar).Render(progress float64, width int) string
• (*Bar).RenderWithText(progress float64, width int, suffix string) string
• (*Bar).WriteTo(w io.Writer, progress float64, width int) (int, error)
• (*Bar).WriteToWithText(w io.Writer, progress float64, width int, suffix string) (int, error)

Defaults:

• Progress input scale is 0 to 100
• Width is the inner bar width (excluding delimiters)
• Percentage precision defaults to 1 decimal place
• Delimiters are [ and ]
• Fill and empty runes are = and space
• Moving head rune defaults to =
• Centered percentage label is visible by default
• Out-of-range input is clamped by default

Options

b := bargo.New(
	bargo.WithPercentDecimals(1),
	bargo.WithFillRune('='),
	bargo.WithHeadRune('>'),
	bargo.WithEmptyRune(' '),
	bargo.WithPercentVisible(true),
	bargo.WithClamp(true),
)

Per-update text can be appended after the bar without changing its width:

b := bargo.New()
fmt.Println(b.RenderWithText(5, 24, "20MB/400MB"))
fmt.Println(b.RenderWithText(40, 24, "File 4/10"))

Runnable example

Run the included sample program:

go run ./example

The example is a showcase of six option combinations:

1. defaults
2. custom head rune
3. hidden percent label
4. custom delimiters and runes
5. custom bounds (0-400)
6. per-update suffix

Showcase

The runnable example in example/main.go prints these six configurations:

shows := []showcase{
	{
		title:    "1) defaults",
		bar:      bargo.New(),
		progress: 12,
		width:    36,
	},
	{
		title:    "2) custom head rune",
		bar:      bargo.New(bargo.WithHeadRune('>')),
		progress: 85,
		width:    36,
	},
	{
		title:    "3) hidden percent label",
		bar:      bargo.New(bargo.WithPercentVisible(false)),
		progress: 55,
		width:    36,
	},
	{
		title: "4) custom delimiters and runes",
		bar: bargo.New(
			bargo.WithLeftDelim("{"),
			bargo.WithRightDelim("}"),
			bargo.WithFillRune('#'),
			bargo.WithHeadRune('>'),
			bargo.WithEmptyRune('.'),
		),
		progress: 68,
		width:    36,
	},
	{
		title: "5) custom bounds (0-400)",
		bar: bargo.New(
			bargo.WithBounds(0, 400),
			bargo.WithPercentDecimals(0),
		),
		progress: 260,
		width:    36,
	},
	{
		title: "6) per-update suffix",
		bar: bargo.New(
			bargo.WithHeadRune('>'),
		),
		progress: 35,
		width:    36,
		suffix:   "File 4/10",
	},
}

Example output style:

bargo showcase: 6 option combinations

1) defaults
[====           12.0%                ]

2) custom head rune
[===============85.0%==========>     ]

3) hidden percent label
[====================                ]

4) custom delimiters and runes
{###############68.0%###>............}

5) custom bounds (0-400)
[================260%===             ]

6) per-update suffix
[============>  35.0%                ] File 4/10

Testing

go test ./...

Changelog

See CHANGELOG.md for the full release history.

License

MIT

Documentation

Overview

Package bargo provides a single-line terminal progress bar with an optional centered percentage label.

Index

• type Bar
  • func New(opts ...Option) *Bar
  • func (b *Bar) Render(progress float64, width int) string
  • func (b *Bar) RenderWithText(progress float64, width int, suffix string) string
  • func (b *Bar) WriteTo(w io.Writer, progress float64, width int) (int, error)
  • func (b *Bar) WriteToWithText(w io.Writer, progress float64, width int, suffix string) (int, error)
• type Option
  • func WithBounds(min, max float64) Option
  • func WithCarriageReturn(enabled bool) Option
  • func WithClamp(enabled bool) Option
  • func WithEmptyRune(r rune) Option
  • func WithFillRune(r rune) Option
  • func WithHeadRune(r rune) Option
  • func WithLeftDelim(s string) Option
  • func WithPercentDecimals(n int) Option
  • func WithPercentVisible(enabled bool) Option
  • func WithRightDelim(s string) Option

Examples

• Bar.Render

Types

type Bar

type Bar struct {
	// contains filtered or unexported fields
}

Bar renders a progress bar. Create one with New.

func New

func New(opts ...Option) *Bar

New returns a Bar configured by the given options. Defaults: progress range 0–100, fill '=', empty ' ', delimiters '[' and ']', head '=', centered percent visible, 1 decimal place, clamping enabled, carriage return disabled.

func (*Bar) Render

func (b *Bar) Render(progress float64, width int) string

Render returns the formatted progress bar string for the given progress value and inner width (excluding delimiters). If clamping is enabled, progress is silently clamped to the configured min/max bounds before rendering.

Example

b := New()
fmt.Println(b.Render(50, 20))

Output:
[=======50.0%        ]

func (*Bar) RenderWithText

func (b *Bar) RenderWithText(progress float64, width int, suffix string) string

RenderWithText returns the formatted progress bar string with optional trailing text appended after the right delimiter.

func (*Bar) WriteTo

func (b *Bar) WriteTo(w io.Writer, progress float64, width int) (int, error)

WriteTo writes the rendered progress bar to w. If WithCarriageReturn is enabled a '\r' is prepended so the output overwrites the current terminal line.

func (*Bar) WriteToWithText

func (b *Bar) WriteToWithText(w io.Writer, progress float64, width int, suffix string) (int, error)

WriteToWithText writes the rendered progress bar with trailing text to w. If WithCarriageReturn is enabled a '\r' is prepended so the output overwrites the current terminal line.

type Option

type Option func(*config)

Option is a functional option for configuring a Bar.

func WithBounds

func WithBounds(min, max float64) Option

WithBounds sets the minimum and maximum values of the progress range. The default range is 0 to 100.

func WithCarriageReturn

func WithCarriageReturn(enabled bool) Option

WithCarriageReturn controls whether Bar.WriteTo prepends '\r' to the output, causing the bar to overwrite the current terminal line. Default is false.

func WithClamp

func WithClamp(enabled bool) Option

WithClamp controls whether out-of-range progress values are silently clamped to the configured bounds. Default is true.

func WithEmptyRune

func WithEmptyRune(r rune) Option

WithEmptyRune sets the rune used for the unfilled portion of the bar. Default is ' ' (space).

func WithFillRune

func WithFillRune(r rune) Option

WithFillRune sets the rune used for the filled portion of the bar. Default is '='.

func WithHeadRune

func WithHeadRune(r rune) Option

WithHeadRune sets the rune used for the moving head of the bar. Default is '='.

func WithLeftDelim

func WithLeftDelim(s string) Option

WithLeftDelim sets the opening delimiter of the bar. Default is "[".

func WithPercentDecimals

func WithPercentDecimals(n int) Option

WithPercentDecimals sets the number of decimal places shown in the percentage label. Negative values are treated as zero. Default is 1.

func WithPercentVisible

func WithPercentVisible(enabled bool) Option

WithPercentVisible controls whether the centered percentage label is shown. Default is true.

func WithRightDelim

func WithRightDelim(s string) Option

WithRightDelim sets the closing delimiter of the bar. Default is "]".