ruby-progress 1.1.8 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b9c54f1a667742fffe32c16ac5d84b26e2e0c9c4ed34492913f61ffb084a44d
-  data.tar.gz: fbf1a1dc3293b68e3ac63e0cc1084bc27a5a99241d56df8843a87ce5f79c59db
+  metadata.gz: 35418d5ca6c2be425e6727b2480ce99da3baaa768991fc1a1e92bbcb15b54d37
+  data.tar.gz: 439632bfced82834cdd7157e33a84c187821436fa6ca3f1854627ab092c682bc
 SHA512:
-  metadata.gz: 52b88f06001f49dac80b6aa735b252ba0760fc123a7b28a5609ef7f7c570f0db43e07a3a104efb4f3a513befa3b7e3113b556847a4b095a4521586587d3d87c7
-  data.tar.gz: 90188577fa0935924cc01ba3e1520a3625fab2c80975cf105413f631e8e5ef8623a160aadd5fb6d03194f88c884be6b4599269296163b4ba4ca66edd0f585d9f
+  metadata.gz: 3def99d8f6d1bde28c3fc6a273fe0d8be65db3aabbd440a9bef8b165bd606e09872f8f216a73b186477cd4ef84f06bcfd728cd3a96eae23fdfc2114926827082
+  data.tar.gz: dda2ef12f24c66481e3280e23ba34932d7691edbdfa5ae503e3c1071a917158f126862df5b4b67ccb45b066523e0010b31298a4c6009dd296557cae190016367

data/CHANGELOG.md

@@ -5,6 +5,73 @@ All notable changes to this project will be documented in this file.
 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).
 
