philiprehberger-progress

Terminal progress bars and spinners with ETA calculation and throughput display

Requirements

Ruby >= 3.1

Installation

Add to your Gemfile:

gem "philiprehberger-progress"

Or install directly:

gem install philiprehberger-progress

Usage

Progress Bar

require "philiprehberger/progress"

bar = Philiprehberger::Progress::Bar.new(total: 100)
100.times do
  sleep(0.01)
  bar.advance
end
bar.finish
# [████████████████████████████████] 100.0% | 100/100 | ETA: 0s | 100.0/s

Block Usage

Philiprehberger::Progress.bar(total: 100) do |bar|
  100.times { bar.advance }
end
# Auto-finishes when block completes

Spinner

spinner = Philiprehberger::Progress::Spinner.new(message: 'Loading...')
10.times do
  sleep(0.1)
  spinner.spin
end
spinner.stop('done')

Block Spinner

Philiprehberger::Progress.spin('Processing...') do |spinner|
  10.times { spinner.spin; sleep(0.1) }
end

Auto-spinning

Start a background thread that animates the spinner automatically:

Philiprehberger::Progress.spin("Deploying...") do |spinner|
  spinner.auto_spin
  deploy!  # spinner animates while you work
end

The thread is joined automatically when stop is called (or when the block completes).

Pause and Resume

Pause the progress bar to freeze elapsed time calculation (e.g. while waiting for user input):

bar = Philiprehberger::Progress::Bar.new(total: 100)
50.times { bar.advance }
bar.pause
# ... elapsed time is frozen ...
bar.resume
50.times { bar.advance }
bar.finish

Custom Bar Characters

Customize the fill, empty, and tip characters:

bar = Philiprehberger::Progress::Bar.new(total: 100, fill: '#', empty: '.', tip: '>')
50.times { bar.advance }
bar.to_s
# [########################>.........................]  50.0% | 50/100 | ETA: 0s | 50.0/s

Default characters are fill: '=', empty: ' ', tip: '>'.

Data Export

Export the current state as a hash:

bar = Philiprehberger::Progress::Bar.new(total: 100)
50.times { bar.advance }
bar.to_h
# => { percentage: 50.0, elapsed: 1.2, eta: 1.2, throughput: 41.7, current: 50, total: 100, remaining: 50 }
bar.remaining # => 50

JSON Mode

Switch to JSON line output for machine-readable progress:

Philiprehberger::Progress.json_mode!
bar = Philiprehberger::Progress::Bar.new(total: 100)
50.times { bar.advance }
bar.to_s
# {"percentage":50.0,"elapsed":1.2,"eta":1.2,"throughput":41.7,"current":50,"total":100}

Philiprehberger::Progress.text_mode!  # revert to ANSI bar

Enumerable Integration

items = (1..100).to_a
Philiprehberger::Progress.each(items) do |item|
  sleep(0.01)
end

Mapping with Progress

Transform items while displaying progress:

results = Philiprehberger::Progress.map(urls) { |url| fetch(url) }
# results contains the return values from each block call

Multi-bar

require "philiprehberger/progress"

multi = Philiprehberger::Progress.multi do |m|
  downloads = m.add("Downloads", total: 100)
  uploads   = m.add("Uploads", total: 50)

  100.times { downloads.advance }
  50.times { uploads.advance }
end

multi.finished?  # => true

API