utils 0.68.0 → 0.69.0

data/bin/enum

@@ -1,25 +1,57 @@
 #!/usr/bin/env ruby
+#
+# Range enumerator - Generate combinations from multiple ranges and execute
+# commands
+#
+# Generates cartesian product of ranges and processes each combination.
 
 require 'tins'
 include Tins
 include Tins::GO
 
 class CompoundRange
+  # Initializes a new instance with an empty ranges array.
   def initialize
     @ranges = []
   end
 
+  # The concat method adds a range to the internal ranges collection and
+  # returns the instance for chaining.
+  #
+  # @param range [ Object ] the range to be added to the collection
+  #
+  # @return [ self ] the instance itself, enabling method chaining
   def concat(range)
     @ranges << range
     self
   end
 
+  # The each method iterates over each range in the instance's ranges
+  # collection and yields each element to the provided block.
+  #
+  # This method delegates the iteration to each range object in the @ranges
+  # collection, allowing the block to be executed for every element contained
+  # within these ranges.
+  #
+  # @yield [ element ]
+  #
+  # @return [ nil ] returns nil after completing the iteration over all ranges
   def each(&block)
     @ranges.each { |r| r.each(&block) }
   end
 end
 
 class Step
+  # Initializes a new Range instance with the specified parameters.
+  #
+  # This method sets up the internal state of a Range object by storing the
+  # start value, end value, step size, and exclusive flag. It also adjusts the
+  # end value when the range is exclusive to ensure proper iteration behavior.
+  #
+  # @param a [ Object ] the starting value of the range
+  # @param b [ Object ] the ending value of the range
+  # @param step [ Object ] the step size for incrementing through the range
+  # @param exclusive [ TrueClass, FalseClass ] whether the range excludes the end value
   def initialize(a, b, step = 1, exclusive = false)
     @a = a
     @b = b
@@ -33,12 +65,33 @@ class Step
     end
   end
 
+  # The each method iterates over a range of values using a step increment.
+  #
+  # This method executes a block for each value in the range from @a to @b,
+  # incrementing by @step each time. It provides a way to perform operations
+  # on a sequence of numbers with a specified increment.
+  #
+  # @param block [ Proc ] the block to be executed for each value in the range
+  #
+  # @return [ Integer ] the final value of the iteration
   def each(&block)
     @a.step(@b, @step, &block)
   end
 end
 
 class StringRange
+  # Initializes a new Range instance with the specified bounds and exclusivity.
+  #
+  # This method creates a range object by determining the appropriate bounds
+  # based on the relationship between the first and second parameters. It
+  # handles both inclusive and exclusive range creation, supporting reverse
+  # ordering of bounds.
+  #
+  # @param a [ Integer ] the first boundary value of the range
+  # @param b [ Integer ] the second boundary value of the range
+  # @param exclusive [ TrueClass, FalseClass ] whether the range should be exclusive
+  #
+  # @return [ Range ] a new Range instance with the specified parameters
   def initialize(a, b, exclusive = false)
     @range = if a > b
       if exclusive
@@ -51,12 +104,33 @@ class StringRange
     end
   end
 
+  # The each method iterates over the range and yields each element to the
+  # provided block.
+  #
+  # @yield [ element ]
+  #
+  # @return [ nil ] returns nil after completing the iteration
+  def each(&block)
+    @range.each(&block)
+  end
   def each(&block)
     @range.each(&block)
   end
 end
 
 class IntegerRange < Step
+  # Initializes a new instance with the specified parameters and sets up
+  # internal state.
+  #
+  # This method configures the object's internal attributes based on the
+  # provided arguments and initializes the parent class with computed values.
+  # It handles parameter validation and setup for exclusive access scenarios.
+  #
+  # @param a [ Object ] the first parameter used in initialization
+  # @param b [ Object ] the second parameter used in initialization
+  # @param exclusive [ TrueClass, FalseClass ] flag indicating whether exclusive access should be enabled
+  #
+  # @return [ void ] returns nil after initialization is complete
   def initialize(a, b, exclusive = false)
     @a = a
     @b = b
