philiprehberger-progress 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8cedfd9240c3ab6dd70848fbc63dca19ca4e3eea6d13ccada9e1663c73ca75d
-  data.tar.gz: 3a81c872fc39dc070eaa68e0393c0e65d9878f7d54b01bd3ec9af557a40b92e2
+  metadata.gz: 8cd9b24ec4af77caa0242168972123e46f8aefe0aa7d010f355f634462d4e7ad
+  data.tar.gz: 956912f23898fd45c2434b06030aea103af6d33f390f11fc432a7cf285983325
 SHA512:
-  metadata.gz: 309c39e3e947e5dc7c9465cd4f1a1feff1fa9ec38221a11325243202c8f9e6326f1e60b458138b9d7fb2ec50ddd5b98cdf7425227d4a913b0dda464a3fd3d137
-  data.tar.gz: 985d65af32ab52d1310b2f01e24b7024a1595e1357a1f09c074ad9bc636ffb0445a33b00fc5a943472955cf5c0d663df516905cb67140db80734ed6af218300e
+  metadata.gz: 79fcad8d626d2869ac6c3bfa9d29ec243c134f7c140dfca896282c940bb82b3879d25378b229162441708d13fc204c6e912c5f802fef0b9331fc4bd9bb845889
+  data.tar.gz: d0074a78f1adfa22c1c749bf6367c468dfdfb1fa011d56ab88b83faedcc86625ada2f5982430cdc2f69013c66ead9bd030058d0b538959b3778cbfc94c86cb9c

data/CHANGELOG.md

@@ -2,11 +2,29 @@
 
 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.1.0/),
-and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [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
+- `Bar#set(n)` to set absolute progress position
+- `Bar#reset` to restart the bar from 0, preserving configuration
+- `Spinner#message=` to update the spinner message dynamically
+
+### Changed
+- Standardize CHANGELOG header format to match template
+
 ## [0.3.0] - 2026-04-09
 
 ### Added
@@ -92,17 +110,3 @@ and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - `Progress.spin` convenience method with block support
 - `Progress.each` for iterating enumerables with progress display
 - TTY detection to auto-disable rendering in non-terminal environments
-
-[0.3.0]: https://github.com/philiprehberger/rb-progress/releases/tag/v0.3.0
-[0.2.0]: https://github.com/philiprehberger/rb-progress/releases/tag/v0.2.0
-[0.1.11]: https://github.com/philiprehberger/rb-progress/releases/tag/v0.1.11
-[0.1.10]: https://github.com/philiprehberger/rb-progress/releases/tag/v0.1.10
-[0.1.9]: https://github.com/philiprehberger/rb-progress/releases/tag/v0.1.9
-[0.1.8]: https://github.com/philiprehberger/rb-progress/releases/tag/v0.1.8
-[0.1.7]: https://github.com/philiprehberger/rb-progress/releases/tag/v0.1.7
-[0.1.6]: https://github.com/philiprehberger/rb-progress/releases/tag/v0.1.6
-[0.1.5]: https://github.com/philiprehberger/rb-progress/releases/tag/v0.1.5
-[0.1.4]: https://github.com/philiprehberger/rb-progress/releases/tag/v0.1.4
-[0.1.3]: https://github.com/philiprehberger/rb-progress/releases/tag/v0.1.3
-[0.1.2]: https://github.com/philiprehberger/rb-progress/releases/tag/v0.1.2
-[0.1.0]: https://github.com/philiprehberger/rb-progress/releases/tag/v0.1.0

data/README.md

@@ -81,6 +81,58 @@ 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 }
+```
+
+### 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,21 +173,28 @@ 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 |
+| `#to_h` | Hash with `:percentage`, `:elapsed`, `:eta`, `:throughput`, `:current`, `:total` |
+| `#to_s` | Render the bar as a string (or JSON line in json_mode) |
 
 ### `Philiprehberger::Progress::Spinner`
 
 | Method | Description |
 |--------|-------------|
 | `.new(message:, output: $stderr)` | Create a spinner |
+| `#message=` | Update the spinner message dynamically |
 | `#spin` | Advance to the next frame |
 | `#auto_spin(interval: 0.1)` | Start background thread animation |
 | `#stop(final_message = 'done')` | Stop with a message (joins background thread) |
@@ -164,6 +223,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)
@@ -25,6 +33,58 @@ module Philiprehberger
         self
       end
 
+      # Set absolute progress position.
+      #
+      # @param n [Integer] the new current value (clamped to 0..total)
+      # @return [self]
+      def set(n)
+        return self if @finished
+
+        @current = [[n, 0].max, @total].min
+        render_to_output
+        self
+      end
+
+      # Reset the bar to 0, preserving total and width. Restarts the timer.
+      #
+      # @return [self]
+      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
@@ -44,7 +104,9 @@ module Philiprehberger
       end
 
       def elapsed
-        now - @start_time
+        raw = now - @start_time - @pause_elapsed
+        raw -= (now - @pause_start) if @paused
+        raw
       end
 
       def eta
@@ -63,7 +125,20 @@ module Philiprehberger
         @current.to_f / elapsed_time
       end
 
+      def to_h
+        {
+          percentage: percentage,
+          elapsed: elapsed,
+          eta: eta,
+          throughput: throughput,
+          current: @current,
+          total: @total
+        }
+      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)
@@ -87,11 +162,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/spinner.rb

@@ -6,7 +6,7 @@ module Philiprehberger
       FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807",
                 "\u280F"].freeze
 
-      attr_reader :message
+      attr_accessor :message
 
       def initialize(message:, output: $stderr)
         @message = message

data/lib/philiprehberger/progress/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module Progress
-    VERSION = '0.3.0'
+    VERSION = '0.5.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.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-10 00:00:00.000000000 Z
+date: 2026-04-15 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,