utils 0.68.0 → 0.69.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9614b9a971f130099440edb6a8a73621898e9e7a4ce8d97c79350fef531db772
-  data.tar.gz: 8cb380f6c71ac83d9dfa4e6a7a4d1423db5191f7ee73b1e3460c44bf030b778c
+  metadata.gz: 85f412311ef245615fb822299605146a2b1fe3c6a678b7c4826bfda8c7f80e78
+  data.tar.gz: 0af45f306f2115ccb6b2a508d7d206a19d8433305d88e9d4b36da3d362edbae3
 SHA512:
-  metadata.gz: ce20e8f6e063c20a46d49ddffa09c42a4bc79f1bdec21c3e384d94a4bceaf097119737fafa7fde02a295412e80622e6c17f8161a0258d64697a4d9f377c73189
-  data.tar.gz: f68fbe751a246b259ebedba01efad3e6cb0c729e5f75cb80fa93a1e758c1df20d00ab3275b414b90ca236d5cff5a1ef3a9f8676a0bc1b29c5855b362e861d3ab
+  metadata.gz: 5b72e6f84ed6945c7dcc29ce430385c29fe5f91ff27a5ddeff394e09a0c43324845677a775311cd67059507918a3080699b78d9c1828c132d439a4055103881e
+  data.tar.gz: 26f68d486605ae78883a3dd6589517e80351f186efb17e4be12946b18d2fbdbd870276f89ee68e08f8eb1f21ff0958cc7ff7b100ab709ae7a128ac475ca0208a

data/README.md

@@ -1,27 +1,260 @@
-# Utils - Some useful command line utilities
+# 📦 Utils - Developer Productivity Command-Line Utilities
 
-## Description
+## 📝 Description
 
-This ruby gem provides some useful command line utilities.
+This Ruby gem delivers a curated collection of command-line utilities designed
+to streamline software development workflows and automate repetitive tasks. The
+toolkit spans multiple domains including code analysis, testing automation,
+file manipulation, and system administration.
 
-## Author
+### Key Features
 
-Florian Frank <mailto:flori@ping.de>
+- **Ruby-Centric Approach**: Built leveraging Ruby's expressive syntax,
+  metaprogramming capabilities, and dynamic nature
+- **Multi-Functional Tools**: From simple CLI interfaces to sophisticated
+  automation workflows
+- **Modern Integration**: Seamlessly integrates with popular development
+  frameworks, external services (including LLMs via Ollama), and system tools
+- **Modular Architecture**: Lightweight design allowing selective tool usage
+  without heavy dependencies
+- **Composability**: Tools designed to work together or independently
 
-## License
+### Technical Approach
 
-This is free software; you can redistribute it and/or modify it under the
-terms of the GNU General Public License Version 2 as published by the Free
-Software Foundation: www.gnu.org/copyleft/gpl.html
+The utilities embrace Ruby's strengths through:
+- Dynamic method dispatch and metaprogramming techniques
+- Expressive DSLs for configuration and tool definition
+- Seamless integration with Git, vim, SSH, and terminal multiplexers
+- Performance-conscious design with pattern matching for pruning operations
 
-## TODO
+## 🛠️ Installation
 
-- add script to fetch ci spec failures and create an error list
-- improve backup mechanism for new configuration, interactivity?
+Add this gem to your Gemfile:
 
