ruby-progress 1.3.5 → 1.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a22fcfc5ae8ffc222ac1f19f4d7b5295f9205c8ae95bce7ec8be8884e076f578
-  data.tar.gz: f96675ec9f6bcc1e6dd905763b45ea776bbf3f78f57629fc50a2cac4a13d22b2
+  metadata.gz: '028f7d94178db61fa5e6fc4353b977b1279504486e83dd540ea63fa9bc7bd6ee'
+  data.tar.gz: 135e0f649c449fccb49de440e1b4ff33782bb4d1e44e340d818a2c989628d098
 SHA512:
-  metadata.gz: 4a61a58643c367f94645d5f3fded92473c44f72ee17553f47f89e27403780cbb3c7bb0fb3a3b36876be8928162434cd28aa847ef6e2ec488ec115c64f06bee2e
-  data.tar.gz: 9a7eda5a91f80ea1be162bb6bd250da3134f0567fa1c47f6c9e782f6aa80e16ed379e60da48a1ebd59f44dcb80a50cc92467ed9ec42be7196ceb973be66113fb
+  metadata.gz: 721f3ca96efffadf06b20079ad931f9f47c1580506c7fb4e174323353fafed08f855594561fa77b4af2cbc99ba1d23347662a4363363b5364f41908a936b8cf1
+  data.tar.gz: 262fc8c721794e2f9a13474d00619577c918b70c6af55b30cad2e92d7382af36d3b2d743e3cc3ff0b2159c6498b40ae40f8a057e224f75a12bc385045f23df4e

data/CHANGELOG.md

@@ -5,6 +5,16 @@ 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.3.6] - 2025-10-15
+
+### Fixed
+
+- **Interrupt handling**: Fixed Twirl and Worm CLIs to exit cleanly on Ctrl+C (SIGINT) without displaying backtraces
+  - Added top-level `trap('INT')` handlers to both `twirl_cli.rb` and `worm_cli.rb`
+  - Added `rescue Interrupt` clauses to Twirl runner methods for graceful cleanup
+  - All four progress indicators (Ripple, Worm, Twirl, Fill) now have consistent interrupt handling
+  - Properly clean up (show cursor, clear line) and exit with code 130 on interrupt
+
 ## [1.3.5] - 2025-10-15
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby-progress (1.3.5)
+    ruby-progress (1.3.6)
       tty-cursor (~> 0.7)
       tty-screen (~> 0.8)
 

data/blog-post.md

@@ -1,39 +1,154 @@
 ---
-title: "More CLI Progress Indicators: The ruby-progress Gem"
-date: 2025-10-10
+title: "Ruby Progress Indicators for Modern CLI Tools"
+date: 2025-10-15 11:00
 categories: [Ruby, CLI, Development Tools]
-tags: [ruby, cli, progress, animation, terminal]
+tags: [ruby, cli, progress, animation, terminal, daemon]
 ---
+I've been playing around with progress bars in the terminal, and I think I've
+created something genuinely useful.
 
-[ripple]: https://brettterpstra.com/2025/06/30/ripple-an-indeterminate-progress-indicator/
+Yes, I know there are multiple options
+already available for this, but I wanted something specific: a Ruby library that
+could be used for command-line scripting, with CLI executables that made it easy
+to use when scripting in *any* language --- not just Ruby.
 
-# More CLI Progress Indicators: The ruby-progress Gem
+The result is `ruby-progress`, a gem that provides four different animated
+progress indicators, each with its own visual style and use cases.
 
