Ruby Progress Indicators

This repository contains three different Ruby progress indicator projects: Ripple, Worm, and Twirl. All provide animated terminal progress indicators with different visual styles and features.

The gem provides a unified prg command that supports all progress indicators through subcommands:

# Install the gem
gem install ruby-progress
# Use worm-style animation
prg worm --message "Processing data" --style blocks --checkmark
# Use ripple-style animation
prg ripple "Loading..." --style rainbow --speed fast
# Use twirl spinner animation
prg twirl --message "Working..." --style dots --speed fast
# Dedicated `fill` shim
# If you prefer a dedicated binary for the determinate progress bar, a thin `fill` shim is available that delegates to `prg fill`:
# Run fill directly (delegates to prg)
fill --report --percent 50

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

prg ripple "Loading data" --ends "[]" --style rainbow prg worm --message "Processing" --ends "()" --style blocks prg twirl --message "Building" --ends "<<>>" --style dots

prg worm --message "Magic" --ends "🎯🎪" --style "custom=🟦🟨🟥"

### Global Options
- `prg --help` - Show main help
- `prg --version` - Show version info
- `prg --list-styles` - Show all available styles for all subcommands
- `prg <subcommand> --help` - Show specific subcommand help
### Common Options (available for all subcommands)
- `--speed SPEED` - Animation speed (fast/medium/slow or f/m/s)
- `--message MESSAGE` - Message to display
- `--command COMMAND` - Command to execute during animation
- `--success MESSAGE` - Success message after completion
- `--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)
For shell scripts where you need a continuous progress indicator across multiple steps, use daemon mode. You can use named daemons or custom PID files.
```bash
### Start in background (uses default PID file)
prg worm --daemon --message "Working..."
### Start with a custom name (creates /tmp/ruby-progress/NAME.pid)
prg worm --daemon-as mytask --message "Processing data..."
### ... run your tasks ...
### Stop with a success message and checkmark (--stop-success implies --stop)
prg worm --stop-success "All done" --stop-checkmark
### Stop a named daemon (--stop-id implies --stop)
prg worm --stop-id mytask --stop-success "Task complete!" --stop-checkmark
### Or stop with an error message and checkmark
prg worm --stop-error "Failed during step" --stop-checkmark
### Check status at any time
prg worm --status
prg worm --status-id mytask
### Use a completely custom PID file path
prg worm --daemon --pid-file /tmp/custom-progress.pid
prg worm --status --pid-file /tmp/custom-progress.pid
prg worm --stop-success "Complete" --pid-file /tmp/custom-progress.pid

Notes:

• The CLI detaches itself (double-fork); do not append &. This prevents shell job notifications like “job … has ended.” The command returns immediately.
• --stop-success and --stop-error are mutually exclusive; whichever you provide determines the success state and icon if --stop-checkmark is set.
• The indicator clears its line on shutdown and prints the final message to STDOUT.
• --stop-pid is still supported for backward compatibility, but --stop [--pid-file FILE] is preferred. o- Ruby Progress Indicators
• Unified Interface
  • With command execution
  • With start/end character decoration using --ends
  • Complex --ends patterns with emojis
  • Start in background (uses default PID file)
  • Start with a custom name (creates /tmp/ruby-progress/NAME.pid)
  • ... run your tasks ...
  • Stop with a success message and checkmark (--stop-success implies --stop)
  • Stop a named daemon (--stop-id implies --stop)
  • Or stop with an error message and checkmark
  • Check status at any time
  • Use a completely custom PID file path
  • Basic text animation
  • With style options
  • Multiple styles combined
  • Case transformation mode
  • Run a command with progress animation
  • Simple progress block
  • With options
  • Basic spinner animation
  • With command execution
  • Different spinner styles
  • With success/error handling
  • Daemon mode for background tasks
  • ... do other work ...
  • Run indefinitely without a command (like ripple)
  • Run a command with progress animation
  • Customize the animation
  • With custom error handling
  • With checkmarks for visual feedback
  • Control animation direction (forward-only or bidirectional)
  • Create custom animations with 3-character patterns
  • Add start/end characters around the animation
  • Capture and display command output
  • Combine checkmarks and stdout output
  • Start in the background (default PID file: /tmp/ruby-progress/progress.pid)
  • ... run your tasks ...
  • Stop using the default PID file
  • Use a custom PID file
  • Stop using the matching custom PID file
  • Create and run animation with a block
  • Your work here
  • With custom style and forward direction
  • Or run with a command
  • ASCII characters
  • Unicode characters
  • Emojis (supports multi-byte characters)
  • Mixed ASCII and emoji
  • Cursor control
  • Basic completion message
  • With success/failure indication and checkmarks
  • Clear line and display completion (useful for replacing progress indicators)

