tins 1.43.0 → 1.44.0

data/lib/tins/find.rb

@@ -3,57 +3,116 @@ require 'pathname'
 require 'tins/module_group'
 
 module Tins
+  # This module provides file system traversal functionality with support for
+  # filtering by file type, handling of hidden files, and error management.
+  #
+  # The Find module implements a depth-first search algorithm that traverses
+  # directory trees, yielding each path to the provided block. It handles
+  # various edge cases including symbolic links, permission errors, and
+  # circular references.
+  #
+  # @example Basic usage
+  #   Tins::Find.find('/path/to/directory') do |path|
+  #     puts path
+  #   end
+  #
+  # @example Find files with specific extension
+  #   Tins::Find.find('/path/to/directory', suffix: 'rb') do |path|
+  #     puts path
+  #   end
+  #
+  # @example Skip directories and files
+  #   Tins::Find.find('/path/to/directory') do |path|
+  #     if File.directory?(path)
+  #       Tins::Find.prune  # Skip this directory and its contents
+  #     else
+  #       puts path
+  #     end
+  #   end
   module Find
+    # Standard errors that are expected during file system operations
+    # and will be silently handled unless raise_errors is enabled
     EXPECTED_STANDARD_ERRORS = ModuleGroup[
       Errno::ENOENT, Errno::EACCES, Errno::ENOTDIR, Errno::ELOOP,
       Errno::ENAMETOOLONG
     ]
 
+    # The Finder class implements the core file system traversal logic.
+    # It handles path processing, error management, and directory traversal.
     class Finder
+      # Extension module that adds convenience methods to Pathname objects
+      # during the find operation. These methods provide access to finder
+      # functionality and handle errors gracefully.
       module PathExtension
         attr_accessor :finder
 
+        # Gets the stat information for this path, handling errors appropriately
+        # @return [File::Stat, nil] File statistics or nil on error
         def finder_stat
           finder.protect_from_errors do
             finder.follow_symlinks ? File.stat(self) : File.lstat(self)
           end
         end
 
+        # Opens the file if it's a regular file
+        # @return [File, nil] File object or nil if not a file
         def file
           finder.protect_from_errors do
             File.new(self) if file?
           end
         end
 
+        # Checks if this path represents a regular file
+        # @return [Boolean] true if the path is a regular file
         def file?
           finder.protect_from_errors { s = finder_stat and s.file? }
         end
 
+        # Checks if this path represents a directory
+        # @return [Boolean] true if the path is a directory
         def directory?
           finder.protect_from_errors { s = finder_stat and s.directory? }
         end
 
+        # Checks if this path exists
+        # @return [Boolean] true if the path exists
         def exist?
           finder.protect_from_errors { File.exist?(self) }
         end
 
+        # Gets the stat information for this path (follows symlinks)
+        # @return [File::Stat, nil] File statistics or nil on error
         def stat
           finder.protect_from_errors { File.stat(self) }
         end
 
+        # Gets the stat information for this path (does not follow symlinks)
+        # @return [File::Stat, nil] File statistics or nil on error
         def lstat
           finder.protect_from_errors { File.lstat(self) }
         end
 
+        # Creates a Pathname object from this path
+        # @return [Pathname] Pathname object for this path
         def pathname
           Pathname.new(self)
         end
 
+        # Gets the file extension without the leading dot
+        # @return [String] File extension or empty string if no extension
         def suffix
           pathname.extname[1..-1] || ''
         end
       end
 
+      # Initializes a new Finder instance with specified options
+      #
+      # @param opts [Hash] Configuration options
+      # @option opts [Boolean] :show_hidden (true) Whether to include hidden files/directories
+      # @option opts [Boolean] :raise_errors (false) Whether to raise exceptions on errors
+      # @option opts [Boolean] :follow_symlinks (true) Whether to follow symbolic links
+      # @option opts [Array<String, Symbol>] :suffix (nil) Filter by file extension(s)
+      # @option opts [Proc] :visit (nil) Custom filter predicate
       def initialize(opts = {})
         @show_hidden     = opts.fetch(:show_hidden)     { true }
         @raise_errors    = opts.fetch(:raise_errors)    { false }