+## [1.2.0] - 2025-10-11
+
+### Added
+
+- **--ends flag for all commands**: New universal option to add start/end characters around animations
+  - Accepts even-length strings split in half for start and end characters
+  - Works across all three commands: ripple, worm, and twirl
+  - Examples: `--ends "[]"` → `[animation]`, `--ends "<<>>"` → `<<animation>>`
+  - Multi-byte character support for emojis: `--ends "🎯🎪"` → `🎯animation🎪`
+  - Graceful fallback for invalid input (odd-length strings)
+
+- **Comprehensive test coverage for new features**: Added extensive test suites
+  - Direction control tests: Forward-only vs bidirectional animation behavior
+  - Custom style tests: ASCII, Unicode, emoji, and mixed character pattern validation
+  - CLI integration tests: End-to-end testing for all new command-line options
+  - Ends functionality tests: Multi-byte character handling, error cases, help documentation
+  - Total: 58 new test examples covering all edge cases
+
+- **Worm direction control**: Fine-grained animation movement control
+  - `--direction forward` (or `-d f`): Animation moves only forward, resets at end
+  - `--direction bidirectional` (or `-d b`): Default back-and-forth movement
+  - Compatible with all worm styles including custom patterns
+
+- **Worm custom styles**: User-defined 3-character animation patterns
+  - Format: `--style custom=abc` where `abc` defines baseline, midline, peak characters
+  - ASCII support: `--style custom=_-=` → `___-=___`
+  - Unicode support: `--style custom=▫▪■` → geometric patterns
+  - Emoji support: `--style custom=🟦🟨🟥` → colorful animations
+  - Mixed characters: `--style custom=.🟡*` → combined ASCII and emoji
+  - Proper multi-byte character counting for accurate 3-character validation
+
+### Enhanced
+
+- **Centralized utility functions**: Moved common functionality to `RubyProgress::Utils`
+  - `Utils.parse_ends()`: Universal start/end character parsing
+  - Eliminates code duplication across animation classes
+  - Consistent behavior and error handling
+
+- **Documentation improvements**: Updated README with comprehensive examples
+  - New common options section highlighting universal flags
+  - Detailed --ends usage examples with various character patterns
+  - Enhanced help output for all commands
+
+### Technical
+
+- **Version management**: Bumped all component versions to reflect new features
+  - Main version: 1.1.9 → 1.2.0 (new feature addition)
+  - Worm version: 1.0.4 → 1.1.0 (direction control + custom styles)
+  - Ripple version: 1.0.5 → 1.1.0 (ends support)
+  - Twirl version: 1.0.1 → 1.1.0 (ends support)
+
+## [1.1.9] - 2025-10-10
+
+### Fixed
+
+- **Worm animation line clearing**: Resolved issue where completion messages appeared alongside animation characters
+  - Fixed stream mismatch where animations used stderr but completion messages used stdout
+  - Implemented atomic operation combining line clearing and message output on stderr
+  - Ensured clean line clearing for all scenarios (success, error, no completion message)
+  - Updated tests to match new stderr-based completion message output
+  - Clean output format: animation disappears completely before completion message appears
+
+### Technical
+
+- **Stream consistency**: All worm animation output (including completion messages) now uses stderr consistently
+- **Enhanced completion message display**: Single atomic stderr operation prevents race conditions between line clearing and message display
+
 ## [1.1.8] - 2025-10-10
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby-progress (1.1.8)
+    ruby-progress (1.2.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -29,6 +29,14 @@ prg twirl --message "Working..." --style dots --speed fast
 prg worm --command "sleep 5" --success "Completed!" --error "Failed!" --checkmark
 prg ripple "Building..." --command "make build" --success "Build complete!" --stdout
 prg twirl --command "npm install" --message "Installing packages" --style arc
+
+# With start/end character decoration using --ends
+prg ripple "Loading data" --ends "[]" --style rainbow
+prg worm --message "Processing" --ends "()" --style blocks
+prg twirl --message "Building" --ends "<<>>" --style dots
+
+# Complex --ends patterns with emojis
+prg worm --message "Magic" --ends "🎯🎪" --style "custom=🟦🟨🟥"
 ```
 
 ### Global Options
@@ -38,7 +46,7 @@ prg twirl --command "npm install" --message "Installing packages" --style arc
 - `prg --list-styles` - Show all available styles for all subcommands
 - `prg <subcommand> --help` - Show specific subcommand help
 
-### Common Options (available for both subcommands)
+### Common Options (available for all subcommands)
 
 - `--speed SPEED` - Animation speed (fast/medium/slow or f/m/s)
 - `--message MESSAGE` - Message to display
@@ -47,6 +55,7 @@ prg twirl --command "npm install" --message "Installing packages" --style arc
 - `--error MESSAGE` - Error message on failure
 - `--checkmark` - Show checkmarks (✅ success, 🛑 failure)
 - `--stdout` - Output command results to STDOUT
+- `--ends CHARS` - Start/end characters (even number of chars, split in half)
 
 ### Daemon Mode (Background Progress)
 
@@ -304,25 +313,39 @@ Worm is a clean, Unicode-based progress indicator that creates a ripple effect u
 
 ```bash
 # Run indefinitely without a command (like ripple)
-./worm.rb --message "Loading..." --speed fast --style circles
+prg worm --message "Loading..." --speed fast --style circles
 
 # Run a command with progress animation
-./worm.rb --command "sleep 5" --message "Installing" --success "Done!"
+prg worm --command "sleep 5" --message "Installing" --success "Done!"
 
 # Customize the animation
-./worm.rb --command "make build" --speed fast --length 5 --style blocks
+prg worm --command "make build" --speed fast --length 5 --style blocks
 
 # With custom error handling
-./worm.rb --command "risky_operation" --error "Operation failed" --style geometric
+prg worm --command "risky_operation" --error "Operation failed" --style geometric
 
 # With checkmarks for visual feedback
-./worm.rb --command "npm install" --success "Installation complete!" --checkmark
+prg worm --command "npm install" --success "Installation complete!" --checkmark
+
+# Control animation direction (forward-only or bidirectional)
+prg worm --message "Processing" --direction forward --style circles
+prg worm --command "sleep 3" --direction bidirectional --style blocks
+
+# Create custom animations with 3-character patterns
+prg worm --message "Custom style" --style "custom=_-=" --command "sleep 2"
+prg worm --message "Emoji worm!" --style "custom=🟦🟨🟥" --success "Complete!"
+prg worm --message "Mixed chars" --style "custom=.🟡*" --direction forward
+
+# Add start/end characters around the animation
+prg worm --message "Bracketed" --ends "[]" --style circles
+prg worm --message "Parentheses" --ends "()" --style blocks --direction forward
+prg worm --message "Emoji ends" --ends "🎯🎪" --style "custom=🟦🟨🟥"
 
 # Capture and display command output
-./worm.rb --command "git status" --message "Checking status" --stdout
+prg worm --command "git status" --message "Checking status" --stdout
 
 # Combine checkmarks and stdout output
-./worm.rb --command "echo 'Build output'" --success "Build complete!" --checkmark --stdout
+prg worm --command "echo 'Build output'" --success "Build complete!" --checkmark --stdout
 ```
 
 #### Daemon mode (background indicator)
@@ -351,15 +374,25 @@ Note: You don’t need `&` when starting the daemon. The command detaches itself
 
 #### Worm Command Line Options
 
-| Option                  | Description                                         |
-| ----------------------- | --------------------------------------------------- |
-| `-s, --speed SPEED`     | Animation speed (1-10, fast/medium/slow, or f/m/s)  |
-| `-l, --length LENGTH`   | Number of dots to display                           |
-| `-m, --message MESSAGE` | Message to display before animation                 |
-| `--style STYLE`         | Animation style (blocks/geometric/circles or b/g/c) |
-| `-c, --command COMMAND` | Command to run (required)                           |
-| `--success TEXT`        | Text to display on successful completion            |
-| `--error TEXT`          | Text to display on error                            |
+| Option                  | Description                                                |
+| ----------------------- | ---------------------------------------------------------- |
+| `-s, --speed SPEED`     | Animation speed (1-10, fast/medium/slow, or f/m/s)         |
+| `-l, --length LENGTH`   | Number of dots to display                                  |
+| `-m, --message MESSAGE` | Message to display before animation                        |
+| `--style STYLE`         | Animation style (circles/blocks/geometric or custom=XXX)   |
+| `--direction DIR`       | Animation direction (forward/bidirectional or f/b)         |
+| `--ends CHARS`          | Start/end characters (even number of chars, split in half) |
+| `-c, --command COMMAND` | Command to run (optional)                                  |
+| `--success TEXT`        | Text to display on successful completion                   |
+| `--error TEXT`          | Text to display on error                                   |
+| `--checkmark`           | Show checkmarks (✅ for success, 🛑 for failure)             |
+| `--stdout`              | Output captured command result to STDOUT                   |
+| `--daemon`              | Run in background daemon mode                              |
+| `--daemon-as NAME`      | Run in daemon mode with custom name                        |
+| `--stop`                | Stop a running daemon                                      |
+| `--stop-id NAME`        | Stop daemon by name (implies --stop)                       |
+| `--status`              | Check daemon status                                        |
+| `--status-id NAME`      | Check daemon status by name                                |
 
 ### Worm Library Usage
 
@@ -371,7 +404,8 @@ worm = RubyProgress::Worm.new(
   length: 4,
   message: "Processing",
   speed: 'fast',
-  style: 'circles'
+  style: 'circles',
+  direction: :bidirectional
 )
 
 result = worm.animate(
@@ -382,6 +416,15 @@ result = worm.animate(
   some_long_running_task
 end
 
+# With custom style and forward direction
+worm = RubyProgress::Worm.new(
+  message: "Custom animation",
+  style: 'custom=🔴🟡🟢',
+  direction: :forward
+)
+
+result = worm.animate { sleep 3 }
+
 # Or run with a command
 worm = RubyProgress::Worm.new(command: "bundle install")
 worm.run_with_command
@@ -389,7 +432,7 @@ worm.run_with_command
 
 ### Animation Styles
 
-Worm supports three built-in animation styles:
+Worm supports three built-in animation styles plus custom patterns:
 
 #### Circles
 
@@ -409,6 +452,39 @@ Worm supports three built-in animation styles:
 - Midline: `▫` (small white square)
 - Peak: `■` (large black square)
 
+#### Custom Styles
+
+Create your own animation patterns using the `custom=XXX` format, where `XXX` is a 3-character pattern representing baseline, midline, and peak states:
+
+```bash
+# ASCII characters
+prg worm --style "custom=_-=" --message "Custom ASCII"
+
+# Unicode characters
+prg worm --style "custom=▫▪■" --message "Custom geometric"
+
+# Emojis (supports multi-byte characters)
+prg worm --style "custom=🟦🟨🟥" --message "Color progression"
+
+# Mixed ASCII and emoji
+prg worm --style "custom=.🟡*" --message "Mixed characters"
+```
+
+The custom format requires exactly 3 characters and supports:
+- ASCII characters
+- Unicode symbols and shapes
+- Emojis (properly handled as single characters)
+- Mixed combinations of the above
+
+#### Direction Control
+
+Control the animation movement pattern:
+
+- `--direction forward` (or `-d f`): Animation moves only forward
+- `--direction bidirectional` (or `-d b`): Animation moves back and forth (default)
+
+This works with all animation styles including custom patterns.
+
 ---
 
 ## Requirements

data/bin/prg

@@ -68,11 +68,18 @@ module PrgCLI
           --show-styles    Show visual previews of all styles for all subcommands
           --stop-all       Stop all prg processes
 
+      COMMON OPTIONS (available for all subcommands):
+          --ends CHARS     Start/end characters (even number split in half)
+          --speed SPEED    Animation speed (fast/medium/slow)
+          --message TEXT   Message to display with animation
+          --checkmark      Show checkmarks for success/failure
+          --command CMD    Execute command during animation
+
       EXAMPLES:
-          prg ripple "Loading..." --style rainbow --speed fast
-          prg worm --message "Processing" --style blocks --checkmark
-          prg twirl --message "Spinning" --style dots --checkmark
-          prg ripple --command "sleep 3" --success "Done!" --checkmark
+          prg ripple "Loading..." --style rainbow --speed fast --ends "[]"
+          prg worm --message "Processing" --style blocks --checkmark --ends "()"
+          prg twirl --message "Spinning" --style dots --checkmark --ends "<<>>"
+          prg ripple --command "sleep 3" --success "Done!" --checkmark --ends "{}"
 
       Run 'prg <subcommand> --help' for specific subcommand options.
     HELP
@@ -304,6 +311,10 @@ module RippleCLI
           options[:format] = f =~ /^f/i ? :forward_only : :bidirectional
         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 'Command Execution:'
 
@@ -611,10 +622,18 @@ module WormCLI
         options[:length] = length
       end
 
-      opts.on('--style STYLE', 'Animation style (circles/blocks/geometric or c/b/g)') do |style|
+      opts.on('--style STYLE', 'Animation style (circles/blocks/geometric, c/b/g, or custom=abc)') do |style|
         options[:style] = style
       end
 
+      opts.on('-d', '--direction DIRECTION', 'Animation direction (forward/bidirectional or f/b)') do |direction|
+        options[:direction] = direction =~ /^f/i ? :forward_only : :bidirectional
+      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 'Command Execution:'
 
@@ -894,6 +913,10 @@ module TwirlCLI
         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 'Command Execution:'
 
@@ -1003,14 +1026,15 @@ class TwirlSpinner
     @style = parse_style(options[:style] || 'dots')
     @speed = parse_speed(options[:speed] || 'medium')
     @frames = RubyProgress::INDICATORS[@style] || RubyProgress::INDICATORS[:dots]
+    @start_chars, @end_chars = RubyProgress::Utils.parse_ends(options[:ends])
     @index = 0
   end
 
   def animate
     if @message && !@message.empty?
-      $stderr.print "\r\e[2K#{@message} #{@frames[@index]}"
+      $stderr.print "\r\e[2K#{@start_chars}#{@message} #{@frames[@index]}#{@end_chars}"
     else
-      $stderr.print "\r\e[2K#{@frames[@index]}"
+      $stderr.print "\r\e[2K#{@start_chars}#{@frames[@index]}#{@end_chars}"
     end
     $stderr.flush
     @index = (@index + 1) % @frames.length

data/lib/ruby-progress/ripple.rb

@@ -93,7 +93,8 @@ module RubyProgress
         spinner_position: false,
         caps: false,
         inverse: false,
-        output: :error
+        output: :error,
+        ends: nil
       }
       @options = defaults.merge(options)
       @string = string
@@ -104,6 +105,7 @@ module RubyProgress
       @spinner_position = @options[:spinner_position]
       @caps = @options[:caps]
       @inverse = @options[:inverse]
+      @start_chars, @end_chars = RubyProgress::Utils.parse_ends(@options[:ends])
     end
 
     def printout
@@ -138,7 +140,7 @@ 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 "\r\e[2K#{pre}#{char}#{post}"
+      $stderr.print "\r\e[2K#{@start_chars}#{pre}#{char}#{post}#{@end_chars}"
       $stderr.flush
     end
 

data/lib/ruby-progress/utils.rb

@@ -61,5 +61,21 @@ module RubyProgress
       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
+
+    # Parse start/end characters for animation wrapping
+    # @param ends_string [String] Even-length string to split in half for start/end chars
+    # @return [Array<String>] Array with [start_chars, end_chars]
+    def self.parse_ends(ends_string)
+      return ['', ''] unless ends_string && !ends_string.empty?
+
+      chars = ends_string.each_char.to_a
+      return ['', ''] if chars.length.odd? || chars.empty?
+
+      mid_point = chars.length / 2
+      start_chars = chars[0...mid_point].join
+      end_chars = chars[mid_point..-1].join
+
+      [start_chars, end_chars]
+    end
   end
 end

data/lib/ruby-progress/version.rb

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

data/lib/ruby-progress/worm.rb

@@ -3,6 +3,7 @@
 require 'optparse'
 require 'open3'
 require 'json'
+require_relative 'utils'
 
 module RubyProgress
   # Animated progress indicator with ripple effect using Unicode combining characters
@@ -63,6 +64,8 @@ module RubyProgress
       @error_text = options[:error]
       @show_checkmark = options[:checkmark] || false
       @output_stdout = options[:stdout] || false
+      @direction_mode = options[:direction] || :bidirectional
+      @start_chars, @end_chars = RubyProgress::Utils.parse_ends(options[:ends])
       @running = false
     end
 
@@ -101,7 +104,8 @@ module RubyProgress
         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
+        # Always clear animation line and restore cursor
+        $stderr.print "\r\e[2K"
         RubyProgress::Utils.show_cursor
         Signal.trap('INT', original_int_handler) if original_int_handler
       end
@@ -224,7 +228,7 @@ module RubyProgress
       @direction ||= 1
 
       message_part = @message && !@message.empty? ? "#{@message} " : ''
-      $stderr.print "\r\e[2K#{message_part}#{generate_dots(@position, @direction)}"
+      $stderr.print "\r\e[2K#{@start_chars}#{message_part}#{generate_dots(@position, @direction)}#{@end_chars}"
       $stderr.flush
 
       sleep @speed
@@ -232,7 +236,11 @@ module RubyProgress
       # Update position and direction
       @position += @direction
       if @position >= @length - 1
-        @direction = -1
+        if @direction_mode == :forward_only
+          @position = 0
+        else
+          @direction = -1
+        end
       elsif @position <= 0
         @direction = 1
       end
@@ -248,7 +256,8 @@ module RubyProgress
         mark = success ? '✅ ' : '🛑 '
       end
 
-      puts "#{mark}#{message}"
+      # Clear animation line and output completion message on stderr
+      $stderr.print "\r\e[2K#{mark}#{message}\n"
     end
 
     def parse_speed(speed_input)
@@ -282,7 +291,15 @@ module RubyProgress
     def parse_style(style_input)
       return RIPPLE_STYLES['circles'] unless style_input && !style_input.to_s.strip.empty?
 
-      style_lower = style_input.to_s.downcase.strip
+      style_str = style_input.to_s.strip
+
+      # Check for custom style format: custom=abc or custom_abc or customXabc
+      if style_str.match(/^custom[_=](.+)$/i)
+        custom_chars = Regexp.last_match(1)
+        return parse_custom_style(custom_chars)
+      end
+
+      style_lower = style_str.downcase
 
       # First, try exact match
       return RIPPLE_STYLES[style_lower] if RIPPLE_STYLES.key?(style_lower)
@@ -336,6 +353,24 @@ module RubyProgress
       RIPPLE_STYLES['circles']
     end
 
+    def parse_custom_style(custom_chars)
+      # Split into individual characters, properly handling multi-byte characters (emojis)
+      chars = custom_chars.each_char.to_a
+
+      # Ensure we have exactly 3 characters
+      if chars.length != 3
+        # Fallback to default if not exactly 3 characters
+        return RIPPLE_STYLES['circles']
+      end
+
+      # Create custom style hash with baseline, midline, peak
+      {
+        baseline: chars[0],
+        midline: chars[1],
+        peak: chars[2]
+      }
+    end
+
     def animation_loop
       position = 0
       direction = 1
@@ -343,14 +378,18 @@ module RubyProgress
       while @running
         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.print "\r\e[2K#{@start_chars}#{message_part}#{generate_dots(position, direction)}#{@end_chars}"
         $stderr.flush
 
         sleep @speed
 
         position += direction
         if position >= @length - 1
-          direction = -1
+          if @direction_mode == :forward_only
+            position = 0
+          else
+            direction = -1
+          end
         elsif position <= 0
           direction = 1
         end
@@ -383,7 +422,11 @@ module RubyProgress
 
         position += direction
         if position >= @length - 1
-          direction = -1
+          if @direction_mode == :forward_only
+            position = 0
+          else
+            direction = -1
+          end
         elsif position <= 0
           direction = 1
         end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-progress
 version: !ruby/object:Gem::Version
-  version: 1.1.8
+  version: 1.2.0
 platform: ruby
 authors:
 - Brett Terpstra