ruby-progress 1.0.1

data/lib/ruby-progress/ripple.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+module RubyProgress
+  # Color definitions for terminal output
+  COLORS = {
+    'red' => "\e[31m",
+    'green' => "\e[32m",
+    'yellow' => "\e[33m",
+    'blue' => "\e[34m",
+    'magenta' => "\e[35m",
+    'cyan' => "\e[36m",
+    'white' => "\e[37m",
+    'dark_red' => "\e[31;1m",
+    'dark_green' => "\e[32;1m",
+    'dark_yellow' => "\e[33;1m",
+    'dark_blue' => "\e[34;1m",
+    'dark_magenta' => "\e[35;1m",
+    'dark_cyan' => "\e[36;1m",
+    'dark_white' => "\e[37;1m",
+    'light_red' => "\e[31;2m",
+    'light_green' => "\e[32;2m",
+    'light_yellow' => "\e[33;2m",
+    'light_blue' => "\e[34;2m",
+    'light_magenta' => "\e[35;2m",
+    'light_cyan' => "\e[36;2m",
+    'light_white' => "\e[37;2m",
+    'reset' => "\e[0m"
+  }.freeze
+
+  # Spinner indicator definitions
+  INDICATORS = {
+    arc: %w[◜ ◠ ◝ ◞ ◡ ◟],
+    arrow: %w[← ↖ ↑ ↗ → ↘ ↓ ↙],
+    arrow_pulse: [
+      '▹▹▹▹▹',
+      '▸▹▹▹▹',
+      '▹▸▹▹▹',
+      '▹▹▸▹▹',
+      '▹▹▹▸▹',
+      '▹▹▹▹▸'
+    ],
+    balloon: %w[. o O ° O o .],
+    block_1: %w[▖▖▖ ▘▖▖ ▖▘▖ ▖▖▘],
+    block_2: %w[▌ ▀ ▐ ▄],
+    bounce: [
+      '[    ]',
+      '[=   ]',
+      '[==  ]',
+      '[=== ]',
+      '[====]'
+    ],
+    circle: %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[⠁ ⠂ ⠄ ⡀ ⢀ ⠠ ⠐ ⠈],
+    ellipsis: ['.   ', '..  ', '... ', '....'],
+    lighthouse: ['∙∙∙', '●∙∙', '∙●∙', '∙∙●'],
+    o: %w[Ooo oOo ooO],
+    pipe: %w[┤ ┘ ┴ └ ├ ┌ ┬ ┐],
+    pulse: %w[⎺ ⎻ ⎼ ⎽ ⎼ ⎻],
+    pulse_2: %w[▁ ▃ ▅ ▆ ▇ █ ▇ ▆ ▅ ▃],
+    pulse_3: %w[▉ ▊ ▋ ▌ ▍ ▎ ▏ ▎ ▍ ▌ ▋ ▊ ▉],
+    pulse_4: %w[- = ≡ = -],
+    push: [
+      '[>    ]',
+      '[=>   ]',
+      '[==>  ]',
+      '[===> ]',
+      '[====>]'
+    ],
+    spin: %w[◴ ◷ ◶ ◵],
+    spin_2: %w[◐ ◓ ◑ ◒],
+    spin_3: %w[◰ ◳ ◲ ◱],
+    toggle: %w[■ □ ▪ ▫],
+    triangle: %w[◢ ◣ ◤ ◥]
+  }.freeze
+
+  # String extensions for color support
+  module StringExtensions
+    COLORS.each do |color_name, color_code|
+      define_method(color_name) do
+        "#{color_code}#{self}#{COLORS['reset']}"
+      end
+    end
+
+    def rainbow(index = 0)
+      chars = split('')
+      colored_chars = chars.map.with_index do |char, idx|
+        color = COLORS.values[(idx + index) % COLORS.size]
+        "#{color}#{char}#{COLORS['reset']}"
+      end
+      colored_chars.join
+    end
+
+    def normalize_type
+      spinner_type = :classic
+      INDICATORS.each do |spinner, _v|
+        spinner_type = spinner if spinner =~ /^#{split('').join('.*?')}/i
+      end
+      spinner_type
+    end
+  end
+
+  # Text ripple animation class
+  class Ripple
+    attr_accessor :index, :string, :speed, :format, :inverse, :rainbow, :spinner, :spinner_position, :caps
+
+    def initialize(string, options = {})
+      defaults = {
+        speed: :medium,
+        format: :bidirectional,
+        rainbow: false,
+        spinner: false,
+        spinner_position: false,
+        caps: false,
+        inverse: false,
+        output: :error
+      }
+      @options = defaults.merge(options)
+      @string = string
+      @index = 0
+      @direction = :forward
+      @rainbow = @options[:rainbow]
+      @spinner = @options[:spinner]
+      @spinner_position = @options[:spinner_position]
+      @caps = @options[:caps]
+      @inverse = @options[:inverse]
+    end
+
+    def printout
+      letters = @string.dup.split('')
+      i = @index
+      if @spinner
+        case @spinner_position
+        when :before
+          pre = "#{INDICATORS[@spinner][i]} "
+          post = @string
+        else
+          pre = "#{@string} "
+          post = INDICATORS[@spinner][i]
+        end
+      elsif @caps
+        pre = letters.slice!(0, i).join
+        char = letters.slice!(0, 2).join
+        post = letters.slice!(0, letters.length).join
+        pre = @inverse ? pre.upcase : pre.downcase
+        char = @inverse ? char.downcase : char.upcase
+        post = @inverse ? post.upcase : post.downcase
+      elsif @inverse
+        pre = letters.slice!(0, i).join
+        pre = @rainbow ? pre.rainbow : pre.extend(StringExtensions).light_white
+        char = letters.slice!(0, 2).join
+        char = char.extend(StringExtensions).dark_white
+        post = letters.slice!(0, letters.length).join
+        post = @rainbow ? post.rainbow : post.extend(StringExtensions).light_white
+      else
+        pre = letters.slice!(0, i).join.extend(StringExtensions).dark_white
+        char = letters.slice!(0, 2).join
+        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"
+    end
+
+    # Hide or show the cursor (delegated to Utils)
+    def self.hide_cursor
+      RubyProgress::Utils.hide_cursor
+    end
+
+    def self.show_cursor
+      RubyProgress::Utils.show_cursor
+    end
+
+    def self.complete(string, message, checkmark, success)
+      display_message = message || (checkmark ? string : nil)
+      return unless display_message
+
+      RubyProgress::Utils.display_completion(
+        display_message,
+        success: success,
+        show_checkmark: checkmark,
+        output_stream: :warn
+      )
+    end
+
+    def advance
+      max = @spinner ? (INDICATORS[@spinner].count - 1) : (@string.length - 1)
+      advance = true
+
+      if @index == max && @options[:format] != :forward_only
+        @direction = :backward
+      elsif @index == max && @options[:format] == :forward_only
+        @index = 0
+        advance = false
+      elsif @index == 0
+        @direction = :forward
+      end
+
+      if advance
+        @index = @direction == :backward ? @index - 1 : @index + 1
+      end
+
+      printout
+
+      case @options[:speed]
+      when :fast
+        sleep 0.05
+      when :medium
+        sleep 0.1
+      else
+        sleep 0.2
+      end
+    end
+
+    def self.progress(string, options = {})
+      Signal.trap('INT') do
+        Thread.current.kill
+        nil
+      end
+      defaults = { speed: :medium,
+                   format: :bidirectional,
+                   rainbow: false,
+                   inverse: false,
+                   output: :error }
+      options = defaults.merge(options)
+
+      rippler = new(string, options)
+      Ripple.hide_cursor
+      begin
+        thread = Thread.new do
+          rippler.advance while true
+        end
+        result = yield if block_given?
+        thread.kill
+
+        if @options[:output] == :error
+          $?.exitstatus.zero?
+        elsif @options[:output] == :stdout
+          result
+        else
+          nil
+        end
+      rescue StandardError
+        thread&.kill
+        nil
+      ensure
+        Ripple.show_cursor
+      end
+    end
+  end
+end
+
+# Extend String class with color methods
+class String
+  include RubyProgress::StringExtensions
+end

