utils 0.68.0 → 0.69.0

data/lib/utils/grepper.rb

@@ -1,5 +1,4 @@
 require 'term/ansicolor'
-require 'tins/xt'
 
 class Utils::Grepper
   include Tins::Find
@@ -7,16 +6,36 @@ class Utils::Grepper
   include Term::ANSIColor
 
   class Queue
+    # The initialize method sets up a new instance with the specified maximum
+    # size and empty data array.
+    #
+    # @param max_size [ Integer ] the maximum size limit for the data storage
     def initialize(max_size)
       @max_size, @data = max_size, []
     end
 
+    # The max_size reader method provides access to the maximum size value.
+    #
+    # @return [ Integer ] the maximum size value stored in the instance
     attr_reader :max_size
 
+    # The data method returns a duplicate of the internal data array.
+    #
+    # This method provides access to the internal @data instance variable by
+    # returning a shallow copy of the array, ensuring that external
+    # modifications do not affect the original data structure.
+    #
+    # @return [ Array ] a duplicate of the internal data array
     def data
       @data.dup
     end
 
+    # The push method adds an element to the queue and removes the oldest
+    # element if the maximum size is exceeded.
+    #
+    # @param x [ Object ] the element to be added to the queue
+    #
+    # @return [ Queue ] returns self to allow for method chaining
     def push(x)
       @data.shift if @data.size > @max_size
       @data << x
@@ -25,6 +44,22 @@ class Utils::Grepper
     alias << push
   end
 
+  # The initialize method sets up the grepper instance with the provided
+  # options.
+  #
+  # This method configures the grepper by processing the input options, setting up
+  # the root directories for searching, initializing the configuration, and
+  # preparing pattern matchers for filename and skip patterns. It also handles
+  # queue initialization for buffering output when specified.
+  #
+  # @param opts [ Hash ] the options hash containing configuration settings
+  # @option opts [ Hash ] :args the command-line arguments
+  # @option opts [ Array ] :roots the root directories to search
+  # @option opts [ Utils::ConfigFile ] :config the configuration file object
+  # @option opts [ Hash ] :pattern the pattern-related options
+  #
+  # @return [ Utils::Grepper ] a new grepper instance configured with the
+  # provided options
   def initialize(opts = {})
     @args  = opts[:args] || {}
     @roots = discover_roots(opts[:roots])
@@ -56,10 +91,32 @@ class Utils::Grepper
       end
   end
 
+  # The paths reader method provides access to the paths instance variable.
+  #
+  # @return [ Array ] the array of paths stored in the instance variable
   attr_reader :paths
 
+  # The pattern reader method provides access to the pattern matcher object.
+  #
+  # This method returns the internal pattern matcher that was initialized
+  # during object creation, allowing external code to interact with the pattern
+  # matching functionality directly.
+  #
+  # @return [ Utils::Patterns::Pattern ] the pattern matcher object used for
+  # matching operations
   attr_reader :pattern
 
+  # The match method processes a file to find matching content based on
+  # configured patterns.
+  # It handles directory pruning, file skipping, and various output formats
+  # depending on the configuration.
+  # The method opens files for reading, applies pattern matching, and manages
+  # output through different code paths.
+  # It supports features like line-based searching, git blame integration, and
+  # multiple output modes.
+  # The method returns the instance itself to allow for method chaining.
+  #
+  # @return [ Utils::Grepper ] returns self to allow for method chaining
   def match(filename)
     @filename = filename
     @output = []
@@ -108,6 +165,15 @@ class Utils::Grepper
     self
   end
 
+  # The match_lines method processes each line from a file using pattern
+  # matching.
+  #
+  # This method iterates through lines in the provided file, applying pattern
+  # matching to identify relevant content. It handles various output options
+  # based on command-line arguments and manages queuing of lines for context
+  # display.
+  #
+  # @param file [IO] the file object to be processed line by line
   def match_lines(file)
     for line in file
       if m = @pattern.match(line)
@@ -148,6 +214,16 @@ class Utils::Grepper
     end
   end
 
+  # The search method performs a file search operation within specified roots,
+  # filtering results based on various criteria including file extensions,
+  # pruning directories, and skipping specific files.
+  #
+  # It utilizes a visit lambda to determine whether each file or directory
+  # should be processed or skipped based on configuration settings and
+  # command-line arguments. The method employs the find utility to traverse
+  # the filesystem, executing match operations on qualifying files.
+  #
+  # @return [ Utils::Grepper ] returns self to allow for method chaining
   def search
     suffixes = Array(@args[?I])
     visit = -> filename {
@@ -175,6 +251,19 @@ class Utils::Grepper
 
   private
 
+  # The discover_roots method processes an array of root patterns and expands
+  # them into actual directory paths.
+  #
+  # This method takes an array of root patterns, which may include glob
+  # patterns, and uses Dir[r] to expand each pattern into matching directory
+  # paths.
+  # It handles the case where the input roots array is nil by defaulting to an
+  # empty array. The expanded paths are then concatenated into a single result
+  # array.
+  #
+  # @param roots [ Array<String>, nil ] an array of root patterns or nil
+  #
+  # @return [ Array<String> ] an array of expanded directory paths matching the input patterns
   def discover_roots(roots)
     roots ||= []
     roots.inject([]) { |rs, r| rs.concat Dir[r] }