philiprehberger-progress 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d1ecb051d55213a818343c3133c067129bf55e65b6677a2efb9be49c249ab5b
-  data.tar.gz: '0039452f607ef4f9fe1f1a1098b31039c6ea7ecbc9c0618c8f8fba78b5464763'
+  metadata.gz: fb855052746be6b7d6a120d7ad8b84ce16c8ccce47534463d04b698c680ea0fa
+  data.tar.gz: 2bf7bbafcf7feb5985c8baacc4a5eb10cbab3b5ee75f25d10a0512704230212a
 SHA512:
-  metadata.gz: da6edc69bcc8dc77d091ba848dae89fb8f8e5054ceb1f9c6991537e85554b8a3bbde4cef23b94089d0c6194827ae6c13e3a7cb02f875d9d7ca9e3960519d7023
-  data.tar.gz: 5692a7b42fb906e3234117a3a96ca0ad2c1af88d558bc41e7a787cd8c1cc954a5c317613b91ff8d913b27b87263ea279d8bf497b19f17886cf57c8141578b6f8
+  metadata.gz: 0b5e4769b17f4a50df8fba852ad7a9eddd1821207051bc1cd3011a2a1ef71afd2369ea6d984be789cb95be6a3e2271caf4872b32180d96ed63ddd0538956c9c1
+  data.tar.gz: c71135352b91900baa613bd2b2c87edd51d1992bd57ef586734b3328fd9fb44c330c2a1af8ecb2827f0b29ba7180860e453ffbe1abfc4e7e1a25142c811d5dc4

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-05-07
+
+### Added
+- `Bar#remaining` — number of steps remaining (clamped to non-negative). Also added to `Bar#to_h`.
+
+## [0.5.0] - 2026-04-14
+
+### Added
+- `Bar#pause` and `Bar#resume` to freeze and unfreeze elapsed time calculation
+- `Bar#to_h` returns a hash with `:percentage`, `:elapsed`, `:eta`, `:throughput`, `:current`, `:total`
+- Custom bar characters via `fill:`, `empty:`, `tip:` keyword arguments (defaults: `fill: '='`, `empty: ' '`, `tip: '>'`)
+- `Progress.json_mode!` and `Progress.text_mode!` to toggle JSON line output for bar rendering
+
 ## [0.4.0] - 2026-04-09
 
 ### Added

data/README.md

@@ -81,6 +81,59 @@ 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):
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+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
 
 ```ruby
@@ -121,17 +174,22 @@ multi.finished?  # => true
 
 | Method | Description |
 |--------|-------------|
-| `.new(total:, width: 30, output: $stderr)` | Create a progress bar |
+| `.new(total:, width: 30, output: $stderr, fill: '=', empty: ' ', tip: '>')` | Create a progress bar |
 | `#advance(n = 1)` | Advance by `n` items |
 | `#set(n)` | Set absolute progress position (clamped to 0..total) |
 | `#reset` | Reset to 0, clear finished state, restart timer |
+| `#pause` | Pause the bar, freezing elapsed time |
+| `#resume` | Resume after pause |
+| `#paused?` | Whether the bar is paused |
 | `#finish` | Mark as complete |
 | `#finished?` | Whether the bar is finished |
 | `#percentage` | Current percentage (0.0 to 100.0) |
-| `#elapsed` | Elapsed time in seconds |
+| `#elapsed` | Elapsed time in seconds (excludes paused time) |
 | `#eta` | Estimated time remaining in seconds |
 | `#throughput` | Items per second |
-| `#to_s` | Render the bar as a string |
+| `#remaining` | Number of steps remaining (clamped to non-negative) |
+| `#to_h` | Hash with `:percentage`, `:elapsed`, `:eta`, `:throughput`, `:current`, `:total`, `:remaining` |
+| `#to_s` | Render the bar as a string (or JSON line in json_mode) |
 
 ### `Philiprehberger::Progress::Spinner`
 
@@ -167,6 +225,9 @@ multi.finished?  # => true
 | `Progress.multi(output: $stderr, &block)` | Create multi-bar tracker |
 | `Progress.each(enumerable, label: nil) { \|item\| }` | Iterate with progress |
 | `Progress.map(enumerable, label: nil) { \|item\| }` | Transform with progress, returns results |
+| `Progress.json_mode!` | Switch bar rendering to JSON line output |
+| `Progress.text_mode!` | Switch bar rendering back to ANSI text |
+| `Progress.json_mode?` | Whether JSON mode is active |
 
 ## Development
 