@@ -64,6 +138,16 @@ class IntegerRange < Step
   end
 end
 
+# The parse_range method converts a range string into a range object.
+#
+# This method handles various range formats including single numbers, 
+# number ranges, string ranges, and stepped ranges.
+# It parses the input string and returns the appropriate range object
+# based on the format encountered.
+#
+# @param range [ String ] the range string to be parsed
+#
+# @return [ Object ] a range object corresponding to the parsed string
 def parse_range(range)
   case range
   when /,/
@@ -91,21 +175,44 @@ def parse_range(range)
   end
 end
 
+# The parse_ranges method processes a pattern string by splitting it on colons
+# and parsing each resulting range component.
+#
+# This method takes a pattern string, splits it into individual range
+# components using colons as delimiters, and then parses each component into a
+# structured format using the parse_range helper method.
+#
+# @param pattern [ String ] the pattern string containing ranges separated by colons
+#
+# @return [ Array<Object> ] an array of parsed range objects resulting from
+# splitting and parsing the input pattern
 def parse_ranges(pattern)
   pattern.split(/:/).map { |range| parse_range(range) }
 end
 
+# The execute_command method formats a command string with provided arguments
+# and executes it.
+#
+# This method takes a command template, a format string, and a tuple of values
+# to be inserted into the command. It processes the format string with the
+# tuple values, splits the result by colons, and then executes the system
+# command with the formatted arguments.
+#
+# @param command [ String ] the command template string with format placeholders
+# @param format [ String ] the format string used to process the tuple values
+# @param tuple [ Array ] the array of values to be inserted into the formatted command
+#
+# @return [ Boolean ] returns the result of the system command execution
 def execute_command(command, format, tuple)
   formatted = (format % tuple).split(/:/)
-  if $limited
-    $limited.execute do
-      system sprintf(command, *formatted)
-    end
-  else
-    system sprintf(command, *formatted)
-  end
+  system sprintf(command, *formatted)
 end
 
+# The usage method displays the help message and exits the program.
+#
+# This method prints a detailed usage message to the standard output,
+# explaining how to use the command-line tool, including information
+# about valid range specifications and available options.
 def usage
   puts <<EOT
 Usage: #{File.basename($0)} [OPTIONS] RANGES
@@ -146,22 +253,39 @@ EOT
   exit 1
 end
 
+argv, rest = ARGV.partition { _1 =~ /\A-\d/ }
 $opts = {
-}.update(go('p:e:f:h')) do |o,default,set|
+}.update(go('p:e:f:h', rest)) do |o,default,set|
   set || default
 end
-usage if $opts[?h] || ARGV.size != 1
-$ranges = ARGV.shift
+ranges = argv + rest
+usage if $opts[?h] || ranges.size != 1
+$ranges = ranges.shift
 $limited = $opts[?p] ? Limited.new($opts[?p]) : nil
 ranges = parse_ranges($ranges)
 generator = Generator.new(ranges)
 $opts[?f] ||= %w[ %s ] * generator.size * ':'
 
-generator.each do |tuple|
-  if $opts[?e]
-    execute_command($opts[?e], $opts[?f], tuple)
-  else
-    puts $opts[?f] % tuple
+if $limited
+  $limited.process do |l|
+    generator.each do |tuple|
+      l.execute do
+        if $opts[?e]
+          execute_command($opts[?e], $opts[?f], tuple)
+        else
+          puts $opts[?f] % tuple
+        end
+      end
+    end
+    $limited.stop
+  end
+else
+  generator.each do |tuple|
+    if $opts[?e]
+      execute_command($opts[?e], $opts[?f], tuple)
+    else
+      puts $opts[?f] % tuple
+    end
   end
 end
 exit 0

data/bin/git-empty

