utils 0.68.0 → 0.69.0

data/lib/utils/config_file.rb

@@ -1,5 +1,4 @@
 require 'tins'
-require 'tins/xt/string'
 
 class Utils::ConfigFile
   class << self
@@ -15,15 +14,41 @@ class Utils::ConfigFile
 
   class ConfigFileError < StandardError; end
 
+  # The initialize method sets up a new instance of the class.
+  #
+  # This method is called when creating a new object and performs any necessary
+  # initialization tasks for the instance variables and internal state.
   def initialize
   end
 
+  # The configure_from_paths method initializes the configuration by parsing
+  # configuration files from the specified paths.
+  #
+  # This method iterates through an array of configuration file paths and
+  # processes each one to load the configuration settings. It is typically used
+  # to set up the application's configuration from multiple sources.
+  #
+  # @param paths [ Array<String> ] an array of file paths pointing to configuration files
   def configure_from_paths(paths = self.class.config_file_paths)
     for config_file_path in paths
       parse_config_file config_file_path
     end
   end
 
+  # The parse_config_file method reads and processes a configuration file.
+  #
+  # This method opens the specified configuration file, reads its contents,
+  # and parses the configuration data. It handles file path expansion and
+  # includes error handling for system call errors during file operations.
+  #
+  # @param config_file_path [ String ] the path to the configuration file to be parsed
+  #
+  # @return [ Utils::ConfigFile ] returns self after parsing the configuration file
+  #
+  # @raise [ SystemCallError ] if there is an issue reading the configuration file
+  #
+  # @note The method will output a warning message to standard error if it fails
+  #       to read the configuration file and return nil.
   def parse_config_file(config_file_path)
     config_file_path = File.expand_path(config_file_path)
     File.open(config_file_path) do |cf|
@@ -36,6 +61,16 @@ class Utils::ConfigFile
     return nil
   end
 
+  # The parse method processes the provided source code by interpreting it
+  # within the given binding context.
+  #
+  # This method takes a source code string and evaluates it in the context of
+  # the specified binding, allowing for dynamic execution of code with access
+  # to the current variable scope.
+  #
+  # @param source [ String ] the source code to be interpreted and executed
+  #
+  # @return [ Object ] returns self after processing the source code
   def parse(source)
     interpret_with_binding source, binding
     self
@@ -43,11 +78,29 @@ class Utils::ConfigFile
 
   class BlockConfig
     class << self
+      # The inherited method extends the module with DSL accessor functionality
+      # and calls the superclass implementation.
+      #
+      # @param modul [ Module ] the module that inherited this class
       def inherited(modul)
         modul.extend DSLKit::DSLAccessor
         super
       end
 
+      # The config method sets up a configuration accessor with the specified
+      # name and options.
+      #
+      # This method registers a new configuration setting by adding it to the
+      # list of configuration settings and then creates an accessor for it
+      # using the dsl_accessor method, allowing for easy retrieval and
+      # assignment of configuration values.
+      #
+      # @param name [ Object ] the name of the configuration setting
+      # @param r [ Array ] additional arguments passed to the dsl_accessor method
+      #
+      # @yield [ block ] optional block to be passed to the dsl_accessor method
+      #
+      # @return [ Object ] returns self to allow for method chaining
       def config(name, *r, &block)
         self.config_settings ||= []
         config_settings << name.to_sym
@@ -55,13 +108,39 @@ class Utils::ConfigFile
         self
       end
 
+      # The config_settings method provides access to the configuration
+      # settings.
+      #
+      # This method returns the configuration settings stored in the instance
+      # variable, allowing for reading and modification of the object's
+      # configuration state.
+      #
+      # @return [ Object ] the current configuration settings stored in the
+      # instance variable
       attr_accessor :config_settings
     end
 
+    # The initialize method sets up the instance by evaluating the provided
+    # block in the instance's context.
+    #
+    # This method allows for dynamic configuration of the object by executing
+    # the given block within the instance's scope, enabling flexible
+    # initialization patterns.
+    #
+    # @param block [ Proc ] the block to be evaluated for instance setup
     def initialize(&block)
       block and instance_eval(&block)
     end
 
