utils 0.68.0 → 0.69.0

data/bin/rd2md

@@ -1,4 +1,19 @@
 #!/usr/bin/env ruby
+#
+# RDoc to Markdown Converter
+#
+# This script converts RDoc formatted documentation into Markdown format.
+# It reads from standard input (or files passed via ARGF) and outputs
+# the converted Markdown to stdout.
+#
+# Usage: rd2md [input.rdoc] > output.md
+#   or:  cat input.rdoc | rd2md > output.md
+#
+# Features:
+# - Converts RDoc markup syntax to equivalent Markdown
+# - Preserves code blocks, lists, and formatting
+# - Handles standard RDoc elements like headings, emphasis, and links
+# - Streaming conversion for efficient processing of large files
 
 require 'rdoc'
 

data/bin/search

@@ -1,13 +1,39 @@
 #!/usr/bin/env ruby
+#
+# Code Search and Edit Tool
+# 
+# Interactive code search and editing utility that combines grep-like functionality
+# with Vim integration for efficient code navigation and modification.
+#
+# Features:
+# - Search code patterns across files with extensive filtering options
+# - Edit matching files directly in Vim with automatic positioning
+# - Interactive replacement with confirmation prompts
+# - Support for fuzzy matching, regular expressions, and case-insensitive searches
+# - Git integration to show author information
+# - Configurable context display (lines before/after matches)
+#
+# The tool integrates seamlessly with your terminal workflow, allowing you to
+# search code and edit files without touching the mouse.
 
 require 'utils'
 include Utils
-require 'tins/xt'
 include Tins::GO
 require 'term/ansicolor'
 include Term::ANSIColor
 require 'tempfile'
 
+# The convert_ruby_to_vim_regexp method converts a Ruby regular expression
+# pattern to a Vim-compatible regular expression string.
+#
+# This method takes a Ruby regular expression object and transforms it into a
+# format suitable for Vim's regular expression engine.
+# It duplicates the source pattern, escapes standalone question marks, and
+# appends a case folding flag when appropriate.
+#
+# @param pattern [ Regexp ] the Ruby regular expression pattern to convert
+#
+# @return [ String ] the converted Vim-compatible regular expression string
 def convert_ruby_to_vim_regexp(pattern)
   regexp = pattern.source.dup
   regexp.gsub!(/([^\\])\?/, '\1\\?')
@@ -15,6 +41,16 @@ def convert_ruby_to_vim_regexp(pattern)
   regexp
 end
 
+# The read_line method retrieves a specific line from a file based on the
+# source location.
+#
+# This method extracts the filename and line number from the provided path
+# object, then opens the file to lazily iterate through its contents until it
+# finds and returns the line at the specified line number.
+#
+# @param path [ Object] the path object containing source location information
+#
+# @return [ String, nil ] the content of the specified line if found, otherwise nil
 def read_line(path)
   filename, lineno = path.source_location
   File.open(filename) do |file|
@@ -22,6 +58,17 @@ def read_line(path)
   end
 end
 
+# The replace_line method replaces a specific line in a file with a new line
+# content.
+#
+# This method takes a path object that contains source location information,
+# extracts the filename and line number, then opens the file to replace the
+# specified line with the provided new line content. It uses a temporary file
+# to perform the replacement safely without corrupting the original file.
+#
+# @param path [ Object] an object that responds to source_location and provides
+#                       filename and line number information
+# @param new_line [ String ] the new line content that will replace the existing line
 def replace_line(path, new_line)
   filename, lineno = path.source_location
   Tempfile.open do |output|
@@ -43,6 +90,23 @@ def replace_line(path, new_line)
   end
 end
 