data/lib/philiprehberger/progress/bar.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module Philiprehberger
   module Progress
     class Bar
@@ -8,13 +10,19 @@ module Philiprehberger
 
       attr_reader :current, :total
 
-      def initialize(total:, width: 30, output: $stderr)
+      def initialize(total:, width: 30, output: $stderr, fill: '=', empty: ' ', tip: '>')
         @total = [total, 0].max
         @width = width
         @output = output
         @current = 0
         @start_time = now
         @finished = false
+        @paused = false
+        @pause_elapsed = 0.0
+        @pause_start = nil
+        @fill = fill
+        @empty = empty
+        @tip = tip
       end
 
       def advance(n = 1)
@@ -43,10 +51,40 @@ module Philiprehberger
       def reset
         @current = 0
         @finished = false
+        @paused = false
+        @pause_elapsed = 0.0
+        @pause_start = nil
         @start_time = now
         self
       end
 
+      # Pause the progress bar, freezing elapsed time calculation.
+      #
+      # @return [self]
+      def pause
+        return self if @paused || @finished
+
+        @paused = true
+        @pause_start = now
+        self
+      end
+
+      # Resume after pause.
+      #
+      # @return [self]
+      def resume
+        return self unless @paused
+
+        @pause_elapsed += now - @pause_start
+        @pause_start = nil
+        @paused = false
+        self
+      end
+
+      def paused?
+        @paused
+      end
+
       def finish
         @current = @total
         @finished = true
@@ -65,8 +103,17 @@ module Philiprehberger
         (@current.to_f / @total * 100).round(1)
       end
 
+      # Number of steps remaining (clamped to non-negative).
+      #
+      # @return [Integer]
+      def remaining
+        [@total - @current, 0].max
+      end
+
       def elapsed
-        now - @start_time
+        raw = now - @start_time - @pause_elapsed
+        raw -= (now - @pause_start) if @paused
+        raw
       end
 
       def eta
@@ -85,7 +132,21 @@ module Philiprehberger
         @current.to_f / elapsed_time
       end
 
+      def to_h
+        {
+          percentage: percentage,
+          elapsed: elapsed,
+          eta: eta,
+          throughput: throughput,
+          current: @current,
+          total: @total,
+          remaining: remaining
+        }
+      end
+
       def to_s
+        return to_h.to_json if Philiprehberger::Progress.json_mode?
+
         bar_str = render_bar
         pct = format('%<p>5.1f%%', p: percentage)
         eta_str = format_eta(eta)
@@ -109,11 +170,16 @@ module Philiprehberger
       end
 
       def render_bar
-        return FILL_CHAR * @width if @total.zero?
+        return @fill * @width if @total.zero?
 
         filled = (@current.to_f / @total * @width).round
         empty = @width - filled
-        (FILL_CHAR * filled) + (EMPTY_CHAR * empty)
+
+        if filled.positive? && filled < @width
+          (@fill * (filled - 1)) + @tip + (@empty * empty)
+        else
+          (@fill * filled) + (@empty * empty)
+        end
       end
 
       def format_eta(seconds)

data/lib/philiprehberger/progress/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module Progress
-    VERSION = '0.4.0'
+    VERSION = '0.6.0'
   end
 end

data/lib/philiprehberger/progress.rb

@@ -7,8 +7,22 @@ require_relative 'progress/multi'
 
 module Philiprehberger
   module Progress
-    def self.bar(total:, width: 30, output: $stderr)
-      progress_bar = Bar.new(total: total, width: width, output: output)
+    @json_mode = false
+
+    def self.json_mode!
+      @json_mode = true
+    end
+
+    def self.text_mode!
+      @json_mode = false
+    end
+
+    def self.json_mode?
+      @json_mode
+    end
+
+    def self.bar(total:, width: 30, output: $stderr, fill: '=', empty: ' ', tip: '>')
+      progress_bar = Bar.new(total: total, width: width, output: output, fill: fill, empty: empty, tip: tip)
 
       if block_given?
         result = yield progress_bar

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-progress
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-10 00:00:00.000000000 Z
+date: 2026-05-07 00:00:00.000000000 Z
 dependencies: []
 description: Display progress bars with percentage, ETA, and throughput, or spinners
   for indeterminate tasks. Supports block-based usage, enumerable iteration with each/map,