ruby-progress 1.1.3 → 1.1.8

data/blog-post.md

@@ -0,0 +1,174 @@
+---
+title: "More CLI Progress Indicators: The ruby-progress Gem"
+date: 2025-10-10
+categories: [Ruby, CLI, Development Tools]
+tags: [ruby, cli, progress, animation, terminal]
+---
+
+[ripple]: https://brettterpstra.com/2025/06/30/ripple-an-indeterminate-progress-indicator/
+
+# More CLI Progress Indicators: The ruby-progress Gem
+
+The `ruby-progress` gem expands my previous work on [Ripple], adding 2 more indicator types and a new daemon mode to make it more useful in non-Ruby shell scripts.
+
+## What is ruby-progress?
+
+Ruby-progress provides animated progress indicators for command-line applications. Unlike traditional progress bars showing completion percentage, this gem focuses on continuous animations (indeterminate) that indicate activity - perfect for tasks with unpredictable completion times.
+
+Three animation styles are available:
+
+- **Ripple**: Wave-like effect across text
+- **Worm**: Moving dot pattern that crawls across the screen
+- **Twirl**: Classic spinning indicators with various symbols
+
+## Quick Start
+
+```bash
+# Install
+gem install ruby-progress
+
+# Basic usage
+ripple "Processing files..."
+worm --message "Loading..." --speed fast
+twirl --spinner dots
+```
+
+## Ruby Integration
+
+```ruby
+require 'ruby-progress'
+
+# Block syntax with automatic cleanup
+RubyProgress::Ripple.progress("Processing files...") do
+  process_files
+  upload_results
+end
+
+# Manual control
+worm = RubyProgress::Worm.new(
+  message: "Custom task",
+  style: 'blocks',
+  speed: 'medium'
+)
+
+worm.animate { heavy_computation }
+```
+
+## Daemon Mode - The Killer Feature
+
+Run progress indicators in the background while your scripts execute:
+
+```bash
+# Start background indicator
+worm --daemon --pid-file /tmp/progress.pid --message "Deploying..."
+
+# Run your actual work
+./deploy.sh
+kubectl apply -f manifests/
+
+# Stop with success message
+worm --stop /tmp/progress.pid --message "Deploy complete!" --checkmark
+```
+
+This is incredibly useful for complex deployment scripts where you want continuous visual feedback without interrupting the main process.
+
+There's a unified binary called `prg` that takes the three types as subcommands, e.g. `prg twirl --checkmark`. You can use any of them either way.
+
+## Advanced Features
+
+### Error Handling
+```ruby
+RubyProgress::Ripple.progress("Risky operation") do
+  might_fail_operation
+rescue StandardError => e
+  # Automatically stops and shows error state
+  puts "Failed: #{e.message}"
+end
+```
+
+### Command Integration
+```ruby
+# Execute shell commands with progress
+RubyProgress::Worm.new(
+  command: "pg_dump mydb > backup.sql",
+  success: "Backup complete!",
+  error: "Backup failed"
+).run_with_command
+```
+
+### Visual Customization
+```ruby
+# Rainbow colors and custom styling
+RubyProgress::Ripple.progress("Colorful task",
+  rainbow: true,
+  speed: :fast,
+  format: :forward_only
+) do
+  process_with_style
+end
+```
+
+## Real-World Examples
+
+### Deployment Script
+
+```bash
+#!/bin/bash
+worm --daemon-as deploy --message "Deploying..." &
+
+git push production main
+kubectl rollout status deployment/app
+
+worm --stop-id deploy --stop-success "Success!" --checkmark
+```
+
+### Data Processing
+```ruby
+def import_large_csv(file)
+  RubyProgress::Ripple.progress("Importing #{File.basename(file)}...") do
+    CSV.foreach(file, headers: true) { |row| User.create!(row.to_h) }
+  end
+end
+```
+
+### Rake Tasks
+```ruby
+task :backup do
+  RubyProgress::Worm.new(
+    command: "tar -czf backup.tar.gz app/",
+    success: "Backup created successfully!"
+  ).run_with_command
+end
+```
+
+## Why ruby-progress?
+
+- **Simple API**: Works in Ruby code and shell scripts
+- **Visual Appeal**: Engaging animations beyond basic spinners
+- **Unique Daemon Mode**: Background progress indicators
+- **Production Ready**: 84.55% test coverage, 113 test examples, zero failures
+- **Cross-Platform**: Linux, macOS, Windows support
+- **Reliable**: Comprehensive error handling and edge case coverage
+
+## Installation & First Steps
+
+1. **Install**: `gem install ruby-progress`
+2. **Test CLI**: `ripple "Hello World!"`
+3. **Try in Ruby**:
+   ```ruby
+   require 'ruby-progress'
+   RubyProgress::Ripple.progress("Testing...") { sleep 2 }
+   ```
+
+## Conclusion
+
+Ruby-progress transforms boring CLI applications into engaging user experiences. Whether building deployment scripts, data processing tools, or utility commands, it provides the visual feedback users expect from modern command-line tools.
+
+The daemon mode alone makes it worth trying - no other progress library offers this level of flexibility for complex workflows.
+
+**Links:**
+- [GitHub](https://github.com/ttscoff/ruby-progress)
+- [RubyGems](https://rubygems.org/gems/ruby-progress)
+- [Latest Release](https://github.com/ttscoff/ruby-progress/releases/latest)
+
+*Make your CLI tools feel alive with ruby-progress!*

data/examples/daemon_demo.rb

@@ -18,7 +18,7 @@ puts "PID file: #{pid_file}"
 puts
 
 # Clean up any existing PID file
-File.delete(pid_file) if File.exist?(pid_file)
+FileUtils.rm_f(pid_file)
 
 puts '1. Starting worm progress indicator in daemon mode...'
 bin_path = File.join(File.dirname(__dir__), 'bin', 'prg')

data/experimental_terminal.rb

@@ -0,0 +1,55 @@
+# Experimental terminal line protection for daemon mode
+# This demonstrates potential solutions for the daemon output interruption problem
+
+module RubyProgress
+  module SmartTerminal
+    # Save current cursor position
+    def self.save_cursor_position
+      $stderr.print "\e[s" # Save cursor position
+      $stderr.flush
+    end
+
+    # Restore cursor to saved position
+    def self.restore_cursor_position
+      $stderr.print "\e[u" # Restore cursor position
+      $stderr.flush
+    end
+
+    # Get current cursor position (requires terminal interaction)
+    def self.get_cursor_position
+      # This is complex and requires reading from stdin
+      # which may not work reliably in daemon mode
+      $stderr.print "\e[6n" # Request cursor position
+      $stderr.flush
+      # Would need to read response: "\e[{row};{col}R"
+      # But this requires terminal input capability
+    end
+
+    # Alternative: Use absolute positioning
+    def self.position_cursor_absolute(row, col)
+      $stderr.print "\e[#{row};#{col}H"
+      $stderr.flush
+    end
+
+    # Enhanced line clearing that works from any position
+    def self.clear_current_line_and_reposition
+      $stderr.print "\r"        # Move to start of line
+      $stderr.print "\e[2K"     # Clear entire line
+      $stderr.print "\e[1A"     # Move up one line (in case we're on a new line)
+      $stderr.print "\r"        # Move to start again
+      $stderr.print "\e[2K"     # Clear that line too
+      $stderr.flush
+    end
+
+    # Experimental: Try to "reclaim" the animation line
+    def self.reclaim_animation_line(animation_text)
+      # Strategy: Clear multiple lines and reposition
+      $stderr.print "\r"        # Go to start of current line
+      $stderr.print "\e[2K"     # Clear current line
+      $stderr.print "\e[1A"     # Move up one line
+      $stderr.print "\e[2K"     # Clear that line
+      $stderr.print animation_text # Print our animation
+      $stderr.flush
+    end
+  end
+end

data/lib/ruby-progress/daemon.rb

@@ -45,10 +45,10 @@ module RubyProgress
       begin
         Process.kill('USR1', pid)
         sleep 0.5
-        File.delete(pid_file) if File.exist?(pid_file)
+        FileUtils.rm_f(pid_file)
       rescue Errno::ESRCH
         puts "Process #{pid} not found (may have already stopped)"
-        File.delete(pid_file) if File.exist?(pid_file)
+        FileUtils.rm_f(pid_file)
         exit 1
       rescue Errno::EPERM
         puts "Permission denied sending signal to process #{pid}"

data/lib/ruby-progress/ripple.rb

@@ -31,57 +31,27 @@ module RubyProgress
   INDICATORS = {
     arc: %w[◜ ◠ ◝ ◞ ◡ ◟],
     arrow: %w[← ↖ ↑ ↗ → ↘ ↓ ↙],
-    arrow_pulse: [
-      '▹▹▹▹▹',
-      '▸▹▹▹▹',
-      '▹▸▹▹▹',
-      '▹▹▸▹▹',
-      '▹▹▹▸▹',
-      '▹▹▹▹▸'
-    ],
-    balloon: %w[. o O ° O o .],
-    block_1: %w[▖▖▖ ▘▖▖ ▖▘▖ ▖▖▘],
     block_2: %w[▌ ▀ ▐ ▄],
-    bounce: [
-      '[    ]',
-      '[=   ]',
-      '[==  ]',
-      '[=== ]',
-      '[====]'
-    ],
-    circle: %w[○○○ ●○○ ○●○ ○○●],
+    block_1: %w[▖▖▖ ▘▖▖ ▖▘▖ ▖▖▘],
+    bounce: %w[⠁ ⠂ ⠄ ⡀ ⢀ ⠠ ⠐ ⠈],
     classic: ['|', '/', '—', '\\'],
     dots: %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏],
     dots_2: %w[⣾ ⣽ ⣻ ⢿ ⡿ ⣟ ⣯ ⣷],
     dots_3: %w[⠋ ⠙ ⠚ ⠞ ⠖ ⠦ ⠴ ⠲ ⠳ ⠓],
-    dots_4: %w[⠄ ⠆ ⠇ ⠋ ⠙ ⠸ ⠰ ⠠ ⠰ ⠸ ⠙ ⠋ ⠇ ⠆],
-    dots_5: %w[⠋ ⠙ ⠚ ⠒ ⠂ ⠂ ⠒ ⠲ ⠴ ⠦ ⠖ ⠒ ⠐ ⠐ ⠒ ⠓ ⠋],
-    dots_6: %w[⠁ ⠉ ⠙ ⠚ ⠒ ⠂ ⠂ ⠒ ⠲ ⠴ ⠤ ⠄ ⠄ ⠤ ⠴ ⠲ ⠒ ⠂ ⠂ ⠒ ⠚ ⠙ ⠉ ⠁],
-    dots_7: %w[⠈ ⠉ ⠋ ⠓ ⠒ ⠐ ⠐ ⠒ ⠖ ⠦ ⠤ ⠠ ⠠ ⠤ ⠦ ⠖ ⠒ ⠐ ⠐ ⠒ ⠓ ⠋ ⠉ ⠈],
-    dots_8: %w[⠁ ⠁ ⠉ ⠙ ⠚ ⠒ ⠂ ⠂ ⠒ ⠲ ⠴ ⠤ ⠄ ⠄ ⠤ ⠠ ⠠ ⠤ ⠦ ⠖ ⠒ ⠐ ⠐ ⠒ ⠓ ⠋ ⠉ ⠈ ⠈],
-    dots_9: %w[⢹ ⢺ ⢼ ⣸ ⣇ ⡧ ⡗ ⡏],
-    dots_10: %w[⢄ ⢂ ⢁ ⡁ ⡈ ⡐ ⡠],
-    dots_11: %w[⠁ ⠂ ⠄ ⡀ ⢀ ⠠ ⠐ ⠈],
+    dots_4: %w[⢹ ⢺ ⢼ ⣸ ⣇ ⡧ ⡗ ⡏],
     ellipsis: ['.   ', '..  ', '... ', '....'],
-    lighthouse: ['∙∙∙', '●∙∙', '∙●∙', '∙∙●'],
-    o: %w[Ooo oOo ooO],
     pipe: %w[┤ ┘ ┴ └ ├ ┌ ┬ ┐],
     pulse: %w[⎺ ⎻ ⎼ ⎽ ⎼ ⎻],
     pulse_2: %w[▁ ▃ ▅ ▆ ▇ █ ▇ ▆ ▅ ▃],
     pulse_3: %w[▉ ▊ ▋ ▌ ▍ ▎ ▏ ▎ ▍ ▌ ▋ ▊ ▉],
     pulse_4: %w[- = ≡ = -],
-    push: [
-      '[>    ]',
-      '[=>   ]',
-      '[==>  ]',
-      '[===> ]',
-      '[====>]'
-    ],
+    o: %w[Ooo oOo ooO],
     spin: %w[◴ ◷ ◶ ◵],
     spin_2: %w[◐ ◓ ◑ ◒],
     spin_3: %w[◰ ◳ ◲ ◱],
     toggle: %w[■ □ ▪ ▫],
-    triangle: %w[◢ ◣ ◤ ◥]
+    triangle: %w[◢ ◣ ◤ ◥],
+    twinkle: %w[⢄ ⢂ ⢁ ⡁ ⡈ ⡐ ⡠]
   }.freeze
 
   # String extensions for color support
@@ -93,7 +63,7 @@ module RubyProgress
     end
 
     def rainbow(index = 0)
-      chars = split('')
+      chars = self.chars
       colored_chars = chars.map.with_index do |char, idx|
         color = COLORS.values[(idx + index) % COLORS.size]
         "#{color}#{char}#{COLORS['reset']}"
@@ -104,7 +74,7 @@ module RubyProgress
     def normalize_type
       spinner_type = :classic
       INDICATORS.each do |spinner, _v|
-        spinner_type = spinner if spinner =~ /^#{split('').join('.*?')}/i
+        spinner_type = spinner if spinner =~ /^#{chars.join('.*?')}/i
       end
       spinner_type
     end
@@ -137,7 +107,7 @@ module RubyProgress
     end
 
     def printout
-      letters = @string.dup.split('')
+      letters = @string.dup.chars
       i = @index
       if @spinner
         case @spinner_position
@@ -168,7 +138,8 @@ module RubyProgress
         char = @rainbow ? char.rainbow(i) : char.extend(StringExtensions).light_white
         post = letters.slice!(0, letters.length).join.extend(StringExtensions).dark_white
       end
-      $stderr.print "\e[2K#{pre}#{char}#{post}\r"
+      $stderr.print "\r\e[2K#{pre}#{char}#{post}"
+      $stderr.flush
     end
 
     # Hide or show the cursor (delegated to Utils)

data/lib/ruby-progress/utils.rb

@@ -12,8 +12,20 @@ module RubyProgress
       $stderr.print "\e[?25h"
     end
 
-    def self.clear_line
-      print "\r\e[K"
+    def self.clear_line(output_stream = :stderr)
+      case output_stream
+      when :stdout
+        $stdout.print "\r\e[K"
+      else
+        $stderr.print "\r\e[K"
+      end
+    end
+
+    # Enhanced line clearing for daemon mode that handles output interruption
+    def self.clear_line_aggressive
+      $stderr.print "\r\e[2K"    # Clear entire current line
+      $stderr.print "\e[1A\e[2K" # Move up one line and clear it too
+      $stderr.print "\r"         # Return to start of line
     end
 
     # Universal completion message display
@@ -46,7 +58,7 @@ module RubyProgress
     # Clear current line and display completion message
     # Convenience method that combines line clearing with message display
     def self.complete_with_clear(message, success: true, show_checkmark: false, output_stream: :warn)
-      clear_line if output_stream != :warn # warn already includes clear in display_completion
+      clear_line(output_stream) if output_stream != :warn # warn already includes clear in display_completion
       display_completion(message, success: success, show_checkmark: show_checkmark, output_stream: output_stream)
     end
   end

data/lib/ruby-progress/version.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
 module RubyProgress
-  VERSION = '1.1.3'
+  VERSION = '1.1.8'
+  WORM_VERSION = '1.0.3'
+  TWIRL_VERSION = '1.0.1'
+  RIPPLE_VERSION = '1.0.5'
 end

data/lib/ruby-progress/worm.rb

@@ -23,6 +23,26 @@ module RubyProgress
         baseline: '▪',  # small black square
         midline: '▫',   # small white square
         peak: '■'       # large black square
+      },
+      'cirlces_small' => {
+        baseline: '∙',
+        midline: '∙',
+        peak: '●'
+      },
+      'arrow' => {
+        baseline: '▹',
+        midline: '▸',
+        peak: '▶'
+      },
+      'balloon' => {
+        baseline: '.',
+        midline: 'o',
+        peak: '°'
+      },
+      'circle_open' => {
+        baseline: '○',
+        midline: '●',
+        peak: '○'
       }
     }.freeze
 
