README
¶
progress
Package progress provides terminal progress bar rendering with stage support for CLI utilities. It handles ANSI escape codes for line clearing and overwriting to show updating progress without scrolling the terminal.
Features
- Single-stage and multi-stage progress tracking
- Unicode and ASCII progress bar rendering
- Terminal line overwriting for smooth updates
- Configurable bar and text widths
Installation
import "github.com/grokify/mogo/fmt/progress"
Usage
SingleStageRenderer
Use SingleStageRenderer for simple progress tracking with a single operation:
package main
import (
"os"
"time"
"github.com/grokify/mogo/fmt/progress"
)
func main() {
// Create renderer writing to stdout
renderer := progress.NewSingleStageRenderer(os.Stdout).
WithBarWidth(40).
WithTextWidth(30)
items := []string{"file1.txt", "file2.txt", "file3.txt"}
total := len(items)
for i, item := range items {
renderer.Update(i+1, total, item)
time.Sleep(500 * time.Millisecond) // simulate work
}
// Clear progress and show completion message
renderer.Done("Processing complete!")
}
Output while running:
[████████████████░░░░░░░░░░░░░░░░░░░░░░░░] 40% (2/5) file2.txt
MultiStageRenderer
Use MultiStageRenderer for operations with multiple distinct phases:
package main
import (
"os"
"github.com/grokify/mogo/fmt/progress"
)
func main() {
renderer := progress.NewMultiStageRenderer(os.Stderr).
WithBarWidth(20).
WithDescWidth(34)
totalStages := 3
// Stage 1: Fetching data
for i := 0; i <= 10; i++ {
renderer.Update(progress.StageInfo{
Stage: 1,
TotalStages: totalStages,
Description: "Fetching repositories",
Current: i,
Total: 10,
})
}
renderer.Update(progress.StageInfo{
Stage: 1,
TotalStages: totalStages,
Description: "Fetching repositories",
Done: true,
})
// Stage 2: Processing
renderer.Update(progress.StageInfo{
Stage: 2,
TotalStages: totalStages,
Description: "Processing data",
Done: true,
})
// Stage 3: Writing output
renderer.Update(progress.StageInfo{
Stage: 3,
TotalStages: totalStages,
Description: "Writing results",
Done: true,
})
}
Output:
[1/3] Fetching repositories [████████████████████] 100%
[2/3] Processing data [████████████████████] 100%
[3/3] Writing results [████████████████████] 100%
Progress Bar Rendering
The package provides two bar rendering functions:
// Unicode bar (default): [████████░░░░░░░░░░░░]
bar := progress.RenderBar(50, 20)
// ASCII bar: [==========----------]
bar := progress.RenderBarASCII(50, 20)
Types
StageInfo
type StageInfo struct {
Stage int // Current stage number (1-based)
TotalStages int // Total number of stages
Description string // What's happening in this stage
Current int // Current item within stage (0 if not applicable)
Total int // Total items in stage (0 if not applicable)
Done bool // True if this stage is complete
Text string // Optional extra text (e.g., current item name)
}
The Percent() method returns the completion percentage for the stage.
Integration Pattern
A common pattern is to pass a progress callback to long-running functions:
type ProgressFunc func(current, total int, name string)
func ProcessItems(items []Item, progress ProgressFunc) error {
for i, item := range items {
if progress != nil {
progress(i+1, len(items), item.Name)
}
// process item...
}
return nil
}
// Usage
renderer := progress.NewSingleStageRenderer(os.Stdout)
err := ProcessItems(items, func(current, total int, name string) {
renderer.Update(current, total, name)
})
renderer.Done("")
Documentation
¶
Overview ¶
Package progress provides terminal progress bar rendering with stage support. It handles ANSI escape codes for line clearing and overwriting to show updating progress without scrolling the terminal.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RenderBar ¶
RenderBar creates a visual progress bar string. width is the number of characters for the bar (excluding brackets). Returns a string like "[████████░░░░░░░░░░░░]"
func RenderBarASCII ¶
RenderBarASCII creates a progress bar using ASCII characters only. Returns a string like "[========------------]"
Types ¶
type MultiStageRenderer ¶
type MultiStageRenderer struct {
// contains filtered or unexported fields
}
MultiStageRenderer handles displaying progress to a terminal with stage support. It manages line clearing and overwriting for smooth progress updates.
func NewMultiStageRenderer ¶
func NewMultiStageRenderer(w io.Writer) *MultiStageRenderer
NewMultiStageRenderer creates a new multi-stage progress renderer that writes to w. Default bar width is 20 characters, description width is 34 characters.
func (*MultiStageRenderer) Update ¶
func (r *MultiStageRenderer) Update(info StageInfo)
Update displays the current progress state. When Done is false, the line is overwritten on subsequent calls. When Done is true, a newline is printed and the next update starts on a new line.
func (*MultiStageRenderer) WithBarWidth ¶
func (r *MultiStageRenderer) WithBarWidth(width int) *MultiStageRenderer
WithBarWidth sets the width of the progress bar in characters.
func (*MultiStageRenderer) WithDescWidth ¶
func (r *MultiStageRenderer) WithDescWidth(width int) *MultiStageRenderer
WithDescWidth sets the width of the description field in characters.
type SingleStageRenderer ¶
type SingleStageRenderer struct {
// contains filtered or unexported fields
}
SingleStageRenderer handles displaying single-stage progress to a terminal. Use this for progress tracking without multiple stages.
func NewSingleStageRenderer ¶
func NewSingleStageRenderer(w io.Writer) *SingleStageRenderer
NewSingleStageRenderer creates a new single-stage progress renderer that writes to w. Default bar width is 40 characters, text width is 30 characters.
func (*SingleStageRenderer) Done ¶
func (r *SingleStageRenderer) Done(message string)
Done clears the progress line and optionally prints a completion message. If message is empty, just clears the line.
func (*SingleStageRenderer) Update ¶
func (r *SingleStageRenderer) Update(current, total int, text string)
Update displays the current progress state. The line is overwritten on subsequent calls. Call Done() when complete to print a newline.
func (*SingleStageRenderer) WithBarWidth ¶
func (r *SingleStageRenderer) WithBarWidth(width int) *SingleStageRenderer
WithBarWidth sets the width of the progress bar in characters.
func (*SingleStageRenderer) WithTextWidth ¶
func (r *SingleStageRenderer) WithTextWidth(width int) *SingleStageRenderer
WithTextWidth sets the width of the text field in characters.
type StageInfo ¶
type StageInfo struct {
Stage int // Current stage number (1-based)
TotalStages int // Total number of stages
Description string // What's happening in this stage
Current int // Current item within stage (0 if not applicable)
Total int // Total items in stage (0 if not applicable)
Done bool // True if this stage is complete
Text string // Optional extra text (e.g., current item name)
}
StageInfo contains information about the current progress state.
Source Files