@@ -68,14 +127,26 @@ module Tins
         end
       end
 
+      # Controls whether hidden files and directories are included in the search
+      # @return [Boolean]
       attr_accessor :show_hidden
 
+      # Controls whether errors during file system operations should be raised
+      # @return [Boolean]
       attr_accessor :raise_errors
 
+      # Controls whether symbolic links should be followed during traversal
+      # @return [Boolean]
       attr_accessor :follow_symlinks
 
+      # The file suffix filter, if specified
+      # @return [Array<String>] Array of allowed file extensions
       attr_accessor :suffix
 
+      # Determines if a path should be visited based on the configured filters
+      #
+      # @param path [String] The path to check
+      # @return [Boolean] true if the path should be visited
       def visit_path?(path)
         if !defined?(@visit) || @visit.nil?
           true
@@ -84,6 +155,11 @@ module Tins
         end
       end
 
+      # Performs a depth-first search of the specified paths
+      #
+      # @param paths [Array<String>] The root paths to search
+      # @yield [String] Each path that matches the criteria
+      # @return [Enumerator] If no block is given, returns an enumerator
       def find(*paths)
         block_given? or return enum_for(__method__, *paths)
         paths.collect! { |d| d.dup }
@@ -106,6 +182,10 @@ module Tins
         end
       end
 
+      # Prepares a path for processing by extending it with PathExtension
+      #
+      # @param path [String] The path to prepare
+      # @return [String] The prepared path object
       def prepare_path(path)
         path = path.dup
         path.extend PathExtension
@@ -113,6 +193,11 @@ module Tins
         path
       end
 
+      # Executes a block while protecting against expected standard errors
+      #
+      # @param errors [Array<Class>] Array of error classes to catch
+      # @yield [] the block to be protected
+      # @return [Object, nil] The result of the block or nil on error
       def protect_from_errors(errors = Find::EXPECTED_STANDARD_ERRORS)
         yield
       rescue errors
@@ -121,25 +206,43 @@ module Tins
       end
     end
 
+    # Performs a depth-first search of the specified paths, yielding each
+    # matching path to the block
     #
-    # Calls the associated block with the name of every path and directory
-    # listed as arguments, then recursively on their subdirectories, and so on.
+    # @param paths [Array<String>] The root paths to search
+    # @param opts [Hash] Configuration options
+    # @option opts [Boolean] :show_hidden (true) Whether to include hidden files/directories
+    # @option opts [Boolean] :raise_errors (false) Whether to raise exceptions on errors
+    # @option opts [Boolean] :follow_symlinks (true) Whether to follow symbolic links
+    # @option opts [Array<String, Symbol>] :suffix (nil) Filter by file extension(s)
+    # @option opts [Proc] :visit (nil) Custom filter predicate
+    # @yield [String] Each path that matches the criteria
+    # @return [Enumerator] If no block is given, returns an enumerator
     #
-    # See the +Find+ module documentation for an example.
+    # @example Basic usage
+    #   Tins::Find.find('/path/to/directory') do |path|
+    #     puts path
+    #   end
     #
-    def find(*paths, &block) # :yield: path
-      opts = Hash === paths.last ? paths.pop : {}
+    # @example Find only Ruby files
+    #   Tins::Find.find('/path/to/directory', suffix: 'rb') do |path|
+    #     puts path
+    #   end
+    def find(*paths, **opts, &block)
       Finder.new(opts).find(*paths, &block)
     end
 
-    #
     # Skips the current path or directory, restarting the loop with the next
