utils 0.68.0 → 0.69.0

data/lib/utils/editor.rb

@@ -1,10 +1,19 @@
-require 'tins/xt/full'
 require 'fileutils'
 require 'rbconfig'
 require 'pstree'
 
 module Utils
   class Editor
+    # The initialize method sets up a new editor instance with default
+    # configuration.
+    #
+    # This method configures the editor by initializing default values for wait
+    # flag, pause duration, and server name. It also loads the configuration
+    # file and assigns the edit configuration section to the instance.
+    #
+    # @param block [ Proc ] optional block to be executed after initialization
+    #
+    # @return [ Utils::Editor ] a new editor instance configured with default settings
     def initialize
       self.wait           = false
       self.pause_duration = 1
@@ -15,28 +24,79 @@ module Utils
       yield self if block_given?
     end
 
+    # The derive_server_name method constructs a server name based on
+    # environment configuration.
+    #
+    # This method determines an appropriate server name by checking for a
+    # VIM_SERVER environment variable, falling back to the current working
+    # directory if not set. On Windows-like systems, it prefixes the name with
+    # "G_" to ensure uniqueness. The resulting name is converted to uppercase
+    # for consistent formatting.
+    #
+    # @return [ String ] the constructed server name based on environment and
+    # system configuration
     private def derive_server_name
       name = ENV['VIM_SERVER'] || Dir.pwd
       RbConfig::CONFIG['host_os'] =~ /mswin|mingw/ and name = "G_#{name}"
       name.upcase
     end
 
+    # The pause_duration method gets or sets the pause duration value.
+    #
+    # @return [ Integer ] the current pause duration value
+    # @param value [ Integer ] the new pause duration value to set
     attr_accessor :pause_duration
 
+    # The wait method gets the wait status.
+    #
+    # @return [ TrueClass, FalseClass, nil ] the wait status value
     attr_accessor :wait
 
+    alias wait? wait
+
+    # The servername method provides access to the server name attribute.
+    #
+    # This method returns the value of the server name instance variable,
+    # which represents the name of the server being used.
+    #
+    # @return [ String ] the server name value
     attr_accessor :servername
 
+    # The mkdir method provides access to the directory creation flag.
+    #
+    # This method returns the current value of the mkdir flag, which determines
+    # whether directory creation should be attempted when processing files.
+    #
+    # @return [ TrueClass, FalseClass ] the current state of the mkdir flag
     attr_accessor :mkdir
 
+    # The config method provides access to the configuration object.
+    #
+    # This method returns the configuration instance variable that holds the
+    # settings and options for the object's operation.
+    #
+    # @return [ Utils::ConfigFile ] the configuration object associated with this instance
     attr_accessor :config
 
-    alias wait? wait
-
+    # The vim method constructs and returns the Vim command configuration.
+    #
+    # This method assembles the Vim command by combining the configured Vim
+    # path with any default arguments specified in the configuration.
+    #
+    # @return [ Array<String> ] an array containing the Vim executable path and
+    #         its default arguments for command execution
     def vim
       ([ config.vim_path ] + Array(config.vim_default_args))
     end
 
+    # The cmd method constructs a command from parts and executes it.
+    #
+    # This method takes multiple arguments, processes them to build a command
+    # array, and then executes the command using the system call.
+    #
+    # @param parts [ Array ] the parts to be included in the command
+    #
+    # @return [ Boolean ] true if the command was successful, false otherwise
     def cmd(*parts)
       command = parts.compact.inject([]) do |a, p|
         case
@@ -52,6 +112,17 @@ module Utils
       system(*command.map(&:to_s))
     end
 
+    # The fullscreen= method sets the fullscreen state for the remote editor
+    # session.
+    #
+    # This method configures the fullscreen mode of the remote editor by
+    # sending appropriate commands through the edit_remote_send mechanism. It
+    # ensures the editor session is started and paused briefly before applying
+    # the fullscreen
+    # setting, then activates the session to apply the changes.
+    #
+    # @param enabled [ TrueClass, FalseClass ] determines whether to enable or
+    # disable fullscreen mode
     def fullscreen=(enabled)
       start
       sleep pause_duration