• Ruby Progress Indicators
  • Unified Interface
    • With command execution
    • With start/end character decoration using --ends
    • Complex --ends patterns with emojis
  • Table of Contents
  • Ripple
    • Ripple Features
    • Ripple Usage
      • Ripple CLI examples
      • Ripple Command Line Options
    • Ripple Library Usage
  • Twirl
    • Twirl Features
    • Twirl Usage
      • Command Line
      • Twirl Command Line Options
    • Available Spinner Styles
  • Worm
    • Worm Features
    • Worm Usage
      • Command Line
      • Daemon mode (background indicator)
      • Worm Command Line Options
    • Worm Library Usage
    • Animation Styles
      • Circles
      • Blocks
      • Geometric
      • Custom Styles
      • Direction Control
  • Requirements
  • Installation
    • As a Gem (Recommended)
    • From Source
    • Development
  • Universal Utilities
    • Terminal Control
    • Completion Messages
  • Contributing
  • License

Ripple is a sophisticated text animation library that creates ripple effects across text strings in the terminal. It supports various animation modes including bidirectional movement, and rainbow colors.

• Text ripple animations with customizable speed and direction
• Style system supporting rainbow colors and inverse highlighting
• Multiple animation formats: forward-only, bidirectional
• Command execution with animated progress display
• Custom success/failure messages with optional checkmarks
• Case transformation modes (uppercase/lowercase rippling)
• Composable styles using comma-separated values

### Basic text animation
prg ripple "Loading..."
### With style options
prg ripple "Processing Data" --speed fast --style rainbow --direction bidirectional
### Multiple styles combined
prg ripple "Loading..." --style rainbow,inverse
### Case transformation mode
prg ripple "Processing Text" --style caps,inverse
### Run a command with progress animation
prg ripple "Installing packages" --command "sleep 5" --success "Installation complete!" --checkmark

You can also use Ripple as a Ruby library:

require 'ruby-progress'
### Simple progress block
result = RubyProgress::Ripple.progress("Processing...") do
  sleep 5  # Your actual work here
end
### With options
rippler = RubyProgress::Ripple.new("Loading Data", {
  speed: :fast,
  format: :bidirectional,
  rainbow: true,
  spinner: :dots
})
RubyProgress::Ripple.hide_cursor
while some_condition
  rippler.advance
end
RubyProgress::Ripple.show_cursor

Twirl is a lightweight spinner animation system providing over 35 different spinner styles for terminal progress indication. It's perfect for showing indefinite progress during command execution.

• 35+ spinner styles including dots, arrows, blocks, and geometric patterns
• Flexible speed control (1-10 scale or named speeds)
• Command execution with animated progress display
• Daemon mode for background progress indication
• Custom success/failure messages with optional checkmarks
• Signal handling for graceful shutdown and status updates

### Basic spinner animation
prg twirl --message "Processing..." --style dots
### With command execution
prg twirl --command "npm install" --message "Installing" --style arc
### Different spinner styles
prg twirl --message "Working" --style arrows --speed fast
prg twirl --message "Loading" --style blocks --speed slow
### With success/error handling
prg twirl --command "make build" --success "Build complete!" --error "Build failed!" --checkmark
### Daemon mode for background tasks
prg twirl --daemon --message "Background processing" --style geometric
prg twirl --daemon-as mytask --message "Named task" --style dots
### ... do other work ...
prg twirl --stop-success "Processing complete!"
prg twirl --stop-id mytask --stop-success "Task finished!"

Twirl includes over 35 different spinner animations:

• Dots: dots, dots_2, dots_3, dots_pulse, dots_scrolling
• Arrows: arrow, arrow_pulse, arrows, arrows_2
• Blocks: blocks, blocks_2, toggle, toggle_2
• Lines: line, line_2, pipe, vertical_bar
• Geometric: arc, circle, triangle, square_corners
• Classic: classic, bounce, push, flip
• And many more!