@@ -1,10 +1,60 @@
 #!/usr/bin/env ruby
+#
+# git-empty - Reset git repository to empty state on specified branch
+#
+# WARNING: This command permanently deletes ALL commit history and untracked
+# files from the current repository. Use with extreme caution.
+#
+# Usage:
+#   git-empty <branch_name>
+#
+# Examples:
+#   git-empty feature/new # Reset to empty feature branch
+#
+# This command:
+# 1. Sets HEAD to point to a new branch reference
+# 2. Removes the Git index (staging area)
+# 3. Cleans all untracked files and directories
+#
+# The repository will be left in a completely fresh state with no history.
 
 require 'fileutils'
 include FileUtils
 
 name = ARGV.shift or fail 'require a branch name'
 
+puts <<~EOT
+  WARNING: This will reset the current repository to empty state on branch '#{name}'
+  This will DELETE ALL commit history and untracked files!
+  Are you absolutely sure? (y/N): 
+EOT
+
+unless gets =~ /\Ay/i
+  puts "Operation cancelled."
+  exit 0
+end
+
+system "git symbolic-ref HEAD refs/heads/#{name}"
+rm '.git/index'
+system 'git clean -fdx'
+```
+
+require 'fileutils'
+include FileUtils
+
+name = ARGV.shift or fail 'require a branch name'
+
+puts <<~EOT
+  WARNING: This will reset the current repository to empty state on branch '#{name}'
+  This will DELETE ALL commit history and untracked files!
+  Are you absolutely sure? (y/N): 
+EOT
+
+unless gets =~ /\Ay/i
+  puts "Operation cancelled."
+  exit 0
+end
+
 system "git symbolic-ref HEAD refs/heads/#{name}"
 rm '.git/index'
 system 'git clean -fdx'

data/bin/git-versions

@@ -1,4 +1,24 @@
 #!/usr/bin/env ruby
+#
+# Git versions - Generate changelog from Git tags
+#
+# Usage: git-versions [OPTIONS]
+#
+# Displays git log history between version tags in semantic order.
+# Version tags are matched using regex pattern /^v((?:\d+\.)*\d+)/
+# by default, or custom pattern via GIT_VERSIONS_REGEXP environment variable.
+#
+# Options:
+#   Any git log arguments supported (e.g., --oneline, --stat, --since)
+#
+# Examples:
+#   git versions                    # Show colorized changelog with stats
+#   git versions --oneline          # Show compact format
+#   git versions --since="2023-01-01"  # Filter by date
+#   GIT_VERSIONS_REGEXP='^release-(\d+\.\d+\.\d+)$' git versions
+#
+# Shows version headers in red/bold with git log output between each version
+# pair.
 
 require 'tins'
 require 'term/ansicolor'

data/bin/json_check

@@ -1,10 +1,24 @@
 #!/usr/bin/env ruby
+#
+# JSON validator - Check if input is valid JSON
+#
+# Usage: json_check [FILE]
+#
+# Validates JSON from stdin or specified file. Exits with:
+#   0 - Valid JSON
+#   1 - Invalid JSON (with error details on stderr)
+#
+# Examples:
+#   echo '{"key": "value"}' | json_check     # Validate stdin
+#   json_check data.json                     # Validate file
+#   json_check < data.json                   # Validate with input redirection
 
 require 'json'
 
 begin
   JSON.parse(ARGF.read)
   exit 0
-rescue JSON::ParserError
+rescue JSON::ParserError => e
+	STDERR.puts "#{e.class}: #{e}"
   exit 1
 end

data/bin/long_lines

@@ -1,4 +1,13 @@
 #!/usr/bin/env ruby
+#
+# Find lines exceeding maximum length threshold with author attribution
+# Usage: #{File.basename($0)} [OPTIONS] [FILES]
+# Options:
+#   -m NUM  Maximum line length (default: 80)
+#   -h      Show this help message
+#
+# Outputs tab-separated data: AUTHOR\tLINE_LENGTH\tFILE:LINE_NUMBER
+# for each line longer than the specified threshold.
 
 require 'tins/go'
 include Tins::GO
@@ -17,9 +26,9 @@ max = ($opts[?m] || 80).to_i
 
 files = ARGV
 
-for file in files
+files.each do |file|
   File.open(file) do |f|
-    for line  in f
+		f.each do |line|
       size = line.size
       if size > max
         lineno = f.lineno

data/bin/myex

@@ -1,12 +1,41 @@
 #!/usr/bin/env ruby
 # vim: set ft=ruby et sw=2 ts=2:
 # encoding: ascii-8bit
+#
+# MySQL Backup Parser/Processor
+#
+# Parses and processes MySQL dump files with various operations including
+# listing tables, creating table statements, truncating tables, inserting data,
+# replacing records, and searching patterns.
+#
+# Usage:
+#   myex list|create|truncate|insert|replace|search [OPTION] [TABLES]
+#
+# Commands:
+#   list        Display all tables in the backup
+#   create      Display CREATE TABLE statements (use -d to drop tables first)
+#   truncate    Truncate tables (use -t to truncate before insert)
+#   insert      Extract INSERT statements (use -i to add IGNORE, -t to truncate)
+#   replace     Convert INSERT to REPLACE statements
+#   search      Search pattern in INSERT statements with context (-p PATTERN -C NUMBER)
+#
+# Options:
+#   -d          Drop table before creation
+#   -t          Truncate table before insert
+#   -i          Add IGNORE to INSERT statements
+#   -p PATTERN  Pattern for search command
+#   -C NUMBER   Context size for search command
+#
+#
+# The script processes stdin as MySQL dump content and outputs processed statements.
 
 require 'tins/go'
 include Tins::GO
 require 'term/ansicolor'
 include Term::ANSIColor
 
+# The usage method displays the command-line interface help text and exits the
+# program.
 def usage
   puts <<EOT
 Usage: #{File.basename($0)} list|create|truncate|insert|replace|search [OPTION] [TABLES]
@@ -40,6 +69,15 @@ EOT
   exit 1
 end
 
+# The bell method outputs a bell character followed by a backspace character
+# multiple times. It pauses between each output based on the specified sleep
+# duration.
+#
+# @param n [ Integer ] the number of times to output the bell and backspace
+# characters @param s [ Float ] the sleep duration in seconds between each
+# output
+#
+# @return [ Integer ] returns the number of iterations performed
 def bell(n = 1, s = 1)
   n.times do
     STDERR.print "\a\b"

data/bin/on_change

@@ -1,5 +1,27 @@
 #!/usr/bin/env ruby
+#
+# Monitor file for changes and execute command when modified
+#
+# Usage:
+#   on_change filename [command...]    # Watch file and run command on changes
+#
+# This script monitors a file for modifications and executes a specified
+# command whenever the file is changed. It can be used for auto-reloading,
+# rebuilding, or triggering actions when source files are updated.
+#
+# If no command is provided, 'true' is executed by default.
+#
+# Special replacement:
+#   %f in command will be replaced with the filename being monitored
+#
+# Examples:
+#   on_change Gemfile bundle install
+#   on_change tests/utils_test.rb ruby -I lib:tests %f
 
+# The execute method runs a command by processing its arguments and displaying
+# the output.
+#
+# @param args [ Array ] the command arguments to be executed
 def execute(*args)
   cmd = args.map(&:inspect) * ' '
   puts "Executing: #{cmd}"

data/bin/path

@@ -1,4 +1,25 @@
 #!/usr/bin/env ruby
+#
+# PATH manager - Manipulate environment PATH variable
+#
+# Usage: path COMMAND [OPTIONS] [ARGUMENTS]
+#
+# Commands:
+#   prefix PATH_PART    Add path part to beginning of PATH
+#   postfix PATH_PART   Add path part to end of PATH
+#   list                Display current PATH
+#   edit                Edit PATH in external editor
+#
+# Options:
+#   -e                  Output as 'export PATH=...' for shell integration
+#
+# Examples:
+#   path prefix /usr/local/bin     # Add to beginning
+#   path postfix ~/bin             # Add to end
+#   path list                      # Show current PATH
+#   path edit                      # Edit PATH in editor
+#
+# Note: PATH entries are automatically expanded and deduplicated.
 
 require 'tins/go'
 include Tins::GO

data/bin/print_method

@@ -1,4 +1,32 @@
 #!/usr/bin/env ruby
+#
+# Method Printer Tool
+#
+# Extracts and prints complete method definitions from Ruby source files based
+# on line number references. Takes filename:line_number input and outputs the
+# full method body including surrounding whitespace and indentation.
+#
+# Usage:
+#   print_method [FILENAME:LINE_NUMBER]...
+#
+# Examples:
+#   print_method file.rb:42
+#   echo "file.rb:42" | print_method
+#
+# Features:
+# - Parses Ruby method definitions by line number
+# - Preserves original indentation and formatting
+# - Handles nested methods and complex indentation
+# - Works with both command-line arguments and stdin input
+# - Uses Tins::LinesFile for efficient line-based file access
+#
+# The tool identifies method boundaries by looking for:
+# - Opening 'def' statement with proper indentation
+# - Closing 'end' statement at the same indentation level
+# - Preserves all original formatting including whitespace
+#
+# This is particularly useful for extracting method definitions from large
+# codebases or when debugging specific method implementations.
 
 require 'utils'
 
@@ -7,7 +35,7 @@ inputs = ARGV.empty? ? STDIN : ARGV
 inputs.each do |filename_linenumber|
   source_location = filename_linenumber.source_location
   lf = Tins::LinesFile.for_filename(source_location.filename, source_location.linenumber)
-  if spaces = lf.match_backward(/^(\s*)def\s+(?:\S+?)(?:\(|\s*$)/)&.first
+  if spaces = lf.match_backward(/^(\s*?)(\S.*?\s+)?def\s+/)&.first
     line_number_begin = lf.line_number
     lf.match_forward(/^#{spaces}end/)
     line_number_end = lf.line_number

data/bin/probe

@@ -1,12 +1,29 @@
 #!/usr/bin/env ruby
+#
+# Probe test runner and server management tool
+#
+# This utility provides comprehensive testing capabilities with support for
+# multiple test frameworks (RSpec, Test::Unit, Cucumber) and triggering test
+# runs via probe -c client.
+#
+# Features:
+# - Run specific tests by name or file
+# - Start/connect to probe servers for testing/env setting.
+# - Environment variable management on probe servers
+# - Automatic framework detection and configuration
 
-require 'tins/xt'
-require 'tins/lines_file'
-include Tins::GO
 require 'utils'
 include Utils
+include Tins::GO
 require 'shellwords'
 
+# The usage method displays the command-line interface help text and version
+# information.
+#
+# This method outputs a formatted help message that describes the available
+# options for the command-line tool, including test execution parameters, probe
+# server controls, and environment variable management. It also shows the
+# current version of the tool.
 def usage
   puts <<~EOT
     Usage: #{File.basename($0)} [OPTS] [FILENAME[:LINENO]]
@@ -25,21 +42,52 @@ def usage
   exit 1
 end
 
+# The cmd method executes a system command with bundle exec prefix.
+#
+# This method prepares and runs a system command by prepending 'bundle' and
+# 'exec' to the provided arguments. It prints the joined command to stdout
+# before execution and exits the current process with the command's exit status
+# if it fails.
+#
+# @param args [ Array<String> ] the command arguments to be executed
 def cmd(*args)
   args.unshift 'bundle', 'exec'
   puts Shellwords.join(args)
   system(*args) or exit $?.exitstatus
 end
 
-def find_cmd(*cmds, on_fail: -> *cmds { raise fail "no #{cmds * '|'} command found" })
+# The find_cmd method searches for the first available command in a list of
+# candidates.
+#
+# It attempts to locate executable commands by checking their availability in
+# the system path. The method returns the first successfully found command or
+# executes a fallback block if none are found.
+#
+# @param cmds [ Array<String> ] an array of command names to search for
+# @param on_fail [ Proc ] a block to execute if no commands are found
+#
+# @return [ String, Object ] the first found command string or the result of the fallback block
+def find_cmd(*cmds, on_fail: -> *cmds { fail "no #{cmds * '|'} command found" })
   cmds.map { |c| `which #{c}`.full?(:chomp) }.compact.first or on_fail.(*cmds)
 end
 