@@ -35,7 +55,7 @@ module RubyProgress
 
     def initialize(options = {})
       @length = options[:length] || 3
-      @message = options[:message] || 'Processing'
+      @message = options[:message]
       @speed = parse_speed(options[:speed] || 'medium')
       @style = parse_style(options[:style] || 'circles')
       @command = options[:command]
@@ -57,7 +77,6 @@ module RubyProgress
         @running = false
         RubyProgress::Utils.clear_line
         RubyProgress::Utils.show_cursor
-        puts "\nInterrupted!"
         exit 130
       end
 
@@ -118,7 +137,6 @@ module RubyProgress
         # animate method handles error display, just exit with proper code
         exit exit_code.nonzero? || 1
       rescue Interrupt
-        puts "\nInterrupted!"
         exit 130
       end
     end
@@ -129,7 +147,6 @@ module RubyProgress
         @running = false
         RubyProgress::Utils.clear_line
         RubyProgress::Utils.show_cursor
-        puts "\nInterrupted!"
         exit 130
       end
 
@@ -161,7 +178,7 @@ module RubyProgress
       RubyProgress::Utils.hide_cursor
 
       begin
-        animation_loop_step while @running && !stop_requested
+        animation_loop_daemon_mode(stop_requested_proc: -> { stop_requested })
       ensure
         RubyProgress::Utils.clear_line
         RubyProgress::Utils.show_cursor