@@ -63,14 +134,48 @@ module Utils
       activate
     end
 
+    # The file_linenumber? method checks if a filename matches the file and
+    # line number pattern.
+    #
+    # This method determines whether the provided filename string conforms to
+    # the regular expression pattern used for identifying file paths
+    # accompanied by line numbers.
+    #
+    # @param filename [ String ] the filename string to be checked
+    #
+    # @return [ MatchData, nil ] a match data object if the filename matches the pattern,
+    #         or nil if it does not match
     def file_linenumber?(filename)
       filename.match(Utils::Xt::SourceLocationExtension::FILE_LINENUMBER_REGEXP)
     end
 
+    # The expand_globs method processes an array of filename patterns by
+    # expanding glob expressions and returning a sorted array of unique
+    # filenames.
+    #
+    # @param filenames [ Array<String> ] an array of filename patterns that may
+    # include glob expressions
+    #
+    # @return [ Array<String> ] a sorted array of unique filenames with glob
+    # patterns expanded, or the original array if no glob patterns are present
     def expand_globs(filenames)
       filenames.map { |f| Dir[f] }.flatten.uniq.sort.full? || filenames
     end
 
+    # The edit method processes filenames to determine their source location
+    # and delegates to appropriate editing methods.
+    #
+    # If a single filename is provided and it has a source location, the method
+    # checks whether the location includes filename and linenumber attributes.
+    # If so, it calls edit_source_location with the source location; otherwise,
+    # it calls edit_file_linenumber with the source location components.
+    # If multiple filenames are provided and all have source locations, the
+    # method expands any glob patterns in the filenames, then calls edit_file
+    # with the expanded list of filenames.
+    # Finally, it ensures the editor is activated after processing.
+    #
+    # @param filenames [ Array<String, Integer> ] an array of filenames that
+    # may contain source location information
     def edit(*filenames)
       source_location = nil
       if filenames.size == 1 and
@@ -89,6 +194,15 @@ module Utils
       end
     end
 
+    # The make_dirs method creates directory structures for the provided
+    # filenames.
+    #
+    # This method checks if directory creation is enabled and, if so, ensures
+    # that the parent directories for each filename exist by creating them
+    # recursively.
+    #
+    # @param filenames [ Array<String> ] an array of filenames for which to
+    # create directory structures
     private def make_dirs(*filenames)
       if mkdir
         for filename in filenames
@@ -97,11 +211,23 @@ module Utils
       end
     end
 
+    # The edit_file method processes a list of filenames by ensuring their
+    # directories exist and then delegates to a remote file editing function.
+    #
+    # @param filenames [ Array<String> ] an array of filename strings to be processed
     def edit_file(*filenames)
       make_dirs(*filenames)
       edit_remote_file(*filenames)
     end
 
+    # The edit_file_linenumber method opens a file at a specific line number
+    # and optionally selects a range of lines in an editor.
+    #
+    # @param filename [ String ] the path to the file to be opened
+    # @param linenumber [ Integer ] the line number where the file should be
+    # opened
+    # @param rangeend [ Integer, nil ] the ending line number for selection, or
+    # nil if no range is specified
     def edit_file_linenumber(filename, linenumber, rangeend = nil)
       make_dirs filename
       if rangeend
@@ -113,12 +239,22 @@ module Utils
         end
       end
       if wait?
+        activate
         edit_remote_wait("+#{linenumber}", filename)
       else
         edit_remote("+#{linenumber}", filename)
       end
     end
 
