philiprehberger-progress 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ba10a34300c085657e70aed11c006694d2c0ea2dccba5e0ea82a6c04fce1c50f
+  data.tar.gz: 78f0c3f6adb6c673b841dffb3e6743ac44042de833b8bf7e7bb1a75132e827a8
+SHA512:
+  metadata.gz: 17a190189ef3f1fb0487ba312796067c4fc91599452698eb7cb390fc1c928e14f9c5dce0b81d3107dd3c56c2af1fcbd4336c949db896b7d680b74f71dd65ed61
+  data.tar.gz: b7d8033d7265d4719a60b455b9635047ca0adbdf72eacb96445a7a92960a88608ac0375ebe3d2481075a1cc7bb65417db5869becbbf43882817728c3146b3a54

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-21
+
+### Added
+- Initial release
+- `Bar` class with percentage, ETA, throughput, and customizable format
+- `Spinner` class with multiple frame sets (default, braille, dots)
+- `Multi` class for tracking multiple concurrent progress bars
+- Convenience methods `Progress.bar`, `Progress.spin`, `Progress.multi`
+- `Enumerable#each_with_progress` integration
+- TTY detection to auto-disable rendering in non-terminal environments

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,140 @@
+# philiprehberger-progress
+
+[![Tests](https://github.com/philiprehberger/rb-progress/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-progress/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/philiprehberger-progress.svg)](https://rubygems.org/gems/philiprehberger-progress)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-progress)](LICENSE)
+
+Terminal progress bars and spinners with ETA calculation and throughput display
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'philiprehberger-progress'
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-progress
+```
+
+## Usage
+
+### Progress Bar
+
+```ruby
+require 'philiprehberger/progress'
+
+Philiprehberger::Progress.bar(total: 100) do |bar|
+  100.times do
+    sleep(0.01)
+    bar.advance
+  end
+end
+```
+
+### Custom Format
+
+```ruby
+bar = Philiprehberger::Progress::Bar.new(
+  total: 100,
+  format: ':bar :percent | :current/:total | :rate items/s | ETA: :eta',
+  width: 30
+)
+bar.advance(50)
+puts bar.to_s
+```
+
+### Spinner
+
+```ruby
+Philiprehberger::Progress.spin('Loading...') do |spinner|
+  10.times do
+    sleep(0.1)
+    spinner.spin
+  end
+end
+```
+
+### Enumerable Integration
+
+```ruby
+items = (1..100).to_a
+items.each_with_progress('Processing') do |item|
+  sleep(0.01)
+end
+```
+
+### Multi-Bar
+
+```ruby
+multi = Philiprehberger::Progress.multi
+bar1 = multi.bar('Downloads', total: 100)
+bar2 = multi.bar('Uploads', total: 50)
+
+bar1.advance(10)
+bar2.advance(5)
+multi.render
+```
+
+## API
+
+### `Philiprehberger::Progress`
+
+| Method | Description |
+|--------|-------------|
+| `.bar(total:, format:, width:)` | Create a progress bar (yields if block given) |
+| `.spin(message, frames:)` | Create a spinner (yields if block given) |
+| `.multi` | Create a multi-bar display |
+
+### `Philiprehberger::Progress::Bar`
+
+| Method | Description |
+|--------|-------------|
+| `.new(total:, format:, width:)` | Create a progress bar |
+| `#advance(n)` | Advance by `n` items (default: 1) |
+| `#finish` | Mark as complete |
+| `#finished?` | Whether the bar is finished |
+| `#percentage` | Current percentage (0.0 to 100.0) |
+| `#elapsed` | Elapsed time in seconds |
+| `#eta` | Estimated time remaining in seconds |
+| `#rate` | Throughput in items per second |
+| `#to_s` | Render the bar as a string |
+
+### `Philiprehberger::Progress::Spinner`
+
+| Method | Description |
+|--------|-------------|
+| `.new(message:, frames:)` | Create a spinner |
+| `#spin` | Advance to the next frame |
+| `#done(message)` | Mark as done with optional message |
+| `#done?` | Whether the spinner is done |
+| `#to_s` | Render the current frame |
+
+### `Philiprehberger::Progress::Multi`
+
+| Method | Description |
+|--------|-------------|
+| `.new` | Create a multi-bar display |
+| `#bar(label, total:)` | Add a new progress bar |
+| `#render` | Render all bars |
+| `#size` | Number of bars |
+| `#finished?` | Whether all bars are finished |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec      # Run tests
+bundle exec rubocop    # Check code style
+```
+
+## License
+
+MIT

data/lib/philiprehberger/progress/bar.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module Progress
+    # A terminal progress bar with ETA and throughput display
+    #
+    # @example
+    #   bar = Bar.new(total: 100)
+    #   100.times { bar.advance }
+    #   bar.finish
+    class Bar
+      DEFAULT_FORMAT = ':bar :percent | :current/:total | :rate items/s | ETA: :eta'
+      DEFAULT_WIDTH = 30
+      FILL_CHAR = "\u2588"
+      EMPTY_CHAR = "\u2591"
+
+      attr_reader :current, :total
+
+      # Create a new progress bar
+      #
+      # @param total [Integer] total number of items
+      # @param format [String] format string with placeholders
+      # @param width [Integer] width of the bar portion in characters
+      # @param output [IO] output stream (default: $stderr)
+      def initialize(total:, format: DEFAULT_FORMAT, width: DEFAULT_WIDTH, output: $stderr)
+        @total = [total, 0].max
+        @format = format
+        @width = width
+        @output = output
+        @current = 0
+        @start_time = now
+        @finished = false
+      end
+
+      # Advance the progress bar
+      #
+      # @param n [Integer] number of items to advance (default: 1)
+      # @return [self]
+      def advance(n = 1)
+        return self if @finished
+
+        @current = [@current + n, @total].min
+        render if tty?
+        self
+      end
+
+      # Mark the progress as complete
+      #
+      # @return [self]
+      def finish
+        @current = @total
+        @finished = true
+        render if tty?
+        @output.write("\n") if tty?
+        self
+      end
+
+      # Check if the progress is finished
+      #
+      # @return [Boolean]
+      def finished?
+        @finished
+      end
+
+      # Get the progress percentage
+      #
+      # @return [Float] percentage from 0.0 to 100.0
+      def percentage
+        return 100.0 if @total.zero?
+
+        (@current.to_f / @total * 100).round(1)
+      end
+
+      # Get the elapsed time in seconds
+      #
+      # @return [Float]
+      def elapsed
+        now - @start_time
+      end
+
+      # Get the estimated time remaining in seconds
+      #
+      # @return [Float, nil] nil if no progress has been made
+      def eta
+        return 0.0 if @current >= @total
+        return nil if @current.zero?
+
+        elapsed_time = elapsed
+        rate = @current.to_f / elapsed_time
+        (@total - @current) / rate
+      end
+
+      # Get the throughput in items per second
+      #
+      # @return [Float]
+      def rate
+        elapsed_time = elapsed
+        return 0.0 if elapsed_time.zero?
+
+        @current.to_f / elapsed_time
+      end
+
+      # Render the progress bar as a string
+      #
+      # @return [String]
+      def to_s
+        result = @format.dup
+        result.gsub!(':bar', render_bar)
+        result.gsub!(':percent', format('%<pct>5.1f%%', pct: percentage))
+        result.gsub!(':current', @current.to_s)
+        result.gsub!(':total', @total.to_s)
+        result.gsub!(':rate', format('%<r>.1f', r: rate))
+        result.gsub!(':eta', format_duration(eta))
+        result.gsub!(':elapsed', format_duration(elapsed))
+        result
+      end
+
+      private
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def tty?
+        @output.respond_to?(:tty?) && @output.tty?
+      end
+
+      def render
+        @output.write("\r#{self}")
+      end
+
+      def render_bar
+        return FILL_CHAR * @width if @total.zero?
+
+        filled = (@current.to_f / @total * @width).round
+        empty = @width - filled
+        (FILL_CHAR * filled) + (EMPTY_CHAR * empty)
+      end
+
+      def format_duration(seconds)
+        return '--:--' if seconds.nil? || seconds.negative?
+
+        seconds = seconds.to_i
+        if seconds < 60
+          format('0:%02d', seconds)
+        elsif seconds < 3600
+          format('%d:%02d', seconds / 60, seconds % 60)
+        else
+          format('%d:%02d:%02d', seconds / 3600, (seconds % 3600) / 60, seconds % 60)
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/progress/multi.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module Progress
+    # Multi-bar progress display for tracking multiple concurrent tasks
+    #
+    # @example
+    #   multi = Multi.new
+    #   bar1 = multi.bar('Downloads', total: 100)
+    #   bar2 = multi.bar('Uploads', total: 50)
+    class Multi
+      # Create a new multi-bar display
+      #
+      # @param output [IO] output stream (default: $stderr)
+      def initialize(output: $stderr)
+        @output = output
+        @bars = []
+      end
+
+      # Add a new progress bar
+      #
+      # @param label [String] label for the bar
+      # @param total [Integer] total items
+      # @param format [String] format string
+      # @param width [Integer] bar width
+      # @return [Bar]
+      def bar(label, total:, format: nil, width: 20)
+        bar_format = format || ":bar :percent | #{label}"
+        progress_bar = Bar.new(total: total, format: bar_format, width: width, output: StringIO.new)
+        @bars << { label: label, bar: progress_bar }
+        progress_bar
+      end
+
+      # Render all bars
+      #
+      # @return [self]
+      def render
+        return self unless tty?
+
+        # Move cursor up to overwrite previous render
+        @output.write("\e[#{@bars.length}A") if @rendered_once
+        @bars.each do |entry|
+          @output.write("\r\e[2K#{entry[:bar]}\n")
+        end
+        @rendered_once = true
+        self
+      end
+
+      # Number of bars being tracked
+      #
+      # @return [Integer]
+      def size
+        @bars.length
+      end
+
+      # Check if all bars are finished
+      #
+      # @return [Boolean]
+      def finished?
+        @bars.all? { |entry| entry[:bar].finished? }
+      end
+
+      private
+
+      def tty?
+        @output.respond_to?(:tty?) && @output.tty?
+      end
+    end
+  end
+end

data/lib/philiprehberger/progress/spinner.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module Progress
+    # A terminal spinner for indeterminate progress
+    #
+    # @example
+    #   spinner = Spinner.new(message: 'Loading...')
+    #   spinner.spin
+    #   spinner.done
+    class Spinner
+      DEFAULT_FRAMES = %w[| / - \\].freeze
+      BRAILLE_FRAMES = %W[\u2807 \u2816 \u2830 \u2821 \u280B \u2819 \u2838 \u2824].freeze
+      DOTS_FRAMES = %W[\u2800 \u2801 \u2803 \u2807 \u280F \u281F \u283F \u287F \u28FF].freeze
+
+      FRAME_SETS = {
+        default: DEFAULT_FRAMES,
+        braille: BRAILLE_FRAMES,
+        dots: DOTS_FRAMES
+      }.freeze
+
+      # Create a new spinner
+      #
+      # @param message [String] message to display next to the spinner
+      # @param frames [Symbol, Array<String>] frame set name or custom frames
+      # @param output [IO] output stream (default: $stderr)
+      def initialize(message: '', frames: :default, output: $stderr)
+        @message = message
+        @frames = frames.is_a?(Symbol) ? FRAME_SETS.fetch(frames, DEFAULT_FRAMES) : frames
+        @output = output
+        @index = 0
+        @done = false
+      end
+
+      # Advance the spinner by one frame
+      #
+      # @return [self]
+      def spin
+        return self if @done
+
+        render if tty?
+        @index = (@index + 1) % @frames.length
+        self
+      end
+
+      # Mark the spinner as done
+      #
+      # @param message [String] optional completion message
+      # @return [self]
+      def done(message = nil)
+        @done = true
+        if tty?
+          clear_line
+          @output.write("#{message || @message}\n") if message || !@message.empty?
+        end
+        self
+      end
+
+      # Check if the spinner is done
+      #
+      # @return [Boolean]
+      def done?
+        @done
+      end
+
+      # Return the current frame
+      #
+      # @return [String]
+      def to_s
+        frame = @frames[@index % @frames.length]
+        @message.empty? ? frame : "#{frame} #{@message}"
+      end
+
+      private
+
+      def tty?
+        @output.respond_to?(:tty?) && @output.tty?
+      end
+
+      def render
+        @output.write("\r#{self}")
+      end
+
+      def clear_line
+        @output.write("\r\e[2K")
+      end
+    end
+  end
+end

data/lib/philiprehberger/progress/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module Progress
+    VERSION = '0.1.0'
+  end
+end

data/lib/philiprehberger/progress.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'stringio'
+require_relative 'progress/version'
+require_relative 'progress/bar'
+require_relative 'progress/spinner'
+require_relative 'progress/multi'
+
+module Philiprehberger
+  module Progress
+    class Error < StandardError; end
+
+    # Create and yield a progress bar
+    #
+    # @param total [Integer] total number of items
+    # @param format [String] format string
+    # @param width [Integer] bar width
+    # @param output [IO] output stream
+    # @yield [Bar] the progress bar
+    # @return [Object] the block's return value
+    def self.bar(total:, format: Bar::DEFAULT_FORMAT, width: Bar::DEFAULT_WIDTH, output: $stderr, &block)
+      progress_bar = Bar.new(total: total, format: format, width: width, output: output)
+
+      if block
+        result = yield progress_bar
+        progress_bar.finish unless progress_bar.finished?
+        result
+      else
+        progress_bar
+      end
+    end
+
+    # Create and yield a spinner
+    #
+    # @param message [String] message to display
+    # @param frames [Symbol, Array<String>] frame set
+    # @param output [IO] output stream
+    # @yield the work to perform
+    # @return [Object] the block's return value
+    def self.spin(message = 'Loading...', frames: :default, output: $stderr, &block)
+      spinner = Spinner.new(message: message, frames: frames, output: output)
+
+      if block
+        result = yield spinner
+        spinner.done unless spinner.done?
+        result
+      else
+        spinner
+      end
+    end
+
+    # Create a multi-bar display
+    #
+    # @param output [IO] output stream
+    # @return [Multi]
+    def self.multi(output: $stderr)
+      Multi.new(output: output)
+    end
+  end
+end
+
+# Enumerable integration
+module Enumerable
+  # Iterate with a progress bar
+  #
+  # @param message [String] label for the progress bar
+  # @param output [IO] output stream
+  # @yield [Object] each element
+  # @return [Array]
+  def each_with_progress(message = 'Processing', output: $stderr)
+    items = to_a
+    bar = Philiprehberger::Progress::Bar.new(
+      total: items.length,
+      format: ":bar :percent | #{message} | :current/:total",
+      output: output
+    )
+
+    items.each do |item|
+      yield item
+      bar.advance
+    end
+
+    bar.finish
+    items
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-progress
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-22 00:00:00.000000000 Z
+dependencies: []
+description: Display progress bars with percentage, ETA, and throughput, or spinners
+  for indeterminate tasks. Supports multi-bar display, Enumerable integration, and
+  auto-disables when not connected to a terminal.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/progress.rb
+- lib/philiprehberger/progress/bar.rb
+- lib/philiprehberger/progress/multi.rb
+- lib/philiprehberger/progress/spinner.rb
+- lib/philiprehberger/progress/version.rb
+homepage: https://github.com/philiprehberger/rb-progress
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-progress
+  source_code_uri: https://github.com/philiprehberger/rb-progress
+  changelog_uri: https://github.com/philiprehberger/rb-progress/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/philiprehberger/rb-progress/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Terminal progress bars and spinners with ETA calculation and throughput display
+test_files: []