ruby-progress 1.1.9 → 1.2.4

data/demo_screencast.rb

@@ -0,0 +1,296 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Ruby Progress Gem Demo Screencast Script
+# ========================================
+#
+# This script creates a comprehensive demonstration of the ruby-progress gem
+# showing all major features across the three subcommands: ripple, worm, and twirl.
+#
+# Usage: ruby demo_screencast.rb
+#
+# The script includes pauses between demonstrations to allow for narration
+# and clear visual separation of different features.
+
+require 'io/console'
+
+# Demo runner that exercises the major features of the ruby-progress gem
+# used by the documentation and screencast recordings.
+class ProgressDemo
+  def initialize
+    @gem_path = File.expand_path('bin/prg', __dir__)
+    @lib_path = File.expand_path('lib', __dir__)
+
+    # Colors for terminal output
+    @colors = {
+      header: "\e[1;36m",    # Bright cyan
+      command: "\e[1;33m",   # Bright yellow
+      description: "\e[0;32m", # Green
+      reset: "\e[0m",        # Reset
+      dim: "\e[2m"           # Dim
+    }
+  end
+
+  def run
+    clear_screen
+    show_title
+
+    # Introduction
+    show_section_header('Ruby Progress Gem Demo')
+    show_description('Demonstrating terminal progress indicators with style!')
+    pause_for_narration(3)
+
+    # Basic examples for each command
+    demo_basic_commands
+
+    # Style demonstrations
+    demo_styles
+
+    # Advanced options
+    demo_advanced_options
+
+    # New v1.2.0 features
+    demo_new_features
+
+    # Finale
+    show_finale
+  end
+
+  private
+
+  def demo_basic_commands
+    show_section_header('Basic Commands Overview')
+
+    # Ripple - basic expanding circle animation
+    show_demo_header('Ripple', 'Expanding circle animation for tasks with unknown duration')
+    run_command("#{ruby_cmd} ripple --command 'sleep 4' --success 'Download complete!' --checkmark")
+    pause_between_demos
+
+    # Worm - progress bar animation
+    show_demo_header('Worm', 'Animated progress bar for visual feedback')
+    run_command("#{ruby_cmd} worm --length 10 --command 'sleep 5' --success 'Processing finished!' --checkmark")
+    pause_between_demos
+
+    # Twirl - spinning indicator
+    show_demo_header('Twirl', 'Classic spinning indicator for quick tasks')
+    run_command("#{ruby_cmd} twirl --command 'sleep 3' --success 'Task completed!' --checkmark")
+    pause_between_demos
+  end
+
+  def demo_styles
+    show_section_header('Style Variations')
+
+    # Ripple styles
+    show_demo_header('Ripple Styles', 'Different visual patterns')
+    show_command_info('Default ripple style')
+    run_command("#{ruby_cmd} ripple --command 'sleep 3' --success 'Default style'")
+    pause_between_demos(2)
+
+    show_command_info('Pulse style')
+    run_command("#{ruby_cmd} ripple --style pulse --command 'sleep 3' --success 'Pulse style'")
+    pause_between_demos
+
+    # Worm styles
+    show_demo_header('Worm Styles', 'Various progress bar animations')
+    show_command_info('Classic worm style')
+    run_command("#{ruby_cmd} worm --length 10 --style classic --command 'sleep 4' --success 'Classic worm'")
+    pause_between_demos(2)
+
+    show_command_info('Emoji worm style')
+    run_command("#{ruby_cmd} worm --length 10 --style emoji --command 'sleep 4' --success 'Emoji worm! 🎉'")
+    pause_between_demos(2)
+
+    show_command_info('Blocks worm style')
+    run_command("#{ruby_cmd} worm --length 10 --style blocks --command 'sleep 4' --success 'Block worm'")
+    pause_between_demos
+
+    # Twirl styles
+    show_demo_header('Twirl Styles', 'Different spinning patterns')
+    show_command_info('Classic spinner')
+    run_command("#{ruby_cmd} twirl --style classic --command 'sleep 3' --success 'Classic spin'")
+    pause_between_demos(2)
+
+    show_command_info('Dots spinner')
+    run_command("#{ruby_cmd} twirl --style dots --command 'sleep 3' --success 'Dotty!'")
+    pause_between_demos(2)
+
+    show_command_info('Arrow spinner')
+    run_command("#{ruby_cmd} twirl --style arrow --command 'sleep 3' --success 'Arrow spin'")
+    pause_between_demos
+  end
+
+  def demo_advanced_options
+    show_section_header('Advanced Options')
+
+    # Error handling
+    show_demo_header('Error Handling', 'Graceful failure with custom messages')
+    show_command_info('Simulating a failed task')
+    run_command("#{ruby_cmd} worm --length 10 --command 'sleep 2 && exit 1' --error 'Something went wrong!' --fail-icon")
+    pause_between_demos
+
+    # Custom colors (if supported)
+    show_demo_header('Success Messages', 'Custom completion messages')
+    show_command_info('Custom success message with checkmark')
+    run_command("#{ruby_cmd} ripple --command 'sleep 3' --success 'Data synchronized successfully' --checkmark")
+    pause_between_demos(2)
+
+    show_command_info('Different success icon')
+    run_command("#{ruby_cmd} twirl --command 'sleep 3' --success 'Backup completed' --icon '✓'")
+    pause_between_demos
+
+    # No completion message
+    show_demo_header('Silent Completion', 'Progress without completion messages')
+    show_command_info('Silent completion (no message)')
+    run_command("#{ruby_cmd} worm --length 10 --command 'sleep 3'")
+    pause_between_demos
+  end
+
+  def demo_new_features
+    show_section_header('New in v1.2.0 - Enhanced Features')
+
+    # Universal --ends flag
+    show_demo_header('Universal --ends Flag', 'Add decorative start/end characters')
+    show_command_info("Ripple with square brackets: --ends '[]'")
+    run_command("#{ruby_cmd} ripple --ends '[]' --command 'sleep 4' --success 'Framed ripple!'")
+    pause_between_demos(2)
+
+    show_command_info("Worm with angle brackets: --ends '<<>>'")
+    run_command("#{ruby_cmd} worm --length 10 --ends '<<>>' --command 'sleep 4' --success 'Angled worm!'")
+    pause_between_demos(2)
+
+    show_command_info("Twirl with emoji decoration: --ends '🎯🎪'")
+    run_command("#{ruby_cmd} twirl --ends '🎯🎪' --command 'sleep 3' --success 'Emoji decorated!'")
+    pause_between_demos
+
+    # Worm direction control
+    show_demo_header('Worm Direction Control', 'Forward-only vs bidirectional movement')
+    show_command_info('Bidirectional worm (default back-and-forth)')
+    run_command("#{ruby_cmd} worm --length 10 --direction bidirectional --command 'sleep 5' --success 'Back and forth!'")
+    pause_between_demos(2)
+
+    show_command_info('Forward-only worm (resets at end)')
+    run_command("#{ruby_cmd} worm --length 10 --direction forward --command 'sleep 5' --success 'Always forward!'")
+    pause_between_demos
+
+    # Custom worm styles
+    show_demo_header('Custom Worm Styles', 'User-defined 3-character patterns')
+    show_command_info('ASCII custom style: --style custom=_-=')
+    run_command("#{ruby_cmd} worm --length 10 --style custom=_-= --command 'sleep 4' --success 'Custom ASCII!'")
+    pause_between_demos(2)
+
+    show_command_info('Unicode custom style: --style custom=▫▪■')
+    run_command("#{ruby_cmd} worm --length 10 --style custom=▫▪■ --command 'sleep 4' --success 'Custom Unicode!'")
+    pause_between_demos(2)
+
+    show_command_info('Emoji custom style: --style custom=🟦🟨🟥')
+    run_command("#{ruby_cmd} worm --length 10 --style custom=🟦🟨🟥 --command 'sleep 4' --success 'Custom emoji!'")
+    pause_between_demos
+
+    # Combining features
+    show_demo_header('Feature Combinations', 'Mixing multiple options together')
+    show_command_info('Custom style + direction + ends: the full package!')
+    # Split the long command string to avoid RuboCop line-length issues while preserving behavior
+    part1 = "#{ruby_cmd} worm --length 10 --style custom=.🟡* --direction forward "
+    part2 = "--ends '【】' --command 'sleep 5' --success 'Ultimate combo!' --checkmark"
+    run_command(part1 + part2)
+    pause_between_demos
+  end
+
+  def show_finale
+    show_section_header('Demo Complete!')
+    show_description('Ruby Progress Gem v1.2.0 - Making terminal progress beautiful! 🚀')
+    puts
+    show_description('Key features demonstrated:')
+    puts "#{@colors[:description]}  • Three animation types: ripple, worm, twirl#{@colors[:reset]}"
+    puts "#{@colors[:description]}  • Multiple built-in styles#{@colors[:reset]}"
+    puts "#{@colors[:description]}  • Universal --ends flag for decoration#{@colors[:reset]}"
+    puts "#{@colors[:description]}  • Worm direction control#{@colors[:reset]}"
+    puts "#{@colors[:description]}  • Custom user-defined styles#{@colors[:reset]}"
+    puts "#{@colors[:description]}  • Success/error handling#{@colors[:reset]}"
+    puts "#{@colors[:description]}  • Multi-byte character support (Unicode/emoji)#{@colors[:reset]}"
+    puts
+    show_description('Install: gem install ruby-progress')
+    show_description('GitHub: https://github.com/ttscoff/ruby-progress')
+    puts
+  end
+
+  # Utility methods
+
+  def ruby_cmd
+    "ruby -I #{@lib_path} #{@gem_path}"
+  end
+
+  def clear_screen
+    system('clear') || system('cls')
+  end
+
+  def show_title
+    puts
+    puts "#{@colors[:header]}#{'=' * 60}#{@colors[:reset]}"
+    puts "#{@colors[:header]}  RUBY PROGRESS GEM - DEMO SCREENCAST#{@colors[:reset]}"
+    puts "#{@colors[:header]}  Version 1.2.0 Feature Demonstration#{@colors[:reset]}"
+    puts "#{@colors[:header]}#{'=' * 60}#{@colors[:reset]}"
+    puts
+  end
+
+  def show_section_header(title)
+    puts
+    puts "#{@colors[:header]}#{'-' * 50}#{@colors[:reset]}"
+    puts "#{@colors[:header]} #{title}#{@colors[:reset]}"
+    puts "#{@colors[:header]}#{'-' * 50}#{@colors[:reset]}"
+    puts
+  end
+
+  def show_demo_header(title, description)
+    puts
+    puts "#{@colors[:header]}### #{title}#{@colors[:reset]}"
+    puts "#{@colors[:description]}#{description}#{@colors[:reset]}"
+    puts
+  end
+
+  def show_command_info(description)
+    puts "#{@colors[:dim]}#{description}#{@colors[:reset]}"
+  end
+
+  def show_description(text)
+    puts "#{@colors[:description]}#{text}#{@colors[:reset]}"
+  end
+
+  def run_command(cmd)
+    puts "#{@colors[:command]}$ #{cmd}#{@colors[:reset]}"
+    puts
+    system(cmd)
+    puts
+  end
+
+  def pause_for_narration(seconds = 2)
+    puts "#{@colors[:dim]}[Pausing #{seconds}s for narration...]#{@colors[:reset]}"
+    sleep(seconds)
+  end
+
+  def pause_between_demos(seconds = 3)
+    puts "#{@colors[:dim]}[Pausing #{seconds}s between demos...]#{@colors[:reset]}"
+    sleep(seconds)
+  end
+end
+
+# Script execution
+if __FILE__ == $PROGRAM_NAME
+  demo = ProgressDemo.new
+
+  puts 'Ruby Progress Gem Demo Screencast'
+  puts '================================='
+  puts
+  puts 'This script will demonstrate various features of the ruby-progress gem.'
+  puts 'Press ENTER to start the demo, or Ctrl+C to exit.'
+  puts
+  print 'Ready? '
+  gets
+
+  begin
+    demo.run
+  rescue Interrupt
+    puts "\n\nDemo interrupted. Thanks for watching!"
+    exit(0)
+  end
+end