+# The start_server method initializes and begins operation of a probe server.
+#
+# This method configures the environment for server operation by setting the
+# thread abort behavior based on the debug flag, then creates and starts a new
+# probe server instance to handle incoming requests and process jobs.
 def start_server
   Thread.abort_on_exception = $DEBUG
   Utils::ProbeServer.new.start
 end
 
+# The connect_server method establishes a connection to a probe server and
+# handles environment variable operations.
+#
+# This method initializes a probe client and processes command-line options for
+# setting or retrieving environment variables.
+# It also enqueues jobs for execution on the probe server when specified.
+#
 def connect_server
   probe_client = ProbeClient.new
   if setting = $opts[?C]

data/bin/rainbow

@@ -1,10 +1,50 @@
 #!/usr/bin/env ruby
+#
+# rainbow - Create colorful ASCII art with Figlet fonts
+#
+# This script generates rainbow-colored ASCII text using Figlet fonts. It
+# takes input text and converts it to colorful ASCII art by applying
+# alternating colors (red, yellow, green, cyan, blue, magenta) to each line.
+#
+# Usage:
+#   rainbow "Hello World"           # Basic usage with text argument
+#   echo "Hello" | rainbow          # Read from stdin
+#   rainbow                         # Defaults to "ruby X.X.X"
+#
+# Requirements:
+#   - figlet installed in PATH
+#
+# The script automatically discovers Figlet fonts in the system installation
+# directory and provides helpful error messages when fonts are not found.
+#
+# Examples:
+#   rainbow "Welcome" small
+#   rainbow "Ruby" big
+#   echo    "World" | rainbow slant
 
 require 'figlet'
 require 'term/ansicolor'
 include Term::ANSIColor
 