+    # The to_ruby method generates a Ruby configuration block representation by
+    # recursively processing the object's configuration settings and their
+    # values.
+    # It creates a nested structure with proper indentation and formatting
+    # suitable for configuration files.
+    #
+    # @param depth [ Integer ] the current nesting depth for indentation purposes
+    #
+    # @return [ String ] a formatted Ruby string representing the configuration block
     def to_ruby(depth = 0)
       result = ''
       result << ' ' * 2 * depth <<
@@ -80,14 +159,41 @@ class Utils::ConfigFile
   end
 
   class Probe < BlockConfig
+    # The config method sets up a configuration option for the test framework.
+    #
+    # This method defines a configuration parameter that specifies which test
+    # framework should be used, allowing for flexible test execution environments.
+    #
+    # @param name [ Symbol ] the name of the configuration option
+    # @param value [ Object ] the value to set for the configuration option
     config :test_framework, :'test-unit'
 
+    # The include_dirs method configures the directories to be included in the
+    # search.
+    #
+    # @param dirs [ Array<String> ] the array of directory names to include
     config :include_dirs, %w[lib test tests ext spec]
 
+    # The include_dirs_argument method constructs a colon-separated string from
+    # include directories.
+    #
+    # This method takes the include directories configuration and converts it
+    # into a single colon-delimited string suitable for use in command-line
+    # arguments or environment variables.
+    #
+    # @return [ String ] a colon-separated string of include directory paths
     def include_dirs_argument
       Array(include_dirs) * ':'
     end
 
+    # The initialize method sets up the configuration by validating the test
+    # framework.
+    #
+    # This method initializes the configuration object and ensures that the
+    # specified test framework is one of the allowed values. It raises an error
+    # if the test framework is not supported.
+    #
+    # @param block [ Proc ] a block to be passed to the superclass initializer
     def initialize(&block)
       super
       test_frameworks_allowed = [ :'test-unit', :rspec ]
@@ -97,6 +203,17 @@ class Utils::ConfigFile
     end
   end
 
+  # The probe method initializes and returns a Probe object.
+  #
+  # This method creates a new Probe instance either from the provided block or
+  # with default settings, storing it for later use. It ensures that only one
+  # Probe instance is created per object, returning the existing instance
+  # on subsequent calls.
+  #
+  # @param block [ Proc ] optional block to configure the Probe instance
+  #
+  # @return [ Utils::Probe ] a Probe instance configured either by the block
+  #         or with default settings
   def probe(&block)
     if block
       @probe = Probe.new(&block)
@@ -105,21 +222,76 @@ class Utils::ConfigFile
   end
 
   class FileFinder < BlockConfig
+    # The prune? method checks if a basename matches any of the configured
+    # prune directories.
+    #
+    # This method determines whether a given filename or directory name should
+    # be excluded based on the prune directories configuration. It iterates
+    # through the list of prune patterns and returns true if any pattern
+    # matches the provided basename.
+    #
+    # @param basename [ String, Object ] the basename to check against prune patterns
+    #
+    # @return [ TrueClass, FalseClass ] true if the basename matches any prune pattern,
+    #         false otherwise
     def prune?(basename)
       Array(prune_dirs).any? { |pd| pd.match(basename.to_s) }
     end
 
+    # The skip? method determines whether a file should be skipped based on
+    # configured patterns.
+    #
+    # This method checks if the provided basename matches any of the configured
+    # skip patterns. It converts the basename to a string and tests it against
+    # all defined skip files.
+    #
+    # @param basename [ Object] the file or directory name to check
+    #
+    # @return [ TrueClass, FalseClass ] true if the basename matches any skip
+    # pattern, false otherwise
     def skip?(basename)
       Array(skip_files).any? { |sf| sf.match(basename.to_s) }
     end
   end
 
   class Search < FileFinder
+    # The prune_dirs method configures the pattern for identifying directories
+    # to be pruned during file system operations.
+    #
+    # This method sets up a regular expression pattern that matches directory
+    # names which should be excluded from processing. The default pattern
+    # excludes version control directories (.svn, .git, CVS) and temporary
+    # directories (tmp).
+    #
+    # @param first [ Regexp ] the regular expression pattern for matching
+    # directories to prune
     config :prune_dirs, /\A(\.svn|\.git|CVS|tmp)\z/
 