+    # The edit_source_location method processes a source location object to
+    # open the corresponding file at the specified line number.
+    #
+    # This method takes a source location object and uses its filename, line
+    # number, and optional range end to invoke the edit_file_linenumber method
+    # for opening the file in an editor.
+    #
+    # @param source_location [ Array<String, Integer> ] the source location
+    # containing filename and line number information
     def edit_source_location(source_location)
       edit_file_linenumber(
         source_location.filename,
@@ -127,20 +263,45 @@ module Utils
       )
     end
 
+    # The rename_window method renames the current tmux window to match the
+    # base name of the current script.
+    #
+    # This method checks if the application is running within a tmux session
+    # and, if so, renames the current window to reflect the base name of the
+    # script being executed. It only performs the renaming operation if a tmux
+    # session is detected and the window has not already been started.
     private def rename_window
       return if started?
       ENV['TMUX'] and system "tmux rename-window #{File.basename($0)}"
     end
 
+    # The start method initializes the Vim server connection if it is not
+    # already running.
+    #
+    # This method first attempts to rename the terminal window to reflect the
+    # server name, then checks if the Vim server has already been started. If
+    # not, it executes the command to launch the Vim server with the specified
+    # server name.
     def start
       rename_window
       started? or cmd(*vim, '--servername', servername)
     end
 
+    # The stop method sends a quit command to the remote editor.
+    #
+    # This method checks if the editor is currently running and, if so, sends a
+    # quit command to close all windows and terminate the editor session.
     def stop
       started? and edit_remote_send('<ESC>:qa<CR>')
     end
 
+    # The activate method switches to the Vim editor window or opens a new one.
+    #
+    # This method checks if the Vim default arguments include the '-g' flag to determine
+    # whether to open a new buffer in the current window or switch to an
+    # existing Vim pane. When the '-g' flag is present, it creates a temporary
+    # file and then closes it. Otherwise, it identifies the appropriate tmux
+    # pane running an editor process and switches to it.
     def activate
       if Array(config.vim_default_args).include?('-g')
         edit_remote("stupid_trick#{rand}")
@@ -160,29 +321,80 @@ module Utils
       end
     end
 
+    # The serverlist method retrieves a list of available Vim server names.
+    #
+    # This method executes the Vim command to list all active servers and
+    # returns the results as an array of server names.
+    #
+    # @return [ Array<String> ] an array of Vim server names currently available
     def serverlist
       `#{vim.map(&:inspect) * ' '} --serverlist`.split
     end
 
+    # The started? method checks whether a server with the given name is
+    # currently running.
+    #
+    # This method verifies the presence of a server in the list of active
+    # servers by checking if the server name exists within the serverlist.
+    #
+    # @param name [ String ] the name of the server to check for
+    #
+    # @return [ TrueClass, FalseClass ] true if the server is running, false otherwise
     def started?(name = servername)
       serverlist.member?(name)
     end
 
+    # The edit_remote method executes a remote Vim command with the specified
+    # arguments.
+    #
+    # This method prepares a command to communicate with a running Vim server
+    # instance, allowing for remote execution of Vim commands without directly
+    # interacting with the terminal. It ensures the window is renamed before
+    # sending the command and constructs the appropriate command line arguments
+    # for the Vim server interface.
+    #
+    # @param args [ Array ] the arguments to be passed to the remote Vim command
     def edit_remote(*args)
       rename_window
       cmd(*vim, '--servername', servername, '--remote', *args)
     end
 
+    # The edit_remote_wait method executes a command remotely and waits for its
+    # completion.
+    #
+    # This method sends a command to a remote server using the specified vim
+    # server connection, and blocks until the remote operation finishes
+    # executing.
+    #
+    # @param args [ Array ] the arguments to be passed to the remote command
     def edit_remote_wait(*args)
       rename_window
       cmd(*vim, '--servername', servername, '--remote-wait', *args)
     end
 
