ruby-progress 1.1.9 → 1.2.4

data/README.md

@@ -25,10 +25,25 @@ prg ripple "Loading..." --style rainbow --speed fast
 # Use twirl spinner animation
 prg twirl --message "Working..." --style dots --speed fast
 
-# With command execution
+# 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
+```
+
+### With command execution
 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 +53,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,34 +62,35 @@ 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)
 
 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)
+### Start in background (uses default PID file)
 prg worm --daemon --message "Working..."
 
-# Start with a custom name (creates /tmp/ruby-progress/NAME.pid)
+### Start with a custom name (creates /tmp/ruby-progress/NAME.pid)
 prg worm --daemon-as mytask --message "Processing data..."
 
-# ... run your tasks ...
+### ... run your tasks ...
 
-# Stop with a success message and checkmark (--stop-success implies --stop)
+### 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)
+### 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
+### Or stop with an error message and checkmark
 prg worm --stop-error "Failed during step" --stop-checkmark
 
-# Check status at any time
+### Check status at any time
 prg worm --status
 prg worm --status-id mytask
 
-# Use a completely custom PID file path
+### 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
@@ -86,14 +102,67 @@ Notes:
 - `--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](#ruby-progress-indicators)
+- [Unified Interface](#unified-interface)
+  - [With command execution](#with-command-execution)
+  - [With start/end character decoration using --ends](#with-startend-character-decoration-using-ends)
+  - [Complex --ends patterns with emojis](#complex-ends-patterns-with-emojis)
+  - [Start in background (uses default PID file)](#start-in-background-uses-default-pid-file)
+  - [Start with a custom name (creates /tmp/ruby-progress/NAME.pid)](#start-with-a-custom-name-creates-tmpruby-progressnamepid)
+  - [... run your tasks ...](#-run-your-tasks-)
+  - [Stop with a success message and checkmark (--stop-success implies --stop)](#stop-with-a-success-message-and-checkmark-stop-success-implies-stop)
+  - [Stop a named daemon (--stop-id implies --stop)](#stop-a-named-daemon-stop-id-implies-stop)
+  - [Or stop with an error message and checkmark](#or-stop-with-an-error-message-and-checkmark)
+  - [Check status at any time](#check-status-at-any-time)
+  - [Use a completely custom PID file path](#use-a-completely-custom-pid-file-path)
+  - [Basic text animation](#basic-text-animation)
+  - [With style options](#with-style-options)
+  - [Multiple styles combined](#multiple-styles-combined)
+  - [Case transformation mode](#case-transformation-mode)
+  - [Run a command with progress animation](#run-a-command-with-progress-animation)
+  - [Simple progress block](#simple-progress-block)
+  - [With options](#with-options)
+  - [Basic spinner animation](#basic-spinner-animation)
+  - [With command execution](#with-command-execution)
+  - [Different spinner styles](#different-spinner-styles)
+  - [With success/error handling](#with-successerror-handling)
+  - [Daemon mode for background tasks](#daemon-mode-for-background-tasks)
+  - [... do other work ...](#-do-other-work-)
+  - [Run indefinitely without a command (like ripple)](#run-indefinitely-without-a-command-like-ripple)
+  - [Run a command with progress animation](#run-a-command-with-progress-animation)
+  - [Customize the animation](#customize-the-animation)
+  - [With custom error handling](#with-custom-error-handling)
+  - [With checkmarks for visual feedback](#with-checkmarks-for-visual-feedback)
+  - [Control animation direction (forward-only or bidirectional)](#control-animation-direction-forward-only-or-bidirectional)
+  - [Create custom animations with 3-character patterns](#create-custom-animations-with-3-character-patterns)
+  - [Add start/end characters around the animation](#add-startend-characters-around-the-animation)
+  - [Capture and display command output](#capture-and-display-command-output)
+  - [Combine checkmarks and stdout output](#combine-checkmarks-and-stdout-output)
+  - [Start in the background (default PID file: /tmp/ruby-progress/progress.pid)](#start-in-the-background-default-pid-file-tmpruby-progressprogresspid)
+  - [... run your tasks ...](#-run-your-tasks-)
+  - [Stop using the default PID file](#stop-using-the-default-pid-file)
+  - [Use a custom PID file](#use-a-custom-pid-file)
+  - [Stop using the matching custom PID file](#stop-using-the-matching-custom-pid-file)
+  - [Create and run animation with a block](#create-and-run-animation-with-a-block)
+  - [Your work here](#your-work-here)
+  - [With custom style and forward direction](#with-custom-style-and-forward-direction)
+  - [Or run with a command](#or-run-with-a-command)
+  - [ASCII characters](#ascii-characters)
+  - [Unicode characters](#unicode-characters)
+  - [Emojis (supports multi-byte characters)](#emojis-supports-multi-byte-characters)
+  - [Mixed ASCII and emoji](#mixed-ascii-and-emoji)
+  - [Cursor control](#cursor-control)
+  - [Basic completion message](#basic-completion-message)
+  - [With success/failure indication and checkmarks](#with-successfailure-indication-and-checkmarks)
+  - [Clear line and display completion (useful for replacing progress indicators)](#clear-line-and-display-completion-useful-for-replacing-progress-indicators)
 
 ## Table of Contents
 
 - [Ruby Progress Indicators](#ruby-progress-indicators)
   - [Unified Interface](#unified-interface)
-    - [Global Options](#global-options)
-    - [Common Options (available for both subcommands)](#common-options-available-for-both-subcommands)
-    - [Daemon Mode (Background Progress)](#daemon-mode-background-progress)
+    - [With command execution](#with-command-execution)
+    - [With start/end character decoration using --ends](#with-startend-character-decoration-using---ends)
+    - [Complex --ends patterns with emojis](#complex---ends-patterns-with-emojis)
   - [Table of Contents](#table-of-contents)
   - [Ripple](#ripple)
     - [Ripple Features](#ripple-features)
@@ -118,6 +187,8 @@ Notes:
       - [Circles](#circles)
       - [Blocks](#blocks)
       - [Geometric](#geometric)
+      - [Custom Styles](#custom-styles)
+      - [Direction Control](#direction-control)
   - [Requirements](#requirements)
   - [Installation](#installation)
     - [As a Gem (Recommended)](#as-a-gem-recommended)
@@ -129,6 +200,7 @@ Notes:
   - [Contributing](#contributing)
   - [License](#license)
 
+
 ---
 
 ## Ripple
@@ -150,19 +222,19 @@ Ripple is a sophisticated text animation library that creates ripple effects acr
 #### Ripple CLI examples
 
 ```bash
-# Basic text animation
+### Basic text animation
 prg ripple "Loading..."
 
-# With style options
+### With style options
 prg ripple "Processing Data" --speed fast --style rainbow --direction bidirectional
 
-# Multiple styles combined
+### Multiple styles combined
 prg ripple "Loading..." --style rainbow,inverse
 
-# Case transformation mode
+### Case transformation mode
 prg ripple "Processing Text" --style caps,inverse
 
-# Run a command with progress animation
+### Run a command with progress animation
 prg ripple "Installing packages" --command "sleep 5" --success "Installation complete!" --checkmark
 ```
 
@@ -187,12 +259,12 @@ You can also use Ripple as a Ruby library:
 ```ruby
 require 'ruby-progress'
 
-# Simple progress block
+### Simple progress block
 result = RubyProgress::Ripple.progress("Processing...") do
   sleep 5  # Your actual work here
 end
 
-# With options
+### With options
 rippler = RubyProgress::Ripple.new("Loading Data", {
   speed: :fast,
   format: :bidirectional,
@@ -227,24 +299,24 @@ Twirl is a lightweight spinner animation system providing over 35 different spin
 #### Command Line
 
 ```bash
-# Basic spinner animation
+### Basic spinner animation
 prg twirl --message "Processing..." --style dots
 
-# With command execution
+### With command execution
 prg twirl --command "npm install" --message "Installing" --style arc
 
-# Different spinner styles
+### Different spinner styles
 prg twirl --message "Working" --style arrows --speed fast
 prg twirl --message "Loading" --style blocks --speed slow
 
-# With success/error handling
+### With success/error handling
 prg twirl --command "make build" --success "Build complete!" --error "Build failed!" --checkmark
 
-# Daemon mode for background tasks
+### 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 ...
+### ... do other work ...
 prg twirl --stop-success "Processing complete!"
 prg twirl --stop-id mytask --stop-success "Task finished!"
 ```
@@ -303,26 +375,40 @@ Worm is a clean, Unicode-based progress indicator that creates a ripple effect u
 #### Command Line
 
 ```bash
-# Run indefinitely without a command (like ripple)
-./worm.rb --message "Loading..." --speed fast --style circles
+### 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!"
 
-# Run a command with progress animation
-./worm.rb --command "sleep 5" --message "Installing" --success "Done!"
+### Customize the animation
+prg worm --command "make build" --speed fast --length 5 --style blocks
 
-# Customize the animation
-./worm.rb --command "make build" --speed fast --length 5 --style blocks
+### With custom error handling
+prg worm --command "risky_operation" --error "Operation failed" --style geometric
 
-# With custom error handling
-./worm.rb --command "risky_operation" --error "Operation failed" --style geometric
+### With checkmarks for visual feedback
+prg worm --command "npm install" --success "Installation complete!" --checkmark
 
-# With checkmarks for visual feedback
-./worm.rb --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
 
-# Capture and display command output
-./worm.rb --command "git status" --message "Checking status" --stdout
+### 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
 
-# Combine checkmarks and stdout output
-./worm.rb --command "echo 'Build output'" --success "Build complete!" --checkmark --stdout
+### 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
 ```
 
 #### Daemon mode (background indicator)
@@ -330,18 +416,18 @@ Worm is a clean, Unicode-based progress indicator that creates a ripple effect u
 Run the worm indicator as a background daemon and stop it later (useful in shell scripts):
 
 ```bash
-# Start in the background (default PID file: /tmp/ruby-progress/progress.pid)
+### Start in the background (default PID file: /tmp/ruby-progress/progress.pid)
 prg worm --daemon
 
-# ... run your tasks ...
+### ... run your tasks ...
 
-# Stop using the default PID file
+### Stop using the default PID file
 prg worm --stop
 
-# Use a custom PID file
+### Use a custom PID file
 prg worm --daemon --pid-file /tmp/custom-worm.pid
 
-# Stop using the matching custom PID file
+### Stop using the matching custom PID file
 prg worm --stop --pid-file /tmp/custom-worm.pid
 ```
 
@@ -351,27 +437,38 @@ 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
 
 ```ruby
 require 'ruby-progress'
 
-# Create and run animation with a block
+### Create and run animation with a block
 worm = RubyProgress::Worm.new(
   length: 4,
   message: "Processing",
   speed: 'fast',
-  style: 'circles'
+  style: 'circles',
+  direction: :bidirectional
 )
 
 result = worm.animate(
@@ -382,14 +479,23 @@ result = worm.animate(
   some_long_running_task
 end
 
-# Or run with a command
+### 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
 ```
 
 ### Animation Styles
 
-Worm supports three built-in animation styles:
+Worm supports three built-in animation styles plus custom patterns:
 
 #### Circles
 
@@ -409,6 +515,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
@@ -462,7 +601,7 @@ The gem provides universal utilities in the `RubyProgress::Utils` module for com
 ```ruby
 require 'ruby-progress'
 
-# Cursor control
+### Cursor control
 RubyProgress::Utils.hide_cursor    # Hide terminal cursor
 RubyProgress::Utils.show_cursor    # Show terminal cursor
 RubyProgress::Utils.clear_line     # Clear current line
@@ -471,10 +610,10 @@ RubyProgress::Utils.clear_line     # Clear current line
 ### Completion Messages
 
 ```ruby
-# Basic completion message
+### Basic completion message
 RubyProgress::Utils.display_completion("Task completed!")
 
-# With success/failure indication and checkmarks
+### With success/failure indication and checkmarks
 RubyProgress::Utils.display_completion(
   "Build successful!",
   success: true,
@@ -488,7 +627,7 @@ RubyProgress::Utils.display_completion(
   output_stream: :stdout  # :stdout, :stderr, or :warn (default)
 )
 
-# Clear line and display completion (useful for replacing progress indicators)
+### Clear line and display completion (useful for replacing progress indicators)
 RubyProgress::Utils.complete_with_clear(
   "Processing complete!",
   success: true,

data/Rakefile

@@ -7,6 +7,13 @@ require 'rubocop/rake_task'
 RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new
 
+# Convenience aliases
+# `rake test` -> runs the :spec task (RSpec)
+task test: :spec
+
+# Provide a `rake lint` alias that runs RuboCop (which defines the :rubocop task)
+task lint: :rubocop
+
 task default: [:spec]
 
 # Used by markdown tasks

data/bin/fill

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Thin shim to delegate to the unified prg CLI
+prg = File.expand_path(File.join(__dir__, 'prg'))
+if File.executable?(prg)
+  exec prg, 'fill', *ARGV
+else
+  exec 'prg', 'fill', *ARGV
+end