data/experimental_terminal.rb

@@ -1,7 +1,11 @@
+# frozen_string_literal: true
+
 # Experimental terminal line protection for daemon mode
 # This demonstrates potential solutions for the daemon output interruption problem
 
 module RubyProgress
+  # SmartTerminal: experimental helpers for safer terminal cursor/line operations
+  # used by daemon-mode demos and scripts where output can interleave with animations.
   module SmartTerminal
     # Save current cursor position
     def self.save_cursor_position
@@ -16,6 +20,8 @@ module RubyProgress
     end
 
     # Get current cursor position (requires terminal interaction)
+    # rubocop:disable Naming/AccessorMethodName
+    # Intentionally named get_cursor_position because it performs an I/O request
     def self.get_cursor_position
       # This is complex and requires reading from stdin
       # which may not work reliably in daemon mode
@@ -24,6 +30,7 @@ module RubyProgress
       # Would need to read response: "\e[{row};{col}R"
       # But this requires terminal input capability
     end
+    # rubocop:enable Naming/AccessorMethodName
 
     # Alternative: Use absolute positioning
     def self.position_cursor_absolute(row, col)

data/lib/ruby-progress/cli/fill_options.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module RubyProgress
+  module FillCLI
+    # Option parsing extracted to reduce module length in FillCLI
+    module Options
+      def self.parse_cli_options
+        options = {
+          style: :blocks,
+          length: 20,
+          speed: :medium,
+          percent: nil,
+          advance: false,
+          complete: false,
+          cancel: false,
+          success_message: nil,
+          error_message: nil,
+          checkmark: false,
+          daemon: false,
+          pid_file: nil,
+          stop: false,
+          status: false,
+          current: false,
+          report: false
+        }
+
+        begin
+          OptionParser.new do |opts|
+            opts.banner = 'Usage: prg fill [options]'
+            opts.separator ''
+            opts.separator 'Progress Bar Options:'
+
+            opts.on('-l', '--length LENGTH', Integer, 'Progress bar length (default: 20)') do |length|
+              options[:length] = length
+            end
+
+            opts.on('-s', '--style STYLE', 'Progress bar style (blocks, classic, dots, etc. or custom=XY)') do |style|
+              options[:style] = style
+            end
+
+            opts.on('--ends CHARS', 'Start/end characters (even number of chars, split in half)') do |chars|
+              options[:ends] = chars
+            end
+
+            opts.separator ''
+            opts.separator 'Progress Control:'
+
+            opts.on('-p', '--percent PERCENT', Float, 'Set progress to percentage (0-100)') do |percent|
+              options[:percent] = percent
+            end
+
+            opts.on('--advance', 'Advance progress by one step') do
+              options[:advance] = true
+            end
+
+            opts.on('--complete', 'Complete the progress bar') do
+              options[:complete] = true
+            end
+
+            opts.on('--cancel', 'Cancel the progress bar') do
+              options[:cancel] = true
+            end
+
+            opts.on('--current', 'Show current progress percentage (0-100 float)') do
+              options[:current] = true
+            end
+
+            opts.on('--report', 'Show detailed progress report') do
+              options[:report] = true
+            end
+
+            opts.separator ''
+            opts.separator 'Auto-advance Mode:'
+
+            opts.on('--speed SPEED', 'Auto-advance speed (fast/medium/slow or numeric)') do |speed|
+              options[:speed] = case speed.downcase
+                                when /^f/ then :fast
+                                when /^m/ then :medium
+                                when /^s/ then :slow
+                                else speed.to_f.positive? ? speed.to_f : :medium
+                                end
+            end
+
+            opts.separator ''
+            opts.separator 'Messages:'
+
+            opts.on('--success MESSAGE', 'Success message to display on completion') do |msg|
+              options[:success_message] = msg
+            end
+
+            opts.on('--error MESSAGE', 'Error message to display on cancellation') do |msg|
+              options[:error_message] = msg
+            end
+
+            opts.on('--checkmark', 'Show checkmarks (✅ success, 🛑 failure)') do
+              options[:checkmark] = true
+            end
+
+            opts.separator ''
+            opts.separator 'Daemon Mode:'
+
+            opts.on('--daemon', 'Run in background daemon mode') do
+              options[:daemon] = true
+            end
+
+            opts.on('--pid-file FILE', 'PID file location (default: /tmp/ruby-progress/fill.pid)') do |file|
+              options[:pid_file] = file
+            end
+
+            opts.on('--stop', 'Stop daemon') do
+              options[:stop] = true
+            end
+
+            opts.on('--status', 'Show daemon status') do
+              options[:status] = true
+            end
+
+            opts.separator ''
+            opts.separator 'General:'
+
+            opts.on('--show-styles', 'Show available fill styles with visual previews') do
+              options[:show_styles] = true
+            end
+
+            opts.on('-v', '--version', 'Show version') do
+              options[:version] = true
+            end
+
+            opts.on('-h', '--help', 'Show this help') do
+              options[:help] = true
+            end
+          end.parse!
+        rescue OptionParser::InvalidOption => e
+          warn "Invalid option: #{e.args.first}"
+          warn ''
+          warn 'Usage: prg fill [options]'
+          warn "Run 'prg fill --help' for more information."
+          exit 1
+        end
+
+        options
+      end
+
+      def self.help_text
+        opts = OptionParser.new
+
+        opts.banner = 'Usage: prg fill [options]'
+        opts.separator ''
+        opts.separator 'Progress Bar Options:'
+
+        opts.on('-l', '--length LENGTH', Integer, 'Progress bar length (default: 20)')
+        opts.on('-s', '--style STYLE', 'Progress bar style (blocks, classic, dots, etc. or custom=XY)')
+        opts.on('--ends CHARS', 'Start/end characters (even number of chars, split in half)')
+
+        opts.separator ''
+        opts.separator 'Progress Control:'
+        opts.on('-p', '--percent PERCENT', Float, 'Set progress to percentage (0-100)')
+        opts.on('--advance', 'Advance progress by one step')
+        opts.on('--complete', 'Complete the progress bar')
+        opts.on('--cancel', 'Cancel the progress bar')
+        opts.on('--current', 'Show current progress percentage (0-100 float)')
+        opts.on('--report', 'Show detailed progress report')
+
+        opts.separator ''
+        opts.separator 'Auto-advance Mode:'
+        opts.on('--speed SPEED', 'Auto-advance speed (fast/medium/slow or numeric)')
+
+        opts.separator ''
+        opts.separator 'Messages:'
+        opts.on('--success MESSAGE', 'Success message to display on completion')
+        opts.on('--error MESSAGE', 'Error message to display on cancellation')
+        opts.on('--checkmark', 'Show checkmarks (✅ success, 🛑 failure)')
+
+        opts.separator ''
+        opts.separator 'Daemon Mode:'
+        opts.on('--daemon', 'Run in background daemon mode')
+        opts.on('--pid-file FILE', 'PID file location (default: /tmp/ruby-progress/fill.pid)')
+        opts.on('--stop', 'Stop daemon')
+        opts.on('--status', 'Show daemon status')
+
+        opts.separator ''
+        opts.separator 'General:'
+        opts.on('--show-styles', 'Show available fill styles with visual previews')
+        opts.on('-v', '--version', 'Show version')
+        opts.on('-h', '--help', 'Show this help')
+
+        opts.to_s
+      end
+    end
+  end
+end