-    # entry. If the current path is a directory, that directory will not be
-    # recursively entered. Meaningful only within the block associated with
-    # Find::find.
-    #
-    # See the +Find+ module documentation for an example.
+    # entry. Meaningful only within the block associated with Find.find.
     #
+    # @example Skip directories
+    #   Tins::Find.find('/path/to/directory') do |path|
+    #     if path.count(?/) < 3
+    #       Tins::Find.prune  # Skip all paths deeper than 2
+    #     else
+    #       puts path
+    #     end
+    #   end
     def prune
       throw :prune
     end

data/lib/tins/generator.rb

@@ -35,6 +35,16 @@ module Tins
       self
     end
 
+    # Recurses through nested enumerators to yield all combinations
+    #
+    # This method performs a recursive traversal of nested enumerators,
+    # building tuples by iterating through each enumerator at its respective
+    # level and yielding complete combinations when the deepest level is
+    # reached
+    #
+    # @param tuple [ Array ] the current tuple being built during recursion
+    # @param i [ Integer ] the current index/level in the recursion
+    # @yield [ Array ] yields a duplicate of the completed tuple
     def recurse(tuple = [ nil ] * @n, i = 0, &block)
       if i < @n - 1 then
         @enums[i].__send__(@iterators[i]) do |x|
@@ -64,5 +74,3 @@ module Tins
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/go.rb

@@ -1,17 +1,62 @@
 module Tins
+  # A command-line option parsing library that provides a flexible way to
+  # parse single-character options with optional arguments. It supports
+  # multiple values for the same flag and provides a clean API for handling
+  # command-line interfaces.
+  #
+  # @example Basic usage
+  #   # Parse options with pattern 'xy:z'
+  #   options = Tins::GO.go('xy:z', ARGV, defaults: { x: true, y: 'default' })
+  #   # Handles: -x -y value -z
+  #
+  # @example Multiple values for same option
+  #   # Handle: -f foo -f bar -f baz
+  #   options = Tins::GO.go('f:', ARGV)
+  #   # options['f'] will contain an EnumerableExtension collection with all
+  #   values, see `option['f'].to_a`
   module GO
+    # An extension module that provides Enumerable behavior for collecting
+    # multiple values associated with the same command-line option.
+    #
+    # This extension enables command-line flags like `-f foo -f bar` to be
+    # collected into a single collection that can be queried via #to_a or #each.
     module EnumerableExtension
+      # Adds an element to the collection.
+      #
+      # This method allows for chaining operations and collects multiple
+      # values for the same command-line option.
+      #
+      # @param argument [Object] The element to add to the collection
+      # @return [self] Returns self to enable method chaining
       def push(argument)
         @arguments ||= []
         @arguments.push argument
         self
       end
+
+      # Alias for {#push}
+      #
+      # Enables intuitive syntax for adding elements: `collection << item`
+      #
+      # @see #push
       alias << push
 
+      # Iterates over each element in the collection.
+      #
+      # Implements the Enumerable interface, allowing the use of all Enumerable
+      # methods like map, select, find, etc.
+      #
+      # @yield [element] Yields each element in the collection
+      # @yieldparam element [Object] Each element in the collection
+      # @return [self] Returns self to enable method chaining
       def each(&block)
         @arguments.each(&block)
         self
       end
+
+      # Includes the Enumerable module to provide rich iteration capabilities.
+      #
+      # This enables the use of methods like map, select, find, etc.
       include Enumerable
     end
 
@@ -25,8 +70,42 @@ module Tins
     #
     # The _defaults_ argument specifies default values for the options.
     #