+# The fetch_font method retrieves a Figlet font by name.
+#
+# This method attempts to locate and load a Figlet font file based on the
+# provided font name. It first checks if figlet is available in the system
+# path, and exits if it's not found.
+# The method then constructs the appropriate font file path by checking for the
+# font in the current directory or searching within the figlet installation
+# directory. If the font cannot be found, it lists all available fonts and
+# exits with an error message.
+#
+# @param font_name [ String ] the name of the font to fetch
+#
+# @return [ Figlet::Font ] a new Figlet::Font object initialized with the found
+# font file path
 def fetch_font(font_name)
+  if `which figlet`.empty?
+    STDERR.puts "Require figlet to be in path, please install it."
+    exit 1
+  end
   font_name += ".flf" unless font_name.end_with?(".flf")
 
   font_path =
@@ -24,6 +64,18 @@ def fetch_font(font_name)
   Figlet::Font.new(font_path)
 end
 
+# The create_rainbow_ascii method generates colored ASCII art text using a
+# specified color palette.
+#
+# This method takes an input text string and converts it into rainbow-colored
+# ASCII art by applying different colors to each line of the art. It utilizes a
+# predefined set of colors that cycle through the available color options to
+# create a vibrant visual effect.
+#
+# @param text [ String ] the input text to be converted into ASCII art
+#
+# @return [ String ] the colored ASCII art text with rainbow coloring applied
+# to each line
 def create_rainbow_ascii(text)
   ascii_art = $t[text]