+    # The skip_files configuration method sets up a regular expression pattern
+    # for filtering out files based on their names.
+    #
+    # This method configures a pattern that matches filenames which should be
+    # skipped during file processing operations.
+    # It uses a regular expression to identify files that start with a dot, end
+    # with common temporary file extensions, or match other patterns typically
+    # associated with backup, swap, log, or temporary files.
+    #
+    # @param pattern [ Regexp ] the regular expression pattern used to identify
+    # files to skip
     config :skip_files, /(\A\.|\.sw[pon]\z|\.log\z|~\z)/
   end
 
+  # The search method initializes and returns a Search object.
+  #
+  # This method creates a Search instance either from a provided block or with
+  # default settings.
+  # It maintains a cached instance of the Search object, returning the same
+  # instance on subsequent calls.
+  #
+  # @param block [ Proc ] optional block to configure the Search object
+  #
+  # @return [ Utils::Search ] a Search object configured either by the provided
+  # block or with default settings
   def search(&block)
     if block
       @search = Search.new(&block)
@@ -128,15 +300,60 @@ class Utils::ConfigFile
   end
 
   class Discover < FileFinder
+    # The prune_dirs method configures the pattern for identifying directories
+    # to be pruned during file system operations.
+    #
+    # This method sets up a regular expression pattern that matches directory
+    # names which should be excluded from processing.
+    # The default pattern excludes version control directories (.svn, .git,
+    # CVS) and temporary directories (tmp).
+    #
+    # @param first [ Regexp ] the regular expression pattern for matching
+    # directories to prune
     config :prune_dirs, /\A(\.svn|\.git|CVS|tmp)\z/
 
+    # The skip_files configuration method sets up a regular expression pattern
+    # for filtering out files based on their names.
+    #
+    # This method configures a pattern that matches filenames which should be
+    # skipped during file processing operations. It uses a regular expression
+    # to identify files that start with a dot, end with common temporary file
+    # extensions, or match other patterns typically associated with backup,
+    # swap, log, or temporary files.
+    #
+    # @param pattern [ Regexp ] the regular expression pattern used to identify
+    # files to skip
     config :skip_files, /(\A\.|\.sw[pon]\z|\.log\z|~\z)/
 
+    # The config method sets up a configuration option with a default value.
+    #
+    # @param name [ Symbol ] the name of the configuration option
+    # @param default [ Object ] the default value for the configuration option
     config :max_matches, 10
 
+    # The index_expire_after method configures the expiration time for index
+    # files.
+    #
+    # This method sets up the duration after which index files should be
+    # considered expired and potentially refreshed or regenerated by the
+    # system.
+    #
+    # @param value [ Integer, nil ] the number of seconds after which indexes expire,
+    #                               or nil to disable automatic expiration
     config :index_expire_after
   end
 
+  # The discover method initializes and returns a Discover object.
+  #
+  # This method sets up a Discover instance, either using a provided block for
+  # configuration or creating a default instance. It ensures that only one
+  # Discover object is created per instance by storing it in an instance
+  # variable.
+  #
+  # @param block [ Proc ] optional block to configure the Discover object
+  #
+  # @return [ Utils::Discover ] a Discover object configured either with the
+  # provided block or with default settings
   def discover(&block)
     if block
       @discover = Discover.new(&block)
@@ -145,11 +362,41 @@ class Utils::ConfigFile
   end
 
   class Scope < FileFinder
+    # The prune_dirs method configures the pattern for identifying directories
+    # to be pruned during file system operations.
+    #
+    # This method sets up a regular expression pattern that matches directory
+    # names which should be excluded from processing. The default pattern
+    # excludes version control directories (.svn, .git, CVS) and temporary
+    # directories (tmp).
+    #
+    # @param first [ Regexp ] the regular expression pattern for matching directories to prune
     config :prune_dirs, /\A(\.svn|\.git|CVS|tmp)\z/
 