data/lib/ruby-progress/utils.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module RubyProgress
+  # Universal terminal utilities shared between progress indicators
+  module Utils
+    # Terminal cursor control
+    def self.hide_cursor
+      $stderr.print "\e[?25l"
+    end
+
+    def self.show_cursor
+      $stderr.print "\e[?25h"
+    end
+
+    def self.clear_line
+      print "\r\e[K"
+    end
+
+    # Universal completion message display
+    # @param message [String] The message to display
+    # @param success [Boolean] Whether this represents success or failure
+    # @param show_checkmark [Boolean] Whether to show checkmark/X symbols
+    # @param output_stream [Symbol] Where to output (:stdout, :stderr, :warn)
+    def self.display_completion(message, success: true, show_checkmark: false, output_stream: :warn)
+      return unless message
+
+      mark = ''
+      if show_checkmark
+        mark = success ? '✅ ' : '🛑 '
+      end
+
+      formatted_message = "#{mark}#{message}"
+
+      case output_stream
+      when :stdout
+        puts formatted_message
+      when :stderr
+        $stderr.puts formatted_message
+      when :warn
+        warn "\e[2K#{formatted_message}"
+      else
+        warn "\e[2K#{formatted_message}"
+      end
+    end
+
+    # 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
+      display_completion(message, success: success, show_checkmark: show_checkmark, output_stream: output_stream)
+    end
+  end
+end