-    # An option hash is returned with all found options set to true or the
-    # found option argument.
+    # An option hash is returned with all found options set to a truthy value
+    # representing the number of times they were encountered, or `false` if not
+    # present. When a default value is specified and the flag is not present,
+    # the default value is used instead.
+    #
+    # @param s [String] Option pattern string where each character represents
+    #   an option, and ':' indicates the option requires an argument
+    # @param args [Array<String>] Array of arguments to parse (defaults to ARGV)
+    # @param defaults [Hash{String => Object}] Default values for options
+    # @return [Hash{String => Object}] Hash mapping option names to their values
+    #
+    # @example Basic usage
+    #   # Parse options with pattern 'xy:z'
+    #   options = Tins::GO.go('xy:z', ARGV, defaults: { x: true, y: 'default' })
+    #   # Handles: -x -y value -z
+    #
+    # @example Multiple values for same option
+    #   # Handle: -f foo -f bar -f baz
+    #   options = Tins::GO.go('f:', ARGV)
+    #   # options['f'] will contain an EnumerableExtension collection with
+    #   # all values, see options['f'].to_a
+    #
+    # @example Boolean flag counting
+    #   # Handle: -x -x -x
+    #   options = Tins::GO.go('x', ARGV)
+    #   # options['x'] will be 3 (truthy numeric value)
+    #
+    # @example Boolean flag not present
+    #   # Handle: no -x flag
+    #   options = Tins::GO.go('x', ARGV)
+    #   # options['x'] will be false
+    #
+    # @example Disabling options with default values
+    #   # Handle: ~x (disables -x option) when x has a default value
+    #   options = Tins::GO.go('x', ARGV, defaults: { x: true })
+    #   # options['x'] will be false if no ~x flag is present
     def go(s, args = ARGV, defaults: {})
       d = defaults || {}
       b, v = s.scan(/(.)(:?)/).inject([ {}, {} ]) { |t, (o, a)|
@@ -92,5 +171,3 @@ module Tins
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/hash_bfs.rb

@@ -1,6 +1,10 @@
 require 'tins/thread_local'
 
 module Tins
+  # HashBFS module for breadth-first traversal of hash structures
+  #
+  # Provides methods to traverse hash structures in a breadth-first manner,
+  # visiting all keys and values while maintaining the order of traversal.
   module HashBFS
     extend Tins::ThreadLocal
 
@@ -63,5 +67,3 @@ module Tins
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/hash_symbolize_keys_recursive.rb

@@ -1,11 +1,52 @@
 require 'tins/thread_local'
 
 module Tins
+  # This module provides recursive symbolization of hash keys. It handles
+  # nested structures including hashes and arrays, with special handling for
+  # circular references to prevent infinite recursion.
+  #
+  # @example Basic usage
+  #   hash = { "name" => "John", "address" => { "street" => "123 Main St" } }
+  #   hash.symbolize_keys_recursive
+  #   # => { name: "John", address: { street: "123 Main St" } }
+  #
+  # @example Handling circular references
+  #   hash = { "name" => "John" }
+  #   hash["self"] = hash  # Circular reference
+  #   hash.symbolize_keys_recursive(circular: "[Circular Reference]")
+  #   # => { name: "John", self: "[Circular Reference]" }
   module HashSymbolizeKeysRecursive
     extend Tins::ThreadLocal
 
+    # Thread-local storage for tracking visited objects to handle circular
+    # references
     thread_local :seen
 
+    # Recursively converts all string keys in a hash (and nested hashes/arrays)
+    # to symbols. This method does not modify the original hash.
+    #
+    # @param circular [Object] The value to use when encountering circular references.
+    #   Defaults to nil, which means circular references will be ignored.
+    # @return [Hash, Array, Object] A new hash/array with symbolized keys
+    #
+    # @example Basic usage
+    #   { "name" => "John", "age" => 30 }.symbolize_keys_recursive
+    #   # => { name: "John", age: 30 }
+    #
+    # @example Nested structures
+    #   {
+    #     "user" => {
+    #       "name" => "John",
+    #       "hobbies" => ["reading", "swimming"]
+    #     }
+    #   }.symbolize_keys_recursive
+    #   # => { user: { name: "John", hobbies: ["reading", "swimming"] } }
+    #
+    # @example Circular reference handling
+    #   hash = { "name" => "John" }
+    #   hash["self"] = hash
+    #   hash.symbolize_keys_recursive(circular: "[Circular]")
+    #   # => { name: "John", self: "[Circular]" }
     def symbolize_keys_recursive(circular: nil)
       self.seen = {}
       _symbolize_keys_recursive(self, circular: circular)
@@ -13,17 +54,35 @@ module Tins
       self.seen = nil
     end
 
+    # Recursively converts all string keys in a hash (and nested hashes/arrays)
+    # to symbols. This method modifies the original hash in place.
+    #
+    # @param circular [Object] The value to use when encountering circular references.
+    #   Defaults to nil, which means circular references will be ignored.
+    # @return [Hash, Array, Object] The same hash/array with symbolized keys
+    #
+    # @example Basic usage
+    #   hash = { "name" => "John", "age" => 30 }
+    #   hash.symbolize_keys_recursive!
+    #   # => { name: "John", age: 30 }
+    #   # hash is now modified in place
     def symbolize_keys_recursive!(circular: nil)
       replace symbolize_keys_recursive(circular: circular)
     end
 
     private
 
+    # Performs the actual recursive symbolization work
+    #
+    # @param object [Object] The object to process
+    # @param circular [Object] The value to return for circular references
+    # @return [Object] The processed object with symbolized keys
     def _symbolize_keys_recursive(object, circular: nil)
       case
       when seen[object.__id__]
         object = circular
-      when Hash === object
+      when object.respond_to?(:to_hash)
+        object = object.to_hash
         seen[object.__id__] = true
         new_object = object.class.new
         seen[new_object.__id__] = true
@@ -31,7 +90,8 @@ module Tins
           new_object[k.to_s.to_sym] = _symbolize_keys_recursive(v, circular: circular)
         end
         object = new_object
-      when Array === object
+      when object.respond_to?(:to_ary)
+        object = object.to_ary
         seen[object.__id__] = true
         new_object = object.class.new(object.size)
         seen[new_object.__id__] = true
@@ -44,5 +104,3 @@ module Tins
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/hash_union.rb

@@ -1,5 +1,52 @@
 module Tins
+  # A module that provides union functionality for hash-like objects
+  #
+  # This module implements the | (pipe) operator for hashes, allowing them to be
+  # merged with other hash-like objects. The merge gives precedence to values from
+  # the other object, making it useful for configuration merging where default
+  # values should be overridden by user-provided options.
   module HashUnion
+    # Implements the | (union) operator for hash-like objects.
+    #
+    # Merges another hash-like object into this object, with the other taking
+    # precedence over self. This is useful for configuration merging where
+    # default values should be overridden by user-provided options.
+    #
+    # @example Basic usage
+    #   h1 = { a: 1, b: 2 }
+    #   h2 = { b: 3, c: 4 }
+    #   result = h1 | h2
+    #   # => { a: 1, b: 3, c: 4 }  # h2 values take precedence
+    #
+    # @example Configuration merging
+    #   default_options = {
+    #     format: :json,
+    #     timeout: 30,
+    #     retries: 3
+    #   }
+    #
+    #   user_options = { timeout: 60 }
+    #   options = user_options | default_options
+    #   # => { format: :json, timeout: 60, retries: 3 }
+    #
+    # @example With objects that respond to to_hash
+    #   class CustomHash
+    #     def to_hash
+    #       { x: 10, y: 20 }
+    #     end
+    #   end
+    #
+    #   custom = CustomHash.new
+    #   result = { a: 1 } | custom
+    #   # => { a: 1, x: 10, y: 20 }
+    #
+    # @param other [Hash, Object] Another hash-like object to merge with.
+    #   Can be a Hash, or any object that responds to either `to_hash` or `to_h`.
+    # @return [Hash] A new hash containing the merged key-value pairs
+    #
+    # @note The merge operation preserves the original hashes and returns a new
+    # hash. In case of duplicate keys, values from `other` will overwrite
+    # values from `self`.
     def |(other)
       case
       when other.respond_to?(:to_hash)
@@ -11,5 +58,3 @@ module Tins
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/if_predicate.rb

@@ -1,5 +1,36 @@
 module Tins
+  # A module that provides a predicate method for checking if a value is
+  # truthy.
+  #
+  # The IfPredicate module adds a #if? method to objects that returns true if
+  # the object is truthy, and false if it is falsy. This is useful for
+  # conditional logic where you want to check if
+  # an object evaluates to true in a boolean context.
   module IfPredicate
+    # A predicate method that returns the receiver if it's truthy,
+    # or nil if it's falsy.
+    #
+    # This method is designed to work in conditional expressions
+    # where you want to check if a value is truthy and either
+    # return it or handle the falsy case.
+    #
+    # @example Basic usage
+    #   true.if?     # => true
+    #   false.if?    # => nil
+    #   nil.if?      # => nil
+    #   "hello".if?  # => "hello"
+    #   "".if?       # => ""
+    #
+    # @example With default values
+    #   user = nil
+    #   name = user.if? || "Anonymous"
+    #   # => "Anonymous"
+    #
+    #   user = "John"
+    #   name = user.if? || "Anonymous"
+    #   # => "John"
+    #
+    # @return [Object, nil] The receiver if truthy, nil if falsy
     def if?
       self ? self : nil
     end

data/lib/tins/implement.rb

@@ -1,5 +1,32 @@
 module Tins
+  # Provides methods for defining abstract method implementations that raise
+  # NotImplementedError. Useful for creating interface-like modules or base
+  # classes where certain methods must be implemented by subclasses.
+  #
+  # @example Basic usage
+  #   module MyInterface
+  #     include Tins::Implement
+  #     implement :process
+  #   end
+  #
+  #   class MyClass
+  #     include MyInterface
+  #     # Must implement process method or it will raise NotImplementedError
+  #   end
+  #
+  # @example With custom messages
+  #   module ApiInterface
+  #     include Tins::Implement
+  #     implement :get_data, :subclass
+  #     implement :post_data, :submodule
+  #   end
+  #
+  # @see Tins::MethodDescription For method description integration
   module Implement
+    # Predefined error message templates for different implementation contexts.
+    #
+    # These templates provide context-specific error messages that help
+    # developers understand where and how methods should be implemented.
     MESSAGES = {
       default:   'method %{method_name} not implemented in module %{module}',
       subclass:  'method %{method_name} has to be implemented in '\
@@ -8,6 +35,21 @@ module Tins
         'submodules of %{module}',
     }
 
+    # Defines an implementation for a method that raises NotImplementedError.
+    #
+    # @param method_name [Symbol, String] The name of the method to implement
+    # @param msg [Symbol, String, Hash] The error message template or options
+    #   @option msg [Symbol] :in When msg is a Hash, specifies which message key to use
+    #
+    # @example Basic usage
+    #   implement :process
+    #   # => Defines process method that raises NotImplementedError
+    #
+    # @example Custom message
+    #   implement :calculate, 'Custom error message'
+    #
+    # @example Using predefined message template
+    #   implement :validate, :subclass
     def implement(method_name, msg = :default)
       method_name.nil? and return
       case msg
@@ -30,6 +72,14 @@ module Tins
       end
     end
 
+    # Defines an implementation for a method that raises NotImplementedError
+    # specifically for submodule implementations.
+    #
+    # @param method_name [Symbol, String] The name of the method to implement
+    #
+    # @example Usage
+    #   implement_in_submodule :render
+    #   # => Defines render method with submodule-specific error message
     def implement_in_submodule(method_name)
       implement method_name,
         'method %{method_name} has to be implemented in submodules of'\