data/lib/ruby-progress/cli/ripple_cli.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require_relative 'ripple_options'
+
+# Enhanced Ripple CLI with unified flags (extracted from bin/prg)
+module RippleCLI
+  def self.run
+    trap('INT') do
+      RubyProgress::Utils.show_cursor
+      exit
+    end
+
+    options = RippleCLI::Options.parse_cli_options
+
+    # Daemon/status/stop handling (process these without requiring text)
+    if options[:status]
+      pid_file = options[:pid_file] || RubyProgress::Daemon.default_pid_file
+      RubyProgress::Daemon.show_status(pid_file)
+      exit
+    elsif options[:stop]
+      pid_file = options[:pid_file] || RubyProgress::Daemon.default_pid_file
+      stop_msg = options[:stop_error] || options[:stop_success]
+      is_error = !options[:stop_error].nil?
+      RubyProgress::Daemon.stop_daemon_by_pid_file(
+        pid_file,
+        message: stop_msg,
+        checkmark: options[:stop_checkmark],
+        error: is_error
+      )
+      exit
+    elsif options[:daemon]
+      # For daemon mode, detach so shell has no tracked job
+      PrgCLI.daemonize
+
+      # For daemon mode, default message if none provided
+      text = options[:message] || ARGV.join(' ')
+      text = 'Processing' if text.nil? || text.empty?
+      run_daemon_mode(text, options)
+    else
+      # Non-daemon path requires text
+      text = options[:message] || ARGV.join(' ')
+      if text.empty?
+        puts 'Error: Please provide text to animate via argument or --message flag'
+        puts "Example: prg ripple 'Loading...' or prg ripple --message 'Loading...'"
+        exit 1
+      end
+
+      # Convert styles array to individual flags for backward compatibility
+      options[:rainbow] = options[:styles].include?(:rainbow)
+      options[:inverse] = options[:styles].include?(:inverse)
+      options[:caps] = options[:styles].include?(:caps)
+
+      if options[:command]
+        run_with_command(text, options)
+      else
+        run_indefinitely(text, options)
+      end
+    end
+  end
+
+  def self.run_with_command(text, options)
+    captured_output = nil
+    RubyProgress::Ripple.progress(text, options) do
+      captured_output = `#{options[:command]} 2>&1`
+    end
+
+    success = $CHILD_STATUS.success?
+
+    puts captured_output if options[:output] == :stdout
+    if options[:success_message] || options[:complete_checkmark]
+      message = success ? options[:success_message] : options[:fail_message] || options[:success_message]
+      RubyProgress::Ripple.complete(text, message, options[:complete_checkmark], success)
+    end
+    exit success ? 0 : 1
+  end
+
+  def self.run_indefinitely(text, options)
+    rippler = RubyProgress::Ripple.new(text, options)
+    RubyProgress::Utils.hide_cursor
+    begin
+      loop { rippler.advance }
+    ensure
+      RubyProgress::Utils.show_cursor
+      RubyProgress::Ripple.complete(text, options[:success_message], options[:complete_checkmark], true)
+    end
+  end
+
+  def self.run_daemon_mode(text, options)
+    pid_file = options[:pid_file] || RubyProgress::Daemon.default_pid_file
+    FileUtils.mkdir_p(File.dirname(pid_file))
+    File.write(pid_file, Process.pid.to_s)
+
+    begin
+      # For Ripple, re-use the existing animation loop via a simple loop
+      RubyProgress::Utils.hide_cursor
+      rippler = RubyProgress::Ripple.new(text, options)
+      stop_requested = false
+
+      Signal.trap('INT') { stop_requested = true }
+      Signal.trap('USR1') { stop_requested = true }
+      Signal.trap('TERM') { stop_requested = true }
+      Signal.trap('HUP')  { stop_requested = true }
+
+      rippler.advance until stop_requested
+    ensure
+      RubyProgress::Utils.clear_line
+      RubyProgress::Utils.show_cursor
+
+      # If a control message file exists, output its message with optional checkmark
+      cmf = RubyProgress::Daemon.control_message_file(pid_file)
+      if File.exist?(cmf)
+        begin
+          data = JSON.parse(File.read(cmf))
+          message = data['message']
+          check = if data.key?('checkmark')
+                    data['checkmark'] ? true : false
+                  else
+                    false
+                  end
+          success_val = if data.key?('success')
+                          data['success'] ? true : false
+                        else
+                          true
+                        end
+          if message
+            RubyProgress::Utils.display_completion(
+              message,
+              success: success_val,
+              show_checkmark: check,
+              output_stream: :stdout
+            )
+          end
+        rescue StandardError
+          # ignore
+        ensure
+          begin
+            File.delete(cmf)
+          rescue StandardError
+            nil
+          end
+        end
+      end
+
+      FileUtils.rm_f(pid_file)
+    end
+  end
+
+  # Options parsing moved to ripple_options.rb
+end