data/lib/ruby-progress/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RubyProgress
+  VERSION = '1.0.1'
+end

data/lib/ruby-progress/worm.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require 'open3'
+
+module RubyProgress
+  # Animated progress indicator with ripple effect using Unicode combining characters
+  class Worm
+    # Ripple effect styles
+    RIPPLE_STYLES = {
+      'circles' => {
+        baseline: '·',  # middle dot
+        midline: '●',   # black circle
+        peak: '⬤'      # large circle
+      },
+      'blocks' => {
+        baseline: '▁',  # lower eighth block
+        midline: '▄',   # lower half block
+        peak: '█'       # full block
+      },
+      'geometric' => {
+        baseline: '▪',  # small black square
+        midline: '▫',   # small white square
+        peak: '■'       # large black square
+      }
+    }.freeze
+
+    # Speed mappings
+    SPEED_MAP = {
+      'slow' => 0.5,
+      'medium' => 0.2,
+      'fast' => 0.1
+    }.freeze
+
+    def initialize(options = {})
+      @length = options[:length] || 3
+      @message = options[:message] || 'Processing'
+      @speed = parse_speed(options[:speed] || 'medium')
+      @style = parse_style(options[:style] || 'circles')
+      @command = options[:command]
+      @success_text = options[:success]
+      @error_text = options[:error]
+      @show_checkmark = options[:checkmark] || false
+      @output_stdout = options[:stdout] || false
+      @running = false
+    end
+
+    def animate(message: nil, success: nil, error: nil, &block)
+      @message = message if message
+      @success_text = success if success
+      @error_text = error if error
+      @running = true
+
+      # Set up interrupt handler to ensure cursor is restored
+      original_int_handler = Signal.trap('INT') do
+        @running = false
+        RubyProgress::Utils.clear_line
+        RubyProgress::Utils.show_cursor
+        puts "\nInterrupted!"
+        exit 130
+      end
+
+      # Hide cursor
+      RubyProgress::Utils.hide_cursor
+
+      animation_thread = Thread.new { animation_loop }
+
+      begin
+        if block_given?
+          result = yield
+          @running = false
+          animation_thread.join
+          display_completion_message(@success_text || 'Done!', true)
+          result
+        else
+          animation_thread.join
+        end
+      rescue StandardError => e
+        @running = false
+        animation_thread.join
+        display_completion_message(@error_text || "Error: #{e.message}", false)
+        nil # Return nil instead of re-raising when used as a progress indicator
+      ensure
+        # Always restore cursor and signal handler
+        RubyProgress::Utils.show_cursor
+        Signal.trap('INT', original_int_handler) if original_int_handler
+      end
+    end
+
+    def run_with_command
+      return unless @command
+
+      exit_code = 0
+      stdout_content = nil
+
+      begin
+        stdout_content = animate do
+          # Use popen3 instead of capture3 for better signal handling
+          Open3.popen3(@command) do |stdin, stdout, stderr, wait_thr|
+            stdin.close
+            captured_stdout = stdout.read
+            stderr_content = stderr.read
+            exit_code = wait_thr.value.exitstatus
+
+            unless wait_thr.value.success?
+              error_msg = @error_text || "Command failed with exit code #{exit_code}"
+              error_msg += ": #{stderr_content.strip}" if stderr_content && !stderr_content.empty?
+              raise StandardError, error_msg
+            end
+            captured_stdout
+          end
+        end
+
+        # Output to stdout if --stdout flag is set
+        puts stdout_content if @output_stdout && stdout_content
+
+      rescue StandardError => e
+        # animate method handles error display, just exit with proper code
+        exit exit_code.nonzero? || 1
+      rescue Interrupt
+        puts "\nInterrupted!"
+        exit 130
+      end
+    end
+
+    def run_indefinitely
+      # Set up interrupt handler to ensure cursor is restored
+      original_int_handler = Signal.trap('INT') do
+        @running = false
+        RubyProgress::Utils.clear_line
+        RubyProgress::Utils.show_cursor
+        puts "\nInterrupted!"
+        exit 130
+      end
+
+      @running = true
+      RubyProgress::Utils.hide_cursor
+
+      begin
+        animation_loop
+      ensure
+        RubyProgress::Utils.show_cursor
+        Signal.trap('INT', original_int_handler) if original_int_handler
+      end
+    end
+
+    def stop
+      @running = false
+    end
+
+    private
+
+    def display_completion_message(message, success)
+      return unless message
+
+      mark = ''
+      if @show_checkmark
+        mark = success ? '✅ ' : '🛑 '
+      end
+
+      puts "#{mark}#{message}"
+    end
+
+    def parse_speed(speed_input)
+      case speed_input
+      when String
+        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)
+        end
+
+        # Check for abbreviated forms
+        speed_lower = speed_input.downcase
+        if speed_lower.start_with?('f')
+          SPEED_MAP['fast']
+        elsif speed_lower.start_with?('m')
+          SPEED_MAP['medium']
+        elsif speed_lower.start_with?('s')
+          SPEED_MAP['slow']
+        else
+          SPEED_MAP['medium']
+        end
+      when Numeric
+        speed_num = speed_input.to_i
+        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
+      end
+    end
+
+    def animation_loop
+      position = 0
+      direction = 1
+
+      while @running
+        print "\r#{@message}#{generate_dots(position, direction)}"
+        $stdout.flush
+
+        sleep @speed
+
+        position += direction
+        if position >= @length - 1
+          direction = -1
+        elsif position <= 0
+          direction = 1
+        end
+      end
+    end
+
+    def generate_dots(ripple_position, direction)
+      dots = Array.new(@length) { @style[:baseline] }
+
+      # Apply ripple effect
+      (0...@length).each do |i|
+        distance = (i - ripple_position).abs
+        case distance
+        when 0
+          dots[i] = @style[:peak]
+        when 1
+          # When moving left, midline appears to the right of peak
+          # When moving right, midline appears to the left of peak
+          if direction == -1 # moving left
+            dots[i] = @style[:midline] if i > ripple_position
+          else # moving right
+            dots[i] = @style[:midline] if i < ripple_position
+          end
+        else
+          dots[i] = @style[:baseline]
+        end
+      end
+
+      dots.join
+    end
+
+    # Terminal utilities moved to RubyProgress::Utils
+  end
+end