+    # The skip_files configuration method sets up a regular expression pattern
+    # for filtering out files based on their names.
+    #
+    # This method configures a pattern that matches filenames which should be
+    # skipped during file processing operations.
+    # It uses a regular expression to identify files that start with a dot, end
+    # with common temporary file extensions, or match other patterns typically
+    # associated with backup, swap, log, or temporary files.
+    #
+    # @param pattern [ Regexp ] the regular expression pattern used to identify files to skip
     config :skip_files, /(\A\.|\.sw[pon]\z|\.log\z|~\z)/
   end
 
+  # The scope method initializes and returns a Scope object.
+  #
+  # This method creates a new Scope instance either from the provided block or
+  # with default initialization if no block is given.
+  # The scope object is stored as an instance variable and reused on subsequent
+  # calls.
+  #
+  # @param block [ Proc ] optional block to pass to the Scope constructor
+  #
+  # @return [ Utils::Scope ] a Scope object configured with the provided block
+  # or default settings
   def scope(&block)
     if block
       @scope = Scope.new(&block)
@@ -158,11 +405,42 @@ class Utils::ConfigFile
   end
 
   class StripSpaces < FileFinder
+    # The prune_dirs method configures the pattern for directory names that
+    # should be pruned.
+    #
+    # This method sets up a regular expression pattern that identifies
+    # directories which should be excluded or removed during file system
+    # operations.
+    #
+    # @param pattern [ Regexp ] the regular expression pattern to match
+    # directory names
     config :prune_dirs, /\A(\..*|CVS)\z/
 
+    # The skip_files configuration method sets up a regular expression pattern
+    # for filtering out files based on their names.
+    #
+    # This method configures a pattern that matches filenames which should be
+    # skipped during file processing operations.
+    # It uses a regular expression to identify files that start with a dot, end
+    # with common temporary file extensions, or match other patterns typically
+    # associated with backup, swap, log, or temporary files.
+    #
+    # @param pattern [ Regexp ] the regular expression pattern used to identify
+    # files to skip
     config :skip_files, /(\A\.|\.sw[pon]\z|\.log\z|~\z)/
   end
 
+  # The strip_spaces method configures and returns a StripSpaces object for
+  # processing whitespace.
+  #
+  # This method initializes a StripSpaces processor that can be used to remove
+  # or modify whitespace in strings. When a block is provided, it sets up the
+  # processor with custom behavior defined by the block. Otherwise, it returns
+  # a default StripSpaces instance.
+  #
+  # @param block [ Proc ] optional block to customize the strip spaces behavior
+  #
+  # @return [ Utils::StripSpaces ] a configured StripSpaces processor instance
   def strip_spaces(&block)
     if block
       @strip_spaces = StripSpaces.new(&block)
@@ -171,25 +449,57 @@ class Utils::ConfigFile
   end
 
   class SshTunnel < BlockConfig
+    # The terminal_multiplexer method configures the terminal multiplexer
+    # setting.
+    #
+    # This method sets up the terminal multiplexer that will be used for
+    # managing multiple terminal sessions within the application environment.
+    #
+    # @param value [ String ] the name of the terminal multiplexer to use
     config :terminal_multiplexer, 'tmux'
 
+    # The env method configures the environment variables for the session.
+    #
+    # @param value [ Hash ] environment variable hash
     config :env, {}
 
+    # The login_session method configures the login session settings.
+    #
+    # @param block [ Proc ] a block containing the login session configuration
     config :login_session do
       ENV.fetch('HOME',  'session')
     end
 
+    # The initialize method sets up the instance by calling the superclass
+    # constructor and assigning the terminal multiplexer configuration.
+    #
+    # @param terminal_multiplexer [ Object ] the terminal multiplexer to be assigned
     def initialize
       super
       self.terminal_multiplexer = terminal_multiplexer
     end
 