@@ -206,8 +223,9 @@ module RubyProgress
       @position ||= 0
       @direction ||= 1
 
-      print "\r#{@message}#{generate_dots(@position, @direction)}"
-      $stdout.flush
+      message_part = @message && !@message.empty? ? "#{@message} " : ''
+      $stderr.print "\r\e[2K#{message_part}#{generate_dots(@position, @direction)}"
+      $stderr.flush
 
       sleep @speed
 
@@ -239,7 +257,7 @@ module RubyProgress
         if speed_input.match?(/^\d+$/)
           # Numeric string (1-10)
           speed_num = speed_input.to_i
-          return 0.6 - (speed_num - 1) * 0.05 if speed_num.between?(1, 10)
+          return 0.6 - ((speed_num - 1) * 0.05) if speed_num.between?(1, 10)
         end
 
         # Check for abbreviated forms
@@ -255,25 +273,67 @@ module RubyProgress
         end
       when Numeric
         speed_num = speed_input.to_i
-        speed_num.between?(1, 10) ? 0.6 - (speed_num - 1) * 0.05 : SPEED_MAP['medium']
+        speed_num.between?(1, 10) ? 0.6 - ((speed_num - 1) * 0.05) : SPEED_MAP['medium']
       else
         SPEED_MAP['medium']
       end
     end
 
     def parse_style(style_input)