data/lib/ruby-progress.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'ruby-progress/version'
+require_relative 'ruby-progress/utils'
+require_relative 'ruby-progress/ripple'
+require_relative 'ruby-progress/worm'
+
+module RubyProgress
+  # Main module for Ruby Progress indicators
+  # Contains both Ripple and Worm classes for different types of progress animations
+end

data/ruby-progress.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'lib/ruby-progress/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'ruby-progress'
+  spec.version = RubyProgress::VERSION
+  spec.authors = ['Brett Terpstra']
+  spec.email = ['me@brettterpstra.com']
+
+  spec.summary = 'Animated terminal progress indicators'
+  spec.description = 'Two different animated progress indicators for Ruby: Ripple (text ripple effects) and Worm (Unicode wave animations)'
+  spec.homepage = 'https://github.com/ttscoff/ruby-progress'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 2.5.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = 'bin'
+  spec.executables = ['prg', 'ripple', 'worm']
+  spec.require_paths = ['lib']
+
+  # Runtime dependencies
+  # None required - uses only standard library
+
+  # Development dependencies
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 1.21'
+  spec.add_development_dependency 'simplecov', '~> 0.21'
+end

data/test_worm_flags.rb

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+
+# Test script to demonstrate the new --stdout and --checkmark flags in worm.rb
+
+puts "Testing worm.rb with new flags:"
+puts
+
+puts "1. Testing --checkmark flag with success:"
+system("ruby worm.rb --command 'echo Hello World' --message 'Running test' --success 'Test passed!' --checkmark")
+puts
+
+puts "2. Testing --stdout flag:"
+system("ruby worm.rb --command 'echo This output will be displayed' --message 'Capturing output' --stdout")
+puts
+
+puts "3. Testing both --checkmark and --stdout together:"
+system("ruby worm.rb --command 'echo Combined test output' --message 'Testing both flags' --success 'Both flags work!' --checkmark --stdout")
+puts
+
+puts "4. Testing --checkmark with failure:"
+system("ruby worm.rb --command 'exit 1' --message 'Testing failure' --error 'Test failed!' --checkmark")
+puts
+
+puts "All tests completed!"