+    # The terminal_multiplexer= method sets the terminal multiplexer type for
+    # the editor.
+    #
+    # This method assigns the specified terminal multiplexer to the editor
+    # configuration, validating that it is either 'screen' or 'tmux'. It
+    # converts the input to a string and ensures it matches one of the
+    # supported multiplexer types.
+    #
+    # @param terminal_multiplexer [ Symbol ] the terminal multiplexer type to
+    # be configured
     def terminal_multiplexer=(terminal_multiplexer)
       @multiplexer = terminal_multiplexer.to_s
       @multiplexer =~ /\A(screen|tmux)\z/ or
         fail "invalid terminal_multiplexer #{terminal_multiplexer.inspect} was configured"
     end
 
+    # The multiplexer_list method returns the appropriate command string for
+    # listing sessions based on the current multiplexer type.
+    #
+    # @return [ String, nil ] the command string to list sessions for the configured
+    #         multiplexer ('screen -ls' or 'tmux ls'), or nil if no multiplexer is set
     def multiplexer_list
       case @multiplexer
       when 'screen'
@@ -199,6 +509,13 @@ class Utils::ConfigFile
       end
     end
 
+    # The multiplexer_new method generates a command string for creating a new
+    # session in the specified terminal multiplexer.
+    #
+    # @param session [ String ] the name of the session to be created
+    #
+    # @return [ String, nil ] a command string for creating a new session in screen
+    #         or tmux, or nil if the multiplexer type is not supported
     def multiplexer_new(session)
       case @multiplexer
       when 'screen'
@@ -208,6 +525,12 @@ class Utils::ConfigFile
       end
     end
 
+    # The multiplexer_attach method generates a command string for attaching to
+    # a session using either screen or tmux multiplexer.
+    #
+    # @param session [ String ] the name or identifier of the session to attach to
+    #
+    # @return [ String ] a formatted command string ready for execution
     def multiplexer_attach(session)
       case @multiplexer
       when 'screen'
@@ -218,19 +541,65 @@ class Utils::ConfigFile
     end
 
     class CopyPaste < BlockConfig
+      # The bind_address method configures the network address to which the
+      # server will bind for incoming connections.
+      #
+      # @param value [ String ] the IP address or hostname to bind the server to
       config :bind_address, 'localhost'
 
+      # The port method configures the port number for the SSH tunnel
+      # specification.
+      #
+      # This method sets up the port component of an SSH tunnel configuration,
+      # allowing for the specification of a network port to be used in the
+      # tunnel.
+      #
+      # @param name [ String ] the name of the port configuration
+      # @param default [ Integer ] the default port number to use if none is specified
       config :port, 6166
 
+      # The host method configures the hostname for the SSH tunnel specification.
+      #
+      # This method sets up the host parameter that will be used in the SSH tunnel
+      # configuration, allowing connections to be established through the specified
+      # host address.
+      #
+      # @param value [ String ] the hostname or IP address to use for the SSH tunnel
       config :host, 'localhost'
 
+      # The host_port method configures the host port setting for the
+      # application.
+      #
+      # @param value [ Integer ] the port number to be used for host communication
       config :host_port, 6166
 
+      # The to_s method returns a colon-separated string representation of the
+      # SSH tunnel specification.
+      #
+      # This method combines the bind address, port, host, and host port components
+      # into a single string format using colons as separators.
+      #
+      # @return [ String ] a colon-separated string containing the tunnel specification
+      #         in the format "bind_address:port:host:host_port"
       def to_s
         [ bind_address, port, host, host_port ] * ':'
       end
     end
 
+    # The copy_paste method manages the copy-paste functionality by returning
+    # an existing instance or creating a new one.
+    #
+    # This method checks if a copy-paste instance already exists and returns it
+    # if available. If no instance exists, it creates a new one based on
+    # whether a block is provided or
+    # the enable flag is set to true.
+    #
+    # @param enable [ TrueClass, FalseClass ] flag to enable copy-paste functionality
+    #
+    # @yield [ block ] optional block to initialize the copy-paste instance
+    #
+    # @return [ CopyPaste, nil ] the existing or newly created copy-paste
+    # instance, or nil if not enabled
     def copy_paste(enable = false, &block)
       if @copy_paste
         @copy_paste
@@ -253,11 +622,27 @@ class Utils::ConfigFile
   end
 
   class Edit < BlockConfig