-      return RIPPLE_STYLES['circles'] unless style_input
-
-      style_lower = style_input.to_s.downcase
-      if style_lower.start_with?('b')
-        RIPPLE_STYLES['blocks']
-      elsif style_lower.start_with?('g')
-        RIPPLE_STYLES['geometric']
-      elsif style_lower.start_with?('c')
-        RIPPLE_STYLES['circles']
-      else
-        RIPPLE_STYLES['circles'] # default
+      return RIPPLE_STYLES['circles'] unless style_input && !style_input.to_s.strip.empty?
+
+      style_lower = style_input.to_s.downcase.strip
+
+      # First, try exact match
+      return RIPPLE_STYLES[style_lower] if RIPPLE_STYLES.key?(style_lower)
+
+      # Then try prefix matching - keys that start with the input
+      prefix_matches = RIPPLE_STYLES.keys.select do |key|
+        key.downcase.start_with?(style_lower)
+      end
+
+      unless prefix_matches.empty?
+        # For prefix matches, return the shortest one
+        best_match = prefix_matches.min_by(&:length)
+        return RIPPLE_STYLES[best_match]
+      end
+
+      # Try character-by-character fuzzy matching for partial inputs
+      # Find keys where the input characters appear in order (not necessarily contiguous)
+      fuzzy_matches = RIPPLE_STYLES.keys.select do |key|
+        key_chars = key.downcase.chars
+        input_chars = style_lower.chars
+
+        # Check if all input characters appear in order in the key
+        input_chars.all? do |char|
+          idx = key_chars.index(char)
+          if idx
+            key_chars = key_chars[idx + 1..-1] # Remove matched chars and continue
+            true
+          else
+            false
+          end
+        end
+      end
+
+      unless fuzzy_matches.empty?
+        # Sort by length (prefer shorter keys)
+        best_match = fuzzy_matches.min_by(&:length)
+        return RIPPLE_STYLES[best_match]
+      end
+
+      # Fallback to substring matching
+      substring_matches = RIPPLE_STYLES.keys.select do |key|
+        key.downcase.include?(style_lower)
+      end
+
+      unless substring_matches.empty?
+        best_match = substring_matches.min_by(&:length)
+        return RIPPLE_STYLES[best_match]
       end