-The `ruby-progress` gem expands my previous work on [Ripple], adding 2 more indicator types and a new daemon mode to make it more useful in non-Ruby shell scripts.
+> If you're scripting in Ruby, I do highly recommend the TTY tools from [Piotr Murach](piotrmurach),
+such as [tty-progress](https://github.com/piotrmurach/tty-progressbar/). Piotr's
+TTY tools are much more elegant with a better Ruby API. `ruby-progress` is
+designed more for use in other shell scripts than it is for detailed Ruby
+scripting.
+{:.tip}
 
-## What is ruby-progress?
+{% gif /uploads/2025/10/ruby-progress.mp4 %}
 
-Ruby-progress provides animated progress indicators for command-line applications. Unlike traditional progress bars showing completion percentage, this gem focuses on continuous animations (indeterminate) that indicate activity - perfect for tasks with unpredictable completion times.
+## The Four Progress Indicators
 
-Three animation styles are available:
+Ripple
+: creates a wave-like effect across text, with the characters rippling
+through different visual states. It supports rainbow colors, inverse
+highlighting, and case transformations. Perfect for text-heavy operations where
+you want something more dynamic than a simple spinner.
 
-- **Ripple**: Wave-like effect across text
-- **Worm**: Moving dot pattern that crawls across the screen
-- **Twirl**: Classic spinning indicators with various symbols
+Worm
+: displays a moving dot pattern that crawls across the screen using
+Unicode characters. It includes multiple styles (circles, blocks, geometric
+shapes) and can move in any direction. Great for file operations, network
+transfers, or any continuous background task.
 
-## Quick Start
+Twirl
+: provides classic spinning indicators with over 35 different spinner
+styles --- from simple dots to complex geometric patterns. It's the most
+traditional of the four, but with way more visual variety than typical spinners.
+
+Fill : is the only determinate indicator in the bunch --- an actual progress bar
+that shows completion percentage. It can be controlled via command execution or
+updated programmatically through daemon control messages.
+
+## Installation and Quick Start
+
+Installation is straightforward:
 
 ```bash
-# Install
 gem install ruby-progress
+```
+
+All four indicators are available through a unified `prg` command:
 
+```bash
 # Basic usage
-ripple "Processing files..."
-worm --message "Loading..." --speed fast
-twirl --spinner dots
+prg ripple "Processing files..."
+prg worm --message "Loading..." --style blocks
+prg twirl --message "Working..." --style dots --speed fast
+prg fill --total 100 --report
+
+# With command execution
+prg ripple "Building..." --command "make build" --success "Build complete!" --checkmark
+```
+
+You can also use the individual commands directly: `ripple`, `worm`, `twirl`, and `fill`.
+
+## The Killer Feature: Daemon Mode
+
+Here's where things get interesting. All four indicators support daemon mode,
+which lets you run a progress indicator in the background while your scripts
+execute other commands. This is useful for complex workflows.
+
+```bash
+# Start a background spinner
+prg worm --daemon-as deployment --message "Deploying application..."
+
+# Execute your actual deployment steps
+git push production main
+kubectl apply -f manifests/
+./run-migrations.sh
+
+# Stop the spinner with a success message
+prg job stop --daemon-name deployment --message "Deployment complete!" --checkmark
+```
+
+The daemon mode uses `Process.fork` and `Process.detach`, so there are no shell
+job notifications cluttering your output. The progress indicator runs cleanly in
+the background, providing visual feedback without interfering with your script's
+execution.
+
+### Keeping Output Clean
+
+One of the challenges with daemon mode is preventing command output from
+disrupting the animation. By default, when you run a progress indicator in
+daemon mode, any STDOUT or STDERR output from commands executed in your script
+will appear on the terminal and potentially mess up the animation display.
+
+Ruby-progress handles this intelligently. When running in daemon mode, the
+animation continues on its dedicated line while your commands execute. However,
+if you want to see the output from those commands, you have options:
+
+```bash
+# Run command with animation, show output after completion
+prg ripple "Building..." --command "make build" --stdout
+
+# Stream output live while animation runs (reserves terminal rows)
+prg worm "Installing..." --command "npm install" --stdout-live --output-lines 5
+
+# Run daemon and manually capture output from your script commands
+prg worm --daemon-as build --message "Building..."
+make build > /tmp/build.log 2>&1
+prg job stop --daemon-name build --message "Build complete!" --checkmark
+cat /tmp/build.log
+```
+
+The `--stdout-live` flag is particularly useful --- it reserves a section of the
+terminal to display live command output while the animation continues above or
+below it. You control how many lines to reserve with `--output-lines` and where
+they appear with `--output-position` (above or below the animation).
+
+### Job Control Commands
+
+The `prg job` command provides subcommands for controlling background indicators:
+
+- `prg job stop` --- Stop a running daemon with an optional message
+- `prg job status` --- Check if a daemon is running and show its PID
+- `prg job advance` --- Update a fill progress bar by a specific amount
+
+```bash
+# Check if a daemon is running
+prg job status --daemon-name mytask
+
+# Advance a progress bar remotely
+prg fill --daemon-as progress --total 100
+prg job advance --daemon-name progress --amount 10
+
+# Stop with error state
+prg job stop --daemon-name mytask --message "Build failed!" --error
 ```
 
-## Ruby Integration
+{% paywall "Library and advanced usage" %}
+
+## Ruby Library Usage
+
+While the CLI is great for shell scripting, the Ruby API is just as elegant:
 
 ```ruby
 require 'ruby-progress'
@@ -44,131 +159,108 @@ RubyProgress::Ripple.progress("Processing files...") do
   upload_results
 end
 
-# Manual control
+# Manual control for complex scenarios
 worm = RubyProgress::Worm.new(
   message: "Custom task",
   style: 'blocks',
   speed: 'medium'
 )
 
-worm.animate { heavy_computation }
-```
+worm.animate do
+  heavy_computation
+  more_work
+end
 
-## Daemon Mode - The Killer Feature
+# Command execution with error handling
+RubyProgress::Twirl.new(
+  command: "bundle install",
+  message: "Installing gems...",
+  success: "Dependencies installed!",
+  error: "Installation failed",
+  checkmark: true
+).run_with_command
+```
 
-Run progress indicators in the background while your scripts execute:
+## Advanced Features Worth Knowing
 
-```bash
-# Start background indicator
-worm --daemon --pid-file /tmp/progress.pid --message "Deploying..."
+### Custom Styling and Icons
 
-# Run your actual work
-./deploy.sh
-kubectl apply -f manifests/
+All indicators support custom success and error icons:
 
-# Stop with success message
-worm --stop /tmp/progress.pid --message "Deploy complete!" --checkmark
+```bash
+prg ripple "Deploying..." \
+  --command "./deploy.sh" \
+  --success "All systems go!" \
+  --error "Houston, we have a problem" \
+  --success-icon "🚀" \
+  --error-icon "💥" \
+  --checkmark
 ```
 
-This is incredibly useful for complex deployment scripts where you want continuous visual feedback without interrupting the main process.
-
-There's a unified binary called `prg` that takes the three types as subcommands, e.g. `prg twirl --checkmark`. You can use any of them either way.
+### Visual Customization
 
-## Advanced Features
+Ripple supports rainbow colors and multiple composable styles:
 
-### Error Handling
-```ruby
-RubyProgress::Ripple.progress("Risky operation") do
-  might_fail_operation
-rescue StandardError => e
-  # Automatically stops and shows error state
-  puts "Failed: #{e.message}"
-end
+```bash
+prg ripple "Processing" --style rainbow,inverse,caps
 ```
 
-### Command Integration
-```ruby
-# Execute shell commands with progress
-RubyProgress::Worm.new(
-  command: "pg_dump mydb > backup.sql",
-  success: "Backup complete!",
-  error: "Backup failed"
-).run_with_command
-```
+Worm has directional control and custom character sets:
 
-### Visual Customization
-```ruby
-# Rainbow colors and custom styling
-RubyProgress::Ripple.progress("Colorful task",
-  rainbow: true,
-  speed: :fast,
-  format: :forward_only
-) do
-  process_with_style
-end
+```bash
+prg worm --direction rtl --style "custom=🟦🟨🟥"
 ```
 
-## Real-World Examples
+### Start/End Character Decoration
 
-### Deployment Script
+The `--ends` flag lets you wrap your progress indicator with decorative characters:
 
 ```bash
-#!/bin/bash
-worm --daemon-as deploy --message "Deploying..." &
+prg worm --message "Magic" --ends "🎯🎪" --style blocks
+prg ripple "Loading data" --ends "[]" --style rainbow
+```
 
-git push production main
-kubectl rollout status deployment/app
+### Output Capture
 
-worm --stop-id deploy --stop-success "Success!" --checkmark
-```
+When running commands, you can capture and display output:
 
-### Data Processing
-```ruby
-def import_large_csv(file)
-  RubyProgress::Ripple.progress("Importing #{File.basename(file)}...") do
-    CSV.foreach(file, headers: true) { |row| User.create!(row.to_h) }
-  end
-end
-```
+```bash
+# Show command output after completion
+prg ripple "Building..." --command "make build" --stdout
 
-### Rake Tasks
-```ruby
-task :backup do
-  RubyProgress::Worm.new(
-    command: "tar -czf backup.tar.gz app/",
-    success: "Backup created successfully!"
-  ).run_with_command
-end
+# Display live output with reserved terminal rows
+prg worm --command "npm install" --output-lines 5 --output-position above
 ```
+{% endpaywall %}
+
+## Real-World Use Cases
+
+**Deployment Scripts**: Show continuous progress during multi-step deployments
+without blocking command output.
+
+**Data Processing**: Provide visual feedback during long-running data imports or
+transformations.
 
-## Why ruby-progress?
+**Build Systems**: Integrate into Rake or Make tasks to show progress during compilation.
 
-- **Simple API**: Works in Ruby code and shell scripts
-- **Visual Appeal**: Engaging animations beyond basic spinners
-- **Unique Daemon Mode**: Background progress indicators
-- **Production Ready**: 84.55% test coverage, 113 test examples, zero failures
-- **Cross-Platform**: Linux, macOS, Windows support
-- **Reliable**: Comprehensive error handling and edge case coverage
+**CI/CD Pipelines**: Add visual indicators to pipeline scripts for better monitoring.
 
-## Installation & First Steps
+**System Administration**: Show progress during backups, database dumps, or file
+synchronization.
 
-1. **Install**: `gem install ruby-progress`
-2. **Test CLI**: `ripple "Hello World!"`
-3. **Try in Ruby**:
-   ```ruby
-   require 'ruby-progress'
-   RubyProgress::Ripple.progress("Testing...") { sleep 2 }
-   ```
+## Try It Out
 
-## Conclusion
+The easiest way to get started:
 
-Ruby-progress transforms boring CLI applications into engaging user experiences. Whether building deployment scripts, data processing tools, or utility commands, it provides the visual feedback users expect from modern command-line tools.
+{% iterm "gem install ruby-progress" %}
 
-The daemon mode alone makes it worth trying - no other progress library offers this level of flexibility for complex workflows.
+{% iterm "prg ripple 'Hello, World!'" %}
 
-**Links:**
-- [GitHub](https://github.com/ttscoff/ruby-progress)
-- [RubyGems](https://rubygems.org/gems/ruby-progress)
-- [Latest Release](https://github.com/ttscoff/ruby-progress/releases/latest)
+Or check out the [GitHub repository](https://github.com/ttscoff/ruby-progress)
+for full documentation, examples, and the complete API reference. The README
+includes detailed guides for each indicator type and advanced usage patterns.
 
-*Make your CLI tools feel alive with ruby-progress!*
+The gem is also available on
+[RubyGems](https://rubygems.org/gems/ruby-progress), and the latest release
+includes significant improvements to daemon mode handling and job control
+commands.

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

@@ -8,6 +8,11 @@ require_relative 'twirl_runner'
 # Twirl CLI (extracted from bin/prg)
 module TwirlCLI
   def self.run
+    trap('INT') do
+      RubyProgress::Utils.show_cursor
+      exit
+    end
+
     options = TwirlCLI::Options.parse_cli_options
 
     if options[:status]

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

@@ -46,6 +46,11 @@ module TwirlRunner
 
       spinner_thread.kill
       RubyProgress::Utils.clear_line
+    rescue Interrupt
+      spinner_thread&.kill
+      RubyProgress::Utils.clear_line
+      RubyProgress::Utils.show_cursor
+      exit 130
     ensure
       RubyProgress::Utils.show_cursor
     end
@@ -74,6 +79,10 @@ module TwirlRunner
     begin
       RubyProgress::Utils.hide_cursor
       loop { spinner.animate }
+    rescue Interrupt
+      RubyProgress::Utils.clear_line
+      RubyProgress::Utils.show_cursor
+      exit 130
     ensure
       RubyProgress::Utils.show_cursor
       if options[:success] || options[:checkmark]

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

@@ -15,6 +15,11 @@ module WormCLI
   end
 
   def self.run
+    trap('INT') do
+      RubyProgress::Utils.show_cursor
+      exit
+    end
+
     options = WormCLI::Options.parse_cli_options
 
     if options[:status]

data/lib/ruby-progress/version.rb

@@ -2,11 +2,11 @@
 
 module RubyProgress
   # Main gem version
-  VERSION = '1.3.5'
+  VERSION = '1.3.6'
 
   # Component-specific versions (patch bumps)
-  WORM_VERSION = '1.1.5'
-  TWIRL_VERSION = '1.1.5'
-  RIPPLE_VERSION = '1.1.5'
-  FILL_VERSION = '1.0.5'
+  WORM_VERSION = '1.1.6'
+  TWIRL_VERSION = '1.1.6'
+  RIPPLE_VERSION = '1.1.6'
+  FILL_VERSION = '1.0.6'
 end

metadata

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