+# The replace_ask method guides the user through replacing patterns in a file
+# line by line.
+#
+# It reads a line from the specified path, displays it with highlighted
+# matches, and prompts the user for replacement decisions based on the provided
+# pattern and replacement string.
+# The method supports various user responses to control the replacement
+# process, including replacing individual matches, all matches, editing the
+# file, or quitting.
+#
+# @param editor [ Utils::Editor ] the editor instance used for file editing
+# @param path [ String ] the file path from which to read and replace content
+# @param pattern [ Utils::Patterns::Pattern ] the pattern matcher used to identify content for replacement
+# @param replace [ String ] the string to replace matched content with
+# @param all [ TrueClass, FalseClass ] flag indicating whether to replace all matches immediately
+#
+# @return [ TrueClass, FalseClass ] true if all matches were replaced, false otherwise
 def replace_ask(editor, path, pattern, replace, all)
   line = read_line path
   display_new_line = line.gsub(
@@ -77,6 +141,18 @@ def replace_ask(editor, path, pattern, replace, all)
   end
 end
 
+# The edit_files method opens editor sessions for specified files and applies
+# pattern-based editing operations.
+#
+# This method utilizes an editor instance to open files for editing, applying
+# either replacement operations or interactive selection based on provided
+# parameters. It supports processing multiple paths with optional pattern
+# matching and replacement functionality.
+#
+# @param pattern [ String ] the pattern used for filtering or matching files
+# @param paths [ Array<String> ] the list of file paths to be processed
+# @param pick [ TrueClass, FalseClass ] determines whether to interactively select a file from the paths
+# @param replace [ String, nil ] the replacement string to be applied when performing replacements
 def edit_files(pattern, paths, pick: false, replace: nil)
   editor = Utils::Editor.new
   editor.edit_remote_send("<ESC>/#{convert_ruby_to_vim_regexp(pattern)}<CR>")
@@ -107,6 +183,12 @@ def edit_files(pattern, paths, pick: false, replace: nil)
   end
 end
 
+# 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 and usage patterns for the command-line tool, including pattern
+# matching, file filtering, context display, and search behavior.
 def usage
   puts <<~EOT
     Usage: #{File.basename($0)} [OPTS] PATTERN [PATHS]

data/bin/sedit

@@ -1,3 +1,9 @@
 #!/usr/bin/env ruby
+#
+# Super-user editor launcher - executes 'edit' command with sudo privileges
+# Usage: sedit [FILE...]
+# 
+# This script is a simple wrapper that elevates permissions when editing files,
+# useful for modifying system configuration files or protected resources.
 
 exec 'sudo', 'edit', *$*

data/bin/serve

@@ -1,4 +1,6 @@
 #!/usr/bin/env ruby
+#
+# Launch simple HTTP server for a local directory
 
 require 'tins/go'
 include Tins::GO
@@ -7,9 +9,22 @@ require 'webrick'
 $opts = go 'p:h'
 
 if $opts[?h]
-  puts <<USAGE
-#{File.basename($0)} [OPTIONS] [DIR]
-USAGE
+  puts <<~USAGE
+    #{File.basename($0)} - Launch simple HTTP server for a local directory
+    
+    Usage: #{File.basename($0)} [OPTIONS] [DIR]
+    
+    Options:
+      -p PORT    Specify port number (default: 8888)
+      -h         Show this help message
+    
+    Examples:
+      #{File.basename($0)}                    # Serve current directory on port 8888
+      #{File.basename($0)} -p 3000            # Serve on port 3000
+      #{File.basename($0)} /path/to/dir       # Serve specific directory
+    
+    Note: If no directory is specified, serves the current working directory.
+  USAGE
   exit
 end
 

data/bin/ssh-tunnel

@@ -1,10 +1,14 @@
 #!/usr/bin/env ruby
+#
+# SSH tunnel manager with session and multiplexer support
+#
+# This script manages SSH connections with tunneling capabilities, session
+# management, and terminal multiplexer integration (screen/tmux).
 
 require 'fileutils'
 include FileUtils::Verbose
-require 'tins/xt'
-include Tins::GO
 require 'utils'
+include Tins::GO
 require 'pstree'
 require 'term/ansicolor'
 include Term::ANSIColor
@@ -19,6 +23,8 @@ Host *
   ControlPath ~/.ssh/%r@%h:%p.sock
 SSH_CONFIG_END
 
+# The usage method displays the command-line interface help text and version
+# information.
 def usage
   puts <<~EOT
     Usage: #{File.basename($0)} [OPTS] [user@]remote[:port]"
@@ -39,6 +45,12 @@ def usage
   exit 1
 end
 
+# The cmd method executes a shell command string.
+#
+# This method takes a command string and executes it using the system exec
+# function, replacing the current process with the specified command.
+#
+# @param string [ String ] the shell command to be executed
 def cmd(string)
   $DEBUG and warn "Executing: #{string.inspect}"
   exec string

data/bin/strip_spaces

@@ -1,4 +1,10 @@
 #!/usr/bin/env ruby
+#
+# Strip trailing whitespace from files or stdin
+#
+# This script removes trailing spaces and tabs from files, with optional tab
+# conversion to spaces. It can process directories recursively or read from
+# stdin and write to stdout.
 
 require 'tins/go'
 include Tins::GO
@@ -8,20 +14,22 @@ require 'tins/find'
 include Tins::Find
 require 'utils'
 
+# The usage method displays the help message and version information for the
+# command-line tool.
 def usage
-  puts <<-EOT
-Usage: #{File.basename($0)} [OPTS] [PATHS]
+  puts <<~EOT
+    Usage: #{File.basename($0)} [OPTS] [PATHS]
 
-PATHS are the directory and file paths that are search for files to be
-stripped.
+    PATHS are the directory and file paths that are search for files to be
+    stripped.
 
-Options are
+    Options are
 
-  -t COLUMNS  turn tabs into COLUMNS spaces
-  -I SUFFIXES list of suffixes
-  -h          display this help
+      -t COLUMNS  turn tabs into COLUMNS spaces
+      -I SUFFIX   list of suffixes (can be used multiple times)
+      -h          display this help
 
-Version is #{File.basename($0)} #{Utils::VERSION}.
+    Version is #{File.basename($0)} #{Utils::VERSION}.
   EOT
   exit 1
 end

data/bin/sync_dir

@@ -1,7 +1,31 @@
 #!/usr/bin/env ruby
+#
+# Directory Synchronization Tool
+#
+# This script synchronizes directories with interactive conflict resolution. It
+# compares source and destination directories recursively, showing differences
+# and prompting for actions when conflicts arise.
+#
+# Usage:
+#   sync_dir <source_directory> [<destination_directory>]
+#
+# If destination is not specified, current directory is used.
+#
+# Features:
+# - Interactive file comparison with colored diffs
+# - Support for copying, editing, deleting, or skipping files
+# - Configuration-based skipping of files/directories
+# - Vim integration for editing files
+# - Colorized output using ANSI escape codes
+#
+# Actions available when conflicts are detected:
+# - c: Copy file to destination
+# - e: Edit file with vim
+# - d: Delete file from source
+# - s: Skip (continue with next file)
+# - q: Quit (exit script)
 
 require 'pathname'
-require 'tins/xt'
 require 'fileutils'
 include FileUtils::Verbose
 require 'utils'
@@ -11,16 +35,39 @@ include Term::ANSIColor
 $config = Utils::ConfigFile.new
 $config.configure_from_paths
 
+# The local_path method computes the relative path from the current directory
+# to the specified path.
+#
+# This method takes an absolute or relative path and returns its relative
+# representation with respect to the current working directory.
+#
+# @param path [ String ] the path to be converted to a relative path
+#
+# @return [ String ] the relative path from the current directory to the
+# specified path
 def local_path(path)
   Pathname.new(path).expand_path.relative_path_from(
     Pathname.new(?.).expand_path
   ).to_s
 end
 
+# The diff_dir method compares the contents of two directories recursively.
+#
+# This method executes a shell command to perform a recursive directory
+# comparison between the source and destination paths, reporting differences in
+# files and subdirectories.
+#
+# @return [ String ] the output from the diff command showing directory
+# differences
 def diff_dir
   `diff -rq #{$src.inspect} #{$dst.inspect}`
 end
 
+# The ask? method prompts the user for input and returns the trimmed response.
+#
+# @param prompt [ String ] the message to display to the user
+#
+# @return [ String ] the user's input with leading and trailing whitespace removed
 def ask?(prompt:)
   print prompt
   gets.chomp

data/bin/untest

@@ -1,8 +1,26 @@
 #!/usr/bin/env ruby
+#
+# Untest - Convert Minitest test blocks to standard Ruby methods
+#
+# This script transforms Minitest test definitions from:
+#   test "method name" do
+#     # test code
+#   end
+# 
+# To standard Ruby method definitions:
+#   def test_method_name
+#     # test code
+#   end
+# 
+# Usage:
+#   untest file1.rb file2.rb
+# 
+# The script preserves whitespace and normalizes test names to snake_case
+# format.
 
 require 'tins/xt/secure_write'
 
-for filename in ARGV
+ARGV.each do |filename|
   File.open(filename) do |input|
     File.secure_write(filename) do |output|
       until input.eof?

data/bin/utils-utilsrc

@@ -1,12 +1,27 @@
 #!/usr/bin/env ruby
+#
+# Utils Configuration Manager
+#
+# Manages utility configuration files (~/.utilsrc) with commands to show,
+# diff, edit, and display default configurations.
 
 require 'tempfile'
 require 'utils'
-include Utils
-
-$config = Utils::ConfigFile.new
-$utilsrc = File.expand_path('~/.utilsrc')
 
+# Creates a default utilsrc file by generating configuration content and
+# yielding temporary and source paths.
+#
+# This method checks if a utilsrc file exists at the configured path, and if so,
+# creates a temporary file containing the Ruby representation of the current
+# configuration. It then yields both the temporary file path and the original
+# utilsrc path to the provided block for further processing.
+#
+# @return [ nil ] returns nil if no utilsrc file exists at the configured path
+#
+# @yield [ tmp_path, source_path ]
+#
+# @yieldparam tmp_path [ String ] the path to the temporary file containing configuration
+# @yieldparam source_path [ String ] the path to the original utilsrc file
 def create_default_utilsrc
   if File.exist?($utilsrc)
     Tempfile.open('utilsrc') do |tmp|
@@ -17,6 +32,14 @@ def create_default_utilsrc
   end
 end
 
+$config = Utils::ConfigFile.new
+utilsrc_path = if ARGV.size == 2
+                 ARGV.pop
+               else
+                 '~/.utilsrc'
+               end
+$utilsrc = File.expand_path(utilsrc_path)
+
 case cmd = ARGV.shift
 when 'show'
   if File.exist?($utilsrc)
@@ -28,7 +51,7 @@ when 'default'
   puts $config.to_ruby
 when 'diff'
   create_default_utilsrc do |default_utilsrc, utilsrc|
-    system "diff -u #{default_utilsrc.inspect} #{utilsrc.inspect} | cdiff"
+    system "diff --color=always -u #{default_utilsrc.inspect} #{utilsrc.inspect}"
   end
 when 'edit'
   create_default_utilsrc do |default_utilsrc, utilsrc|
@@ -36,6 +59,19 @@ when 'edit'
   end
 else
   puts <<~EOT
-    Usage: #{File.basename($0)} show|diff|edit
+    Usage: #{File.basename($0)} show|diff|edit|default [UTILSRC]
+
+    Commands:
+
+    show     - Display current ~/.utilsrc file or default config if none exists
+    default  - Show the default Ruby configuration representation
+    diff     - Show differences between current config and default using 'diff'
+    edit     - Open current config in vimdiff to compare with default for editing
+
+
+    Arguments:
+
+    UTILSRC   - Optional path to configuration file (defaults to ~/.utilsrc)
+
   EOT
 end

data/bin/vcf2alias

@@ -1,10 +1,43 @@
 #!/usr/bin/env ruby
 #
+# VCard to Mutt Aliases Converter
+#
+# This script reads a VCard (.vcf) file containing contact information and
+# generates corresponding mutt alias entries in a specified output file.
+# 
+# Features:
+# - Generates unique shorthand identifiers for contact names
+# - Handles multiple email types (HOME, WORK, general)
+# - Supports Unicode characters including German umlauts
+# - Avoids duplicate aliases through intelligent conflict resolution
+# - Automatically resolves symbolic links in output path
+#
+# Usage: vcf2alias [input.vcf] [output.alias]
+#   input.vcf   - VCard file path (defaults to ~/Desktop/Contacts.vcf)
+#   output.alias - Output file path (defaults to ~/.muttrc-aliases)
+#
+# Example output:
+#   alias jsm h-smith <john.smith@company.com>
+#   alias jsmh john.smith <john.smith.home@company.com>
+#   alias jsmw john.smith <john.smith.work@company.com>
+
 require 'tins/xt'
 require 'set'
 
 $shortcuts = Set.new
 
+# The shortcut method generates a unique shorthand identifier for a given
+# function name.
+#
+# This method creates a concise shortcut representation by extracting initial
+# capital letters from the function name and appending an optional suffix.
+# It ensures uniqueness by incrementing a numeric suffix or appending a digit
+# when conflicts are detected in the global shortcuts collection.
+#
+# @param fn [ String ] the full name to generate a shortcut for
+# @param suffix [ String, nil ] an optional suffix to append to the shortcut
+#
+# @return [ String ] the generated unique shortcut identifier
 def shortcut(fn, suffix = nil)
   shortcut = fn.scan(/([A-ZÄÖÜ])[a-zäöü]/).join.downcase
   shortcut.empty? and return fn.gsub(' ', ?_)

data/bin/yaml_check

@@ -1,6 +1,28 @@
 #!/usr/bin/env ruby
-
-require 'yaml'
+#
+# YAML Validator - Checks YAML syntax correctness
+#
+# This script validates YAML files or stdin input for proper syntax.
+# It uses YAML.unsafe_load which can execute arbitrary Ruby code, so
+# use with caution on untrusted input.
+#
+# Usage:
+#   yaml_check <filename>     # Validate a file
+#   cat file.yaml | yaml_check # Validate from stdin
+#
+# Options:
+#   DEBUG=1                     # Enable verbose output with parsed YAML
+#
+# Output:
+#   'ok' - if YAML is valid
+#   'nak' - if YAML is invalid
+#   Error messages to STDERR with line/column information
+#
+# Examples:
+#   ./yaml_check config.yaml
+#   echo "name: John" | ./yaml_check
+#   DEBUG=1 ./yaml_check data.yaml
+#
 
 format = -> s {
   if /^\((?<f>[^)]+)\):\ (?<m>.*?) at line (?<l>\d+) column (?<c>\d+)/ =~ s

data/lib/utils/config_dir.rb

@@ -0,0 +1,127 @@
+require 'pathname'
+require 'stringio'
+
+module Utils
+  class ConfigDir
+    # Initializes a new ConfigDir instance with the specified name and optional
+    # root path or environment variable.
+    #
+    # @param name [ String ] the name of the directory to be used
+    # @param root_path [ String, nil ] the root path to use; if nil, the
+    #                                  default root path is used
+    # @param env_var [ String, nil ] the name of the environment variable to
+    #                                check for the root path
+    def initialize(name, root_path: nil, env_var: nil)
+      root_path ||= env_var_path(env_var)
+      @directory_path = derive_directory_path(name, root_path)
+    end
+
+    # Memoizes the foobar method's return value and returns the result of the computation.
+    # Initializes a new ConfigDir instance with the specified name and optional
+    # root path or environment variable.
+    #
+    # @param name [ String ] the name of the directory to be used
+    # @param root_path [ String, nil ] the root path to use; if nil, the
+    #                                  default root path is used
+    # @param env_var [ String, nil ] the name of the environment variable to
+    #                                check for the root path
+    def initialize(name, root_path: nil, env_var: nil)
+      root_path ||= env_var_path(env_var)
+      @directory_path = derive_directory_path(name, root_path)
+    end
+
+    # Returns the string representation of the configuration directory path.
+    #
+    # @return [ String ] the path of the configuration directory as a string
+    def to_s
+      @directory_path.to_s
+    end
+
+    # Joins the directory path with the given path and returns the combined
+    # result.
+    #
+    # @param path [ String ] the path to be joined with the directory path
+    #
+    # @return [ Pathname ] the combined path as a Pathname object
+    def join(path)
+      @directory_path + path
+    end
+    alias + join
+
+    # Reads the content of a file at the given path within the configuration
+    # directory.
+    #
+    # If the file exists, it returns the file's content as a string encoded in
+    # UTF-8. If a block is given and the file exists, it opens the file and
+    # yields to the block.
+    # If the file does not exist and a default value is provided, it returns
+    # the default. If a block is given and the file does not exist, it yields a
+    # StringIO object containing
+    # the default value to the block.
+    #
+    # @param path [ String ] the path to the file relative to the configuration
+    # directory
+    # @param default [ String, nil ] the default value to return if the file
+    # does not exist
+    #
+    # @yield [ io ]
+    #
+    # @return [ String, nil ] the content of the file or the default value if
+    # the file does not exist
+    def read(path, default: nil, &block)
+      full_path = join(path)
+      if File.exist?(full_path)
+        if block
+          File.new(full_path, &block)
+        else
+          File.read(full_path, encoding: 'UTF-8')
+        end
+      else
+        if default && block
+          block.(StringIO.new(default))
+        else
+          default
+        end
+      end
+    end
+
+    private
+
+    # Derives the full directory path by combining the root path and the given
+    # name.
+    #
+    # @param name [ String ] the name of the directory to be appended to the root path
+    # @param root_path [ String, nil ] the root path to use; if nil, the default root path is used
+    #
+    # @return [ Pathname ] the combined directory path as a Pathname object
+    def derive_directory_path(name, root_path)
+      root = if path = root_path
+               Pathname.new(path)
+             else
+               Pathname.new(default_root_path)
+             end
+      root + name
+    end
+
+    # Returns the environment variable path if it is set and not empty.
+    #
+    # @param env_var [ String ] the name of the environment variable to check
+    # @return [ String, nil ] the value of the environment variable if it
+    # exists and is not empty, otherwise nil
+    def env_var_path(env_var)
+      env_var.full? { ENV[it].full? }
+    end
+
+    # Returns the default configuration directory path based on the HOME
+    # environment variable.
+    #
+    # This method constructs and returns a Pathname object pointing to the
+    # standard configuration directory location, which is typically
+    # $HOME/.config.
+    #
+    # @return [ Pathname ] the default configuration directory path
+    def default_root_path
+      Pathname.new(ENV.fetch('HOME') + '.config')
+    end
+  end
+end