+
+      # Default fallback
+      RIPPLE_STYLES['circles']
     end
 
     def animation_loop
@@ -281,10 +341,45 @@ module RubyProgress
       direction = 1
 
       while @running
-        print "\r#{@message}#{generate_dots(position, direction)}"
-        $stdout.flush
+        message_part = @message && !@message.empty? ? "#{@message} " : ''
+        # Enhanced line clearing for better daemon mode behavior
+        $stderr.print "\r\e[2K#{message_part}#{generate_dots(position, direction)}"
+        $stderr.flush
+
+        sleep @speed
+
+        position += direction
+        if position >= @length - 1
+          direction = -1
+        elsif position <= 0
+          direction = 1
+        end
+      end
+    end
+
+    # Enhanced animation loop for daemon mode with aggressive line clearing
+    def animation_loop_daemon_mode(stop_requested_proc: -> { false })
+      position = 0
+      direction = 1
+      frame_count = 0
+
+      while @running && !stop_requested_proc.call
+        message_part = @message && !@message.empty? ? "#{@message} " : ''
+
+        # Always clear current line
+        $stderr.print "\r\e[2K"
+
+        # Every few frames, use aggressive clearing to handle interruptions
+        if (frame_count % 10).zero?
+          $stderr.print "\e[1A\e[2K"   # Move up and clear that line too (in case of interruption)
+          $stderr.print "\r"           # Return to start
+        end
+
+        $stderr.print "#{message_part}#{generate_dots(position, direction)}"
+        $stderr.flush
 
         sleep @speed
+        frame_count += 1
 
         position += direction
         if position >= @length - 1

data/test_daemon_interruption.rb

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+# Test script to explore terminal cursor behavior with daemon output interruption
+
+require_relative 'lib/ruby-progress'
+
+puts 'Testing daemon output interruption behavior...'
+puts 'This will start a daemon and then output some text to see what happens.'
+
+# Start a daemon
+system("ruby -I lib bin/prg worm --daemon --message 'Testing daemon animation' &")
+
+sleep 1
+
+puts 'This output should interrupt the animation'
+puts 'And this is a second line of output'
+
+sleep 2
+
+puts 'More interrupting output after animation has been running'
+
+sleep 2
+
+# Stop the daemon
+system('ruby -I lib bin/prg --stop-all')
+
+puts 'Test completed'

data/test_daemon_orphan.rb

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+# Test script to reproduce daemon orphaning issue
+puts 'Starting daemon...'
+system("./bin/prg worm --daemon-as test 'Working on something...'")
+
+puts 'Daemon started, sleeping for 3 seconds...'
+puts 'Cancel this script with ^C during the sleep to reproduce the orphan issue'
+sleep 3
+
+puts 'Stopping daemon normally...'
+system('./bin/prg --stop-id test')
+puts 'Done'