+    # The vim_path method determines the path to the vim executable.
+    #
+    # This method executes the which command to locate the vim executable in
+    # the system's PATH and returns the resulting path after stripping any
+    # trailing whitespace.
+    #
+    # @return [ String ] the full path to the vim executable as determined by the which command
     config :vim_path do `which vim`.chomp end
 
     config :vim_default_args, nil
   end
 
+  # The edit method initializes and returns an Edit object.
+  #
+  # This method creates an Edit instance either from a provided block or with
+  # default settings. It stores the Edit object as an instance variable and
+  # returns it on subsequent calls.
+  #
+  # @param block [ Proc ] optional block to configure the Edit object
+  #
+  # @return [ Edit ] an Edit object configured either by the block or with default settings
   def edit(&block)
     if block
       @edit = Edit.new(&block)
@@ -266,11 +651,35 @@ class Utils::ConfigFile
   end
 
   class Classify < BlockConfig
+    # The shift_path_by_default method configuration accessor
+    #
+    # This method provides access to the shift_path_by_default configuration
+    # setting which determines the default path shifting value used in various
+    # operations.
+    #
+    # @return [ Integer ] the default path shifting value configured for the system
     config :shift_path_by_default, 0
 
+    # The shift_path_for_prefix method configures path shifting behavior for
+    # prefix handling.
+    #
+    # This method sets up the configuration for how paths should be shifted
+    # when dealing with prefix-based operations, typically used in file system
+    # or directory navigation contexts.
+    #
+    # @param config [ Array ] the configuration array for shift path settings
     config :shift_path_for_prefix, []
   end
 
+  # The classify method initializes and returns a Classify object.
+  #
+  # This method creates a Classify instance either from the provided block or
+  # with default settings if no block is given. It ensures that only one
+  # Classify object is created per instance by storing it in an instance variable.
+  #
+  # @param block [ Proc ] optional block to configure the Classify object
+  #
+  # @return [ Classify ] a Classify object configured either by the block or with defaults
   def classify(&block)
     if block
       @classify = Classify.new(&block)
@@ -279,13 +688,41 @@ class Utils::ConfigFile
   end
 
   class SyncDir < BlockConfig
+    # The skip_path method configures a regular expression pattern for skipping
+    # paths.
+    #
+    # This method sets up a configuration option that defines a regular
+    # expression used to identify and skip certain paths during processing
+    # operations.
+    #
+    # @param pattern [ Regexp ] the regular expression pattern used to match
+    # paths to be skipped
     config :skip_path, %r((\A|/)\.\w)
 
+    # The skip? method determines whether a given path should be skipped based
+    # on the skip_path pattern.
+    #
+    # This method checks if the provided path matches the internal skip_path
+    # regular expression, returning true if the path should be excluded from
+    # processing, or false otherwise.
+    #
+    # @param path [ String ] the path to check against the skip pattern
+    #
+    # @return [ TrueClass, FalseClass ] true if the path matches the skip
+    # pattern, false otherwise
     def skip?(path)
       path =~ skip_path
     end
   end
 
+  # The sync_dir method provides access to a SyncDir instance.
+  #
+  # This method returns the existing SyncDir instance if one has already been
+  # created, or initializes and returns a new SyncDir instance if no instance
+  # exists. If a block is provided, it will be passed to the SyncDir constructor
+  # when creating a new instance.
+  #
+  # @return [ SyncDir ] the SyncDir instance associated with this object
   def sync_dir(&block)
     if block
       @sync_dir = SyncDir.new(&block)
@@ -293,6 +730,13 @@ class Utils::ConfigFile
     @sync_dir ||= SyncDir.new
   end
 
+  # The to_ruby method generates a Ruby configuration string by collecting
+  # configuration data from various components and combining them into a
+  # single formatted output.
+  #
+  # @return [ String ] a Ruby formatted string containing configuration
+  #         settings from search, discover, strip_spaces, probe, ssh_tunnel,
+  #         edit, and classify components
   def to_ruby
     result = "# vim: set ft=ruby:\n"
     for bc in %w[search discover strip_spaces probe ssh_tunnel edit classify]