-_CHECK_
-- When finding many places in the same file only jump to the first occurence if
-  a cli option is given.
-- Make it configurable to find the same file many times via different symlinks
-  or to find it only once.
-- Stop finder from going in infinite symlink circles
+```ruby
+gem 'utils'
+```
+
+And install it using Bundler:
+
+```bash
+bundle install
+```
+
+Or install the gem directly:
+
+```bash
+gem install utils
+```
+
+## 🧰 Utilities
+
+### 🔍 Searching
+
+- **`blameline`** - Show git blame line for a file and line number
+- **`create_cstags`** - Create cscope tags file for current directory
+- **`create_tags`** - Create ctags tags file for current directory  
+- **`discover`** - Find files with specific content patterns
+- **`git-versions`** - Show git versions of files and directories
+- **`long_lines`** - Finds long lines with author attribution
+- **`search`** - Search for text in files recursively
+
+### ✍️ Editing
+
+- **`classify`** - Classify files by type using file command
+- **`edit_wait`** - Edit a file and wait for changes to be saved
+- **`edit`** - Edit a file using default editor
+- **`print_method`** - Extracts complete method definitions from Ruby source
+  files
+- **`sedit`** - Edit a file with sed commands
+- **`strip_spaces`** - Removes trailing whitespace with tab conversion options
+- **`sync_dir`** - Sync directories with rsync
+- **`untest`** - Remove test files from current directory
+
+### 🧪 Testing
+
+- **`json_check`** - Validate JSON syntax in files
+- **`on_change`** - Monitors files for changes and executes commands
+- **`probe`** - Test runner supporting RSpec, Test::Unit, Cucumber with
+  server/client functionality
+- **`yaml_check`** - Validate YAML syntax in files
+
+### 📚 Documenting
+
+- **`changes`** - Generate changelogs using Git history and LLM summaries
+- **`code_comment`** - Generates YARD documentation using LLM assistance
+- **`commit_message`** - Generate commit messages via LLM from git diff
+- **`rd2md`** - Convert RDoc to Markdown
+
+### ⚙️ Configuring
+
+- **`git-empty`** - Create empty git repository with default files
+- **`myex`** - Processes MySQL dump files (list, create, truncate, insert,
+  search)
+- **`path`** - Show or modify PATH environment variable
+- **`utils-utilsrc`** - Manages `~/.utilsrc` configuration file with
+  show/diff/edit capabilities
+- **`vcf2alias`** - Converts VCard contacts to Mutt email aliases
+
+### 🌐 Networking
+
+- **`serve`** - Simple HTTP server launcher
+- **`ssh-tunnel`** - Create SSH tunnel to remote host
+
+### 🎨 Slacking
+
+- **`ascii7`** - Generate ASCII art from text
+- **`enum`** - Enumerate files and directories with line counts
+- **`rainbow`** - Display rainbow-colored banner text
+
+## ⚙️ Configuration
+
+The `~/.utilsrc` configuration file uses Ruby syntax to define settings for
+various utility components. This file allows you to customize the behavior of
+different utilities without modifying their source code.
+
+Each configuration block corresponds to a specific utility or category of
+utilities. The settings within each block control how those utilities behave
+during execution. The configuration system supports:
+
+- **Pattern matching**: Regular expressions for including/excluding files and
+  directories
+- **Performance optimization**: Caching mechanisms and pruning rules to avoid
+  unnecessary processing
+- **Integration capabilities**: Settings for connecting with external tools
+  like SSH, vim, and terminal multiplexers
+- **Environment customization**: Ability to set environment variables and
+  default paths
+
+The configuration is loaded at runtime and can be modified without requiring a
+restart of the utilities. Changes take effect immediately for subsequent
+operations.
+
+⚠️ **Important Note**: Since this is Ruby syntax, you have access to full Ruby
+capabilities within the configuration blocks. You can use variables, methods,
+conditional logic, and other Ruby features to create dynamic configurations
+when needed.
+
+```ruby
+# vim: set ft=ruby:
+
+# ~/.utilsrc - Utility configuration file
+# This file contains configuration settings for various utility components
+
+## Search Configuration
+search do
+  # Directories to prune during search operations
+  # These are excluded from the search scope to improve performance
+  prune_dirs /\A(\.svn|\.git|\.terraform|CVS|tmp|coverage|corpus|pkg|\.yardoc)\z/
+  
+  # Files to skip during search operations
+  # Excludes temporary files, log files, and system files
+  skip_files /(\A\.|\.sw[pon]\z|\.(log|fnm|jpg|jpeg|png|pdf|svg)\z|\Atags\z|~\z)/i
+end
+
+## Discovery Configuration
+discover do
+  # Directories to prune during discovery operations
+  # Excludes version control systems, temporary directories, and build artifacts
+  prune_dirs /\A(\.svn|\.git|\.terraform|\.yardoc|CVS|tmp|coverage|corpus|pkg|\.yardoc)\z/
+  
+  # Files to skip during discovery operations
+  # Excludes hidden files, swap files, and log files
+  skip_files /(\A\.|\.sw[pon]\z|\.log\z|~\z)/
+  
+  # Cache index expiration time in seconds (1 hour = 3600 seconds)
+  index_expire_after 3_600
+
+  # Maximum number of matches to return (0 = no limit)
+  # Prevents overwhelming output when many files match the search criteria
+  max_matches 10
+end
+
+## Space Stripping Configuration
+strip_spaces do
+  # Directories to prune during space stripping operations
+  # Excludes hidden directories and system directories
+  prune_dirs /\A(\..*|CVS|pkg|\.yardoc)\z/
+  
+  # Files to skip during space stripping operations
+  # Excludes hidden files, swap files, and log files
+  skip_files /(\A\.|\.sw[pon]\z|\.log\z|~\z)/
+end
+
+## Probe Configuration
+probe do
+  # Test framework to use for probing
+  test_framework :'test-unit'
+  
+  # Directories to include in probe operations
+  # Specifies where to look for test files and source code
+  include_dirs %w[lib test tests ext spec]
+end
+
+## SSH Tunnel Configuration
+ssh_tunnel do
+  # Terminal multiplexer to use (supports :tmux or other terminal managers)
+  terminal_multiplexer :tmux
+  
+  # Login session path for SSH connections
+  login_session "/home/#{ENV['USER']}"
+  
+  # Environment variables to set for the tunnel
+  env(
+    FOO: 'test'  # Example environment variable - adjust as needed
+  )
+  
+  # Enable or disable copy/paste functionality
+  copy_paste true do
+    # Bind address for the tunnel
+    bind_address 'localhost'
+    
+    # Port number for the tunnel
+    port 6166
+    
+    # Host for the tunnel
+    host 'localhost'
+    
+    # Host port for the tunnel
+    host_port 6166
+  end
+end
+
+## Classification Configuration
+classify do
+  # Default path shifting value (1 = shift by one directory level)
+  shift_path_by_default 1
+  
+  # Path prefixes to check in order for classification
+  # Used to determine how paths should be shifted or categorized
+  shift_path_for_prefix [ # prefixes checked in order
+    'a/b',
+    'c/d/e',
+  ]
+end
+
+## Sync Directory Configuration
+sync_dir do
+  # Paths to skip during sync operations
+  # Uses regex pattern to exclude certain directory patterns
+  skip_path %r((\A|/)\.\w)
+end
+
+## Edit Configuration
+edit do
+  # Path to vim executable
+  # Uses shell command to find vim in PATH
+  vim_path `which vim`.chomp
+  
+  # Default arguments for vim (nil = no default args)
+  vim_default_args nil
+end
+```
+
+## 👨‍💻 Author
+
+[Florian Frank](mailto:flori@ping.de)
+
+## 📄 License
+
+GPLv2 [LICENSE](./LICENSE)