+    # The edit_remote_send method transmits a sequence of arguments to a remote
+    # Vim server for execution.
+    #
+    # This method prepares and sends commands to an already running Vim
+    # instance identified by its server name, allowing for remote control of
+    # the editor session. It ensures the window is properly named before
+    # sending the command, and uses the configured Vim executable along with
+    # its remote communication flags.
+    #
+    # @param args [ Array<String> ] the arguments to be sent to the remote Vim server
     def edit_remote_send(*args)
       rename_window
       cmd(*vim, '--servername', servername, '--remote-send', *args)
     end
 
+    # The edit_remote_file method delegates to either edit_remote_wait or
+    # edit_remote based on the wait? condition.
+    #
+    # This method determines whether to execute file editing operations with
+    # waiting for completion or without waiting, depending on the result of the
+    # wait? check.
+    #
+    # @param filenames [ Array<String> ] an array of filenames to be processed
     def edit_remote_file(*filenames)
       if wait?
         edit_remote_wait(*filenames)

data/lib/utils/finder.rb

@@ -1,5 +1,4 @@
 require 'term/ansicolor'
-require 'tins/xt'
 require 'tempfile'
 require 'digest/md5'
 require 'fileutils'
@@ -10,6 +9,17 @@ class Utils::Finder
   include Utils::Patterns
   include Term::ANSIColor
 
+  # The initialize method sets up the finder instance with the provided options.
+  #
+  # This method configures the finder by processing the input options,
+  # including arguments, root directories, and pattern settings. It initializes
+  # the pattern matcher based on the specified options and prepares the index
+  # for searching.
+  #
+  # @param opts [ Hash ] the options hash containing configuration settings
+  # @option opts [ Hash ] :args the argument options for the finder
+  # @option opts [ Array ] :roots the root directories to search in
+  # @option opts [ Utils::ConfigFile ] :config the configuration file object
   def initialize(opts = {})
     @args  = opts[:args] || {}
     @roots = discover_roots(opts[:roots])
@@ -27,19 +37,36 @@ class Utils::Finder
     reset_index
   end
 
+  # The paths reader method provides access to the array of file paths that
+  # have been processed or collected.
+  #
+  # This method returns the internal array containing the file paths, allowing
+  # external code to read the current set of paths without modifying the
+  # original collection.
+  #
+  # @return [ Array<String> ] an array of file path strings that have been processed or collected
   attr_reader :paths
 
+  # The output reader method provides access to the output value.
+  #
+  # @return [ Object ] the output value that was set previously
   attr_reader :output
 
-  def search_index
-    paths = load_paths
-    search_paths(paths)
-  end
-
-  alias search search_index
-
+  # The build_paths method constructs a list of file system paths by traversing
+  # the configured root directories.
+  #
+  # This method iterates through the specified root directories and collects
+  # all file system entries, applying filtering logic to exclude certain
+  # directories and files based on configuration settings.
+  # It handles both regular files and directories, ensuring that directory
+  # entries are properly marked with a trailing slash for distinction. The
+  # resulting paths are deduplicated before being returned.
+  #
+  # @return [ Array ] an array of file system path strings, with directories
+  # marked by a trailing slash
   def build_paths
     paths = []