Use prg --list-styles to see all available spinner options.

Worm is a clean, Unicode-based progress indicator that creates a ripple effect using combining characters. It's designed for running commands with visual progress feedback.

• Ripple wave animation using Unicode characters
• Multiple visual styles (circles, blocks, geometric)
• Configurable speed (1-10 scale or named speeds)
• Customizable length and messages
• Command execution with progress indication
• Success/error message customization
• Proper signal handling and cursor management

### Run indefinitely without a command (like ripple)
prg worm --message "Loading..." --speed fast --style circles
### Run a command with progress animation
prg worm --command "sleep 5" --message "Installing" --success "Done!"
### Customize the animation
prg worm --command "make build" --speed fast --length 5 --style blocks
### With custom error handling
prg worm --command "risky_operation" --error "Operation failed" --style geometric
### With checkmarks for visual feedback
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
prg worm --command "git status" --message "Checking status" --stdout
### Combine checkmarks and stdout output
prg worm --command "echo 'Build output'" --success "Build complete!" --checkmark --stdout

Run the worm indicator as a background daemon and stop it later (useful in shell scripts):

### Start in the background (default PID file: /tmp/ruby-progress/progress.pid)
prg worm --daemon
### ... run your tasks ...
### Stop using the default PID file
prg worm --stop
### Use a custom PID file
prg worm --daemon --pid-file /tmp/custom-worm.pid
### Stop using the matching custom PID file
prg worm --stop --pid-file /tmp/custom-worm.pid

Stopping clears the progress line for clean output. You can also provide a success message and checkmark while stopping by sending SIGUSR1; the CLI handles cleanup automatically.

Note: You don’t need & when starting the daemon. The command detaches itself and returns right away, which also avoids “job … has ended” messages from your shell.

require 'ruby-progress'
### Create and run animation with a block
worm = RubyProgress::Worm.new(
  length: 4,
  message: "Processing",
  speed: 'fast',
  style: 'circles',
  direction: :bidirectional
)
result = worm.animate(
  success: "Complete!",
  error: "Failed!"
) do
  # Your work here
  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

Worm supports three built-in animation styles plus custom patterns:

• Baseline: · (middle dot)
• Midline: ● (black circle)
• Peak: ⬤ (large circle)

• Baseline: ▁ (lower eighth block)
• Midline: ▄ (lower half block)
• Peak: █ (full block)

• Baseline: ▪ (small black square)
• Midline: ▫ (small white square)
• Peak: ■ (large black square)

Create your own animation patterns using the custom=XXX format, where XXX is a 3-character pattern representing baseline, midline, and peak states:

### 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

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.

Both projects require:

• Ruby 2.5 or higher
• Terminal with Unicode support (for Worm)
• ANSI color support (for Ripple rainbow effects)

gem install ruby-progress

1. Clone this repository

2. Build and install:

   bundle install
   bundle exec rake build
   gem install pkg/ruby-progress-*.gem

1. Clone the repository

2. Install dependencies:

   bundle install

3. Run tests:

   bundle exec rspec

The gem provides universal utilities in the RubyProgress::Utils module for common terminal operations:

require 'ruby-progress'
### Cursor control
RubyProgress::Utils.hide_cursor    # Hide terminal cursor
RubyProgress::Utils.show_cursor    # Show terminal cursor
RubyProgress::Utils.clear_line     # Clear current line

### Basic completion message
RubyProgress::Utils.display_completion("Task completed!")
### With success/failure indication and checkmarks
RubyProgress::Utils.display_completion(
  "Build successful!",
  success: true,
  show_checkmark: true
)
RubyProgress::Utils.display_completion(
  "Build failed!",
  success: false,
  show_checkmark: true,
  output_stream: :stdout  # :stdout, :stderr, or :warn (default)
)
### Clear line and display completion (useful for replacing progress indicators)
RubyProgress::Utils.complete_with_clear(
  "Processing complete!",
  success: true,
  show_checkmark: true,
  output_stream: :stdout
)

These utilities are used internally by Ripple, Worm, and Twirl classes and are available for use in your own applications.

Feel free to submit issues and pull requests to improve either project!

Both projects are provided as-is for educational and practical use.