data/bin/ascii7

@@ -1,4 +1,32 @@
 #!/usr/bin/env ruby
+#
+# This script generates a visual representation of how 7-bit ASCII characters #
+# are interpreted when the upper 2 bits (prefix) are varied while keeping the
+# lower 5 bits constant. It demonstrates the relationship between binary
+# patterns and character representations in classic ASCII encoding.
+#
+# The output shows:
+# - First column: Lower 5 bits of ASCII values (0-31 in binary)
+# - Remaining columns: Character names for each prefix combination (00, 01, 10, 11)
+#   where prefix + lower_bits = full 7-bit ASCII value
+#
+# This reveals how early computer systems treated the same bit patterns differently
+# depending on context or system interpretation, and illustrates the evolution
+# from control characters to printable ASCII ranges.
+#
+# The script uses bit manipulation: (prefix << 5) | lower_bits
+# to generate all 32 combinations of the lower 5 bits with 4 possible prefixes.
+#
+# This demonstrates fundamental concepts in computer science:
+# - Bit-level character encoding
+# - Historical ASCII design principles  
+# - Binary representation and manipulation
+# - Control character vs printable character distinctions
+#
+# References:
+# - Original 7-bit ASCII standard
+# - Early computer system character set conventions
+# - Bit manipulation in low-level programming
 
 map = Hash.new { |h, k| h[k] = k }.merge(
   " "    => "Spc",

data/bin/blameline

@@ -1,4 +1,21 @@
 #!/usr/bin/env ruby
+#
+# Line blamer - Show Git blame information for lines or files
+#
+# Usage: blameline [OPTIONS] [LINES|FILES]
+#
+# Displays Git blame information for specified lines or files.
+#
+# Options:
+#   -s    Read lines from stdin instead of command-line arguments
+#   -h    Show this help message
+#
+# Examples:
+#   blameline file.rb:23                 # Blame all lines in file
+#   blameline -s < lines.txt             # Blame lines from stdin
+#   echo some/code:23 | blameline -s     # Blame single line from stdin
+#
+# Shows author, commit hash, and date for each line of code.
 
 require 'tins/go'
 include Tins::GO

data/bin/changes

@@ -1,17 +1,62 @@
 #!/usr/bin/env ruby
+#
+# Generate changelogs using Git history and LLM summaries
+#
+# Usage:
+#   changes pending    # Show changes since last version
+#   changes current    # Show changes between two latest versions
+#   changes range v1.0.0..v1.2.0  # Show changes in a specific range
+#   changes full       # Generate full changelog from first tag
+#   changes add CHANGELOG.md    # Append new entries to existing file
+#
+# Requires:
+#   - Git repository with version tags (vX.Y.Z format)
+#   - Ollama server running locally or accessible via OLLAMA_URL / OLLAMA_HOST
+#   - Configuration files in ~/.config/changes/
+#     - system.txt: System prompt for LLM
+#     - prompt.txt: Template for changelog generation
+#     - client.json: Ollama client settings
+#     - options.json: Generation options (temperature, etc.)
+#
+# Environment variables:
+#   OLLAMA_URL:  Base URL of Ollama server OR
+#   OLLAMA_HOST: Host of Ollama server
+#   OLLAMA_MODEL: Model to use (default: llama3.1)
+#   XDG_CONFIG_HOME: Custom config directory location
+#   DEBUG: Set to 1 for verbose output
 
 require 'ollama'
 include Ollama
-require 'tins/xt'
 require 'utils'
-include Utils::XDGConfig
 
+# Executes a shell command and returns its output.
+#
+# This method runs the provided command in a shell environment and captures its
+# standard output. If the command fails (returns a non-zero exit status), it
+# raises an exception with details about the failure.
+#
+# @param cmd [ String ] the shell command to be executed
+#
+# @return [ String ] the standard output of the executed command
+#
+# @raise [ RuntimeError ] if the executed command returns a non-zero exit status
 def x(cmd)
   output = `#{cmd}`
   $?.success? or fail "failed to execute #{cmd.inspect}"
   output
 end
 
+# Finds the highest version tag from a CHANGES file by parsing version strings
+# in YYYY-MM-DD vMAJOR.MINOR.PATCH format.
+#
+# This method reads through the specified file line by line, extracting version
+# tags that match the pattern "## YYYY-MM-DD vMAJOR.MINOR.PATCH" and determines
+# the highest version number among them.
+#
+# @param filename [ String ] the path to the file containing version tags
+#
+# @return [ String, nil ] the highest version string found in the file, or nil
+# if no valid version tags are present
 def find_highest_version_tag(filename)
   File.open(filename, ?r) do |input|
     tags = []
@@ -24,6 +69,17 @@ def find_highest_version_tag(filename)
   end
 end
 
+# The compute_change method generates a changelog entry by processing Git log
+# information and using an LLM to create a formatted summary.
+#
+# This method takes two range parameters, computes the Git log between them,
+# retrieves the commit date, and then uses an LLM to generate a human-readable
+# changelog entry based on configuration files and prompt templates.
+#
+# @param range_from [ Object ] the starting point of the Git log range
+# @param range_to [ Object ] the ending point of the Git log range
+#
+# @return [ String ] a formatted changelog entry including the date and LLM-generated content
 def compute_change(range_from, range_to)
   range_from = range_from.to_s.sub(/\Av?/, ?v)
   if range_to.to_s == 'HEAD'
@@ -45,7 +101,7 @@ def compute_change(range_from, range_to)
     EOT
   end
 
-  config = xdg_config('changes')
+  config = Utils::ConfigDir.new('changes', env_var: 'XDG_CONFIG_HOME')
 
   base_url      = ENV['OLLAMA_URL'] || 'http://%s' % ENV.fetch('OLLAMA_HOST')
   model         = ENV.fetch('OLLAMA_MODEL', 'llama3.1')
@@ -156,7 +212,15 @@ when 'full', 'add'
     end
   end
 else
-  puts <<~end
+  puts <<~EOT
     Usage: #{File.basename($0)} help|range|full|add|pending
-  end
+
+    Commands:
+      pending        Show changes since last version tag
+      current        Show changes between two latest version tags
+      range <range>  Show changes for a specific Git range (e.g., v1.0.0..v1.2.0)
+      full           Generate complete changelog from first tag
+      add <file>     Append new entries to existing changelog file
+
+  EOT
 end

data/bin/classify

@@ -1,11 +1,35 @@
 #!/usr/bin/env ruby
+#
+# Ruby module name to file path converter
+#
+# This tool helps map between Ruby module naming conventions and filesystem
+# paths, which is essential for Ruby development, code generation, and
+# refactoring. It converts between Foo::BarBaz (module names) and foo/bar_baz
+# (file paths) while supporting various formatting options and project-specific
+# path shifting.
+#
+# Common use cases:
+# - Converting controller names to file paths in Rails
+# - Refactoring code by mapping between naming conventions
+# - Can be used in editor functions for easy access
+#
+# Run 'classify -h' for detailed help and examples
 
 require 'utils'
-require 'tins/go'
 include Tins::GO
-require 'tins/xt/string'
 require 'term/ansicolor'
 
+# The path_shifter method processes a string path by splitting it using the
+# specified separator and then either removing the first n elements or taking a
+# slice from the end, depending on whether n is positive or negative.
+#
+# @param string [ String ] the path string to be processed
+# @param separator [ String ] the character used to split the path string,
+# defaults to '/'
+# @param n [ Integer, nil ] the number of elements to remove from the beginning
+# of the path if positive, or take from the end if negative
+#
+# @return [ String ] the resulting path string after processing
 def path_shifter(string, separator: ?/, n: nil)
   n or return string
   n, path = n.to_i, string.split(separator)
@@ -17,6 +41,15 @@ def path_shifter(string, separator: ?/, n: nil)
   path * separator
 end
 
+# The underscore method converts a string to underscored format.
+#
+# This method processes a string by first applying path shifting based on
+# options, then applies the standard underscore transformation.
+# It optionally appends '.rb' to the result if specified in the options.
+#
+# @param string [ String ] the input string to be converted
+#
+# @return [ String ] the underscored version of the input string
 def underscore(string)
   string = path_shifter(string, n: $opts[?n], separator: '::')
   string = Tins::StringUnderscore.instance_method(:underscore).bind(string).()
@@ -24,31 +57,89 @@ def underscore(string)
   string
 end
 
+# The parameterize method converts a string into a URL-friendly format by
+# replacing spaces and special characters with a specified separator.
+#
+# This method takes an input string and transforms it into a lowercase,
+# underscore-separated format suitable for use in URLs or file names. It
+# handles forward slashes by replacing them with the specified separator
+# character.
+#
+# @param string [ String ] the input string to be parameterized
+# @param separator [ String ] the character to replace forward slashes with
+#
+# @return [ String ] the parameterized string with forward slashes replaced by
+# the specified separator
 def parameterize(string, separator)
   underscore(string).gsub(?/, separator) # quick and dirty
 end
 
+# The camelize method converts a string into camelCase format by processing...
+# It removes the file extension first, then applies camelization to the
+# remaining string.
+#
+# @param string [ String ] the input string to be converted
+#
+# @return [ String ] the camelized string result
 def camelize(string)
   string = path_shifter(string, n: $opts[?n])
   string = string.gsub(/#{Regexp.quote(File.extname(string))}\Z/, '')
   string.camelize
 end
 
+# The camelcase? method checks whether a string starts with an uppercase
+# letter.
+#
+# This method determines if the provided string begins with a capital letter,
+# returning true if it does and false otherwise.
+#
+# @param string [ String ] the string to be checked for camelCase format
+#
+# @return [ TrueClass, FalseClass ] true if the string starts with an uppercase
+# letter, false otherwise
 def camelcase?(string)
-  string[0, 1] =~ /[A-Z]/
+  string =~ /\A[A-Z]/
 end
 
+# The compute_shift method determines the shift value for a string based on
+# configuration settings.
+#
+# This method processes a string by converting it to underscore format and then
+# checks against configured shift path prefixes to determine an appropriate
+# shift value.
+# If a matching prefix is found, it returns the count of forward slashes in the
+# prefix plus one. Otherwise, it returns the default shift path value from the
+# configuration.
+#
+# @param config [ Object ] the configuration object containing classify
+# settings
+# @param string [ String ] the input string to process and determine shift
+# value for
+#
+# @return [ Integer ] the calculated shift value based on prefix matching or
+# default setting
 def compute_shift(config, string)
-  string = underscore(string)
-  result = config.classify.shift_path_by_default
+  string  = underscore(string)
+  default = config.classify.shift_path_by_default
   for prefix in config.classify.shift_path_for_prefix
     if string.start_with? prefix
       return prefix.count(?/) + 1
     end
   end
-  result
+  default
 end
 
+# The usage method displays the command-line interface help text and exits the
+# program.
+#
+# This method prints a formatted usage message that describes the available
+# options for the command-line tool, including descriptions of each flag and
+# their functionality.
+# It provides information about how to classify and declassify path names into
+# module namespaces, along with various toggle and formatting options.
+#
+# This method always exits the program with status code 0 after displaying
+# help.
 def usage
   puts <<~EOT
     Usage: #{File.basename($0)} [OPTS]
@@ -65,6 +156,32 @@ def usage
       -p SEPARATOR used for declassification
       -h           display this help
 
+    Examples:
+
+    classify Foo::BarBaz           ⇢ Foo::BarBaz
+    classify -d Foo::Bar           ⇢ foo/bar
+    classify -d foo/bar_baz        ⇢ foo/bar_baz
+    classify foo/bar               ⇢ Foo::Bar
+    classify -b Foo::BarBaz        ⇢ BarBaz
+    classify -d -s Foo::Bar        ⇢ foo/bar.rb
+    classify -t Foo::Bar           ⇢ foo/bar
+    classify -t foo/bar            ⇢ Foo::Bar
+    classify -p . -d Foo::Bar::Baz ⇢ foo.bar.baz
+    classify -p : -d Foo::Bar::Baz ⇢ foo:bar:baz
+    classify -n 1 lib/foo/bar      ⇢ Foo::Bar
+
+    With this configuration in .utilsrc:
+      classify do
+        shift_path_by_default 1 # if no prefix matched
+        shift_path_for_prefix [ # prefixes checked in order
+          'a/b',
+          'c/d/e',
+        ]
+      end
+
+    classify lib/foo/bar   ⇢ Foo::Bar
+    classify a/b/foo/bar   ⇢ Foo::Bar
+    classify c/d/e/foo/bar ⇢ Foo::Bar
   EOT
   exit 0
 end
@@ -103,6 +220,10 @@ print(
       underscore string
     end
   else
-    camelize string
+    if camelcase?(string)
+      path_shifter(string, separator: '::', n: $opts[?n])
+    else
+      camelize string
+    end
   end
 )