+
     visit = -> filename {
       s  = filename.stat
       bn = filename.pathname.basename
@@ -60,6 +87,15 @@ class Utils::Finder
     paths
   end
 
+  # The index_path method generates a unique file path for storing finder
+  # results.
+  #
+  # This method creates a standardized location in the temporary directory for
+  # caching finder path data based on the root directories being processed.
+  # It ensures uniqueness by hashing the sorted root paths and uses the current
+  # script name as part of the directory structure.
+  #
+  # @return [ String ] the full file path where finder results should be stored
   def index_path
     roots = @roots.map { |r| File.expand_path(r) }.uniq.sort
     filename = "finder-paths-" +
@@ -69,6 +105,12 @@ class Utils::Finder
     File.join(dirname, filename)
   end
 
+  # The create_paths method generates and stores path information by building a
+  # list of paths, writing them to a secure file, and then returning the list
+  # of paths.
+  #
+  # @return [ Array ] an array containing the paths that were built and written
+  # to the index file
   def create_paths
     paths = build_paths
     File.secure_write(index_path) do |output|
@@ -77,6 +119,14 @@ class Utils::Finder
     paths
   end
 
+  # The load_paths method reads and processes indexed file paths from disk.
+  #
+  # This method loads lines from the index file path, removes trailing
+  # whitespace, and filters out directory entries if the debug flag is not set.
+  # It returns create_paths if the index file is empty or missing,
+  # otherwise it returns the processed list of file paths.
+  #
+  # @return [ Array<String> ] an array of file paths loaded from the index
   memoize method:
   def load_paths
     lines = File.readlines(index_path)
@@ -88,6 +138,16 @@ class Utils::Finder
     return create_paths
   end
 
+  # The reset_index method resets the index file by removing it if the reset
+  # flag is set or if the index has expired.
+  #
+  # This method checks whether the reset argument flag is set or if the index
+  # file has expired based on its modification time.
+  # If either condition is true, it removes the index file from the filesystem
+  # and clears the mize cache. The method then returns the instance itself to
+  # allow for method chaining.
+  #
+  # @return [ Utils::Finder ] returns self to allow for method chaining
   def reset_index
     path = index_path
     if @args[?r] || index_expired?(path)
@@ -98,14 +158,17 @@ class Utils::Finder
     self
   end
 
-  def search_index
-    search_paths load_paths
-  end
-
-  def search_directly
-    search_paths build_paths
-  end
-
+  # The search_paths method processes and filters a collection of file paths
+  # based on specified criteria.
+  #
+  # This method takes an array of paths and applies filtering based on file
+  # extensions and patterns. It handles both fuzzy and regular expression
+  # pattern matching, and returns formatted results with optional sorting and
+  # limiting of results.
+  #
+  # @param paths [ Array<String> ] the collection of file paths to be processed
+  #
+  # @return [ Utils::Finder ] returns self to allow for method chaining
   def search_paths(paths)
     suffixes = Array(@args[?I])
     suffixes.full? do |s|
@@ -148,8 +211,44 @@ class Utils::Finder
     self
   end
 
+  # The search_directly method performs a direct search by building paths and
+  # then searching through them.
+  #
+  # This method first constructs the list of paths to be searched and then
+  # executes the search operation on those paths, returning the results of the
+  # search.
+  #
+  # @return [ Object ] the result of the search operation performed on the built paths
+  def search_directly
+    search_paths build_paths
+  end
+
+  # The search_index method performs a pattern search across previously loaded
+  # paths.
+  #
+  # This method utilizes the loaded paths from the internal storage to execute
+  # a search operation, applying the configured pattern matching criteria to
+  # filter and return relevant results based on the current search
+  # configuration.
+  def search_index
+    search_paths load_paths
+  end
+
+  alias search search_index
+
   private
 
+  # The index_expired? method checks whether the index file has exceeded its
+  # expiration duration.
+  #
+  # This method determines if the specified index file is considered expired
+  # based on the configured discovery index expiration time. It compares the
+  # current time with the modification time of the file to make this
+  # determination.
+  #
+  # @param path [ String ] the filesystem path to the index file being checked
+  #
+  # @return [ TrueClass, FalseClass ] true if the index file has expired, false otherwise
   def index_expired?(path)
     if duration = @config.discover.index_expire_after
       Time.now - duration >= File.mtime(path)
@@ -160,6 +259,18 @@ class Utils::Finder
     false
   end
 
+  # 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.
+  #
+  # @param roots [ Array<String>, nil ] an array of root patterns or nil
+  #
+  # @return [ Array<String> ] an array of expanded directory paths that match
+  # the input patterns
   def discover_roots(roots)
     roots ||= []
     roots.inject([]) { |rs, r| rs.concat Dir[r] }