tins 1.43.0 → 1.44.0

data/lib/tins/method_description.rb

@@ -1,64 +1,115 @@
 module Tins
+  # Provides methods for describing method signatures and parameters.
+  #
+  # This module is designed to be included in method objects to provide
+  # introspection capabilities, particularly useful for generating
+  # documentation or debugging method signatures.
   module MethodDescription
+    # Represents individual parameters with specific types and names.
     class Parameters
+      # Base class for all parameter types.
       class Parameter < Struct.new(:type, :name)
+        # Compares two parameters by their type.
+        #
+        # @param other [Parameter] The other parameter to compare against
+        # @return [Boolean] Whether the types are equal
         def ==(other)
           type == other.type
         end
 
+        # Returns a string representation of the parameter for debugging.
+        #
+        # @return [String] A debug-friendly representation
         def inspect
           "#<#{self.class} #{to_s.inspect}>"
         end
       end
 
+      # Represents a splat parameter (*args).
       class RestParameter < Parameter
+        # Converts the parameter to its string form.
+        #
+        # @return [String] Formatted as "*name"
         def to_s
           "*#{name}"
         end
       end
 
+      # Represents a keyword rest parameter (**kwargs).
       class KeyrestParameter < Parameter
+        # Converts the parameter to its string form.
+        #
+        # @return [String] Formatted as "**name"
         def to_s
           "**#{name}"
         end
       end
 
+      # Represents a required parameter.
       class ReqParameter < Parameter
+        # Converts the parameter to its string form.
+        #
+        # @return [String] The parameter name
         def to_s
           name.to_s
         end
       end
 
+      # Represents an optional parameter (with default value).
       class OptParameter < Parameter
+        # Converts the parameter to its string form.
+        #
+        # @return [String] Formatted as "name=..."
         def to_s
-          "#{name}=?"
+          "#{name}=…"
         end
       end
 
+      # Represents a keyword parameter.
       class KeyParameter < Parameter
+        # Converts the parameter to its string form.
+        #
+        # @return [String] Formatted as "name:..."
         def to_s
-          "#{name}:?"
+          "#{name}:…"
         end
       end
 
+      # Represents a required keyword parameter (without default).
       class KeyreqParameter < Parameter
+        # Converts the parameter to its string form.
+        #
+        # @return [String] Formatted as "name:"
         def to_s
           "#{name}:"
         end
       end
 
+      # Represents a block parameter (&block).
       class BlockParameter < Parameter
+        # Converts the parameter to its string form.
+        #
+        # @return [String] Formatted as "&name"
         def to_s
           "&#{name}"
         end
       end
 
+      # Represents a generic parameter type not covered by other classes.
       class GenericParameter < Parameter
+        # Converts the parameter to its string form.
+        #
+        # @return [String] Formatted as "name:type"
         def to_s
           [ name, type ] * ?:
         end
       end
 
+      # Builds a parameter instance based on type and name.
+      #
+      # @param type [Symbol] The type of parameter (e.g., :req, :opt)
+      # @param name [String, Symbol] The parameter name
+      # @return [Parameter] An appropriate Parameter subclass or GenericParameter
       def self.build(type, name)
         parameter_classname = "#{type.to_s.capitalize}Parameter"
         parameter_class =
@@ -71,38 +122,70 @@ module Tins
       end
     end
 
+    # Represents the signature of a method including all its parameters.
     class Signature
+      # Initializes a new signature with given parameters.
+      #
+      # @param parameters [Array<Parameters::Parameter>] The list of parameters
       def initialize(*parameters)
         @parameters = parameters
       end
 
+      # Returns the parameters associated with this signature.
+      #
+      # @return [Array<Parameters::Parameter>] The method's parameters
       attr_reader :parameters
 
+      # Checks if two signatures are equal based on their parameters.
+      #
+      # @param other [Signature] The other signature to compare against
+      # @return [Boolean] Whether the signatures are equal
       def eql?(other)
         @parameters.eql? other.parameters
       end
 
+      # Checks if two signatures are equal (alias for eql?).
+      #
+      # @param other [Signature] The other signature to compare against
+      # @return [Boolean] Whether the signatures are equal
       def ==(other)
         @parameters == other.parameters
       end
 
+      # Pattern matching operator for comparing with a method's signature.
+      #
+      # @param method [Method] The method whose signature we're checking
+      # @return [Boolean] Whether this signature matches the method's signature
       def ===(method)
         self == method.signature
       end
 
+      # Converts the signature to a comma-separated string.
+      #
+      # @return [String] The parameters formatted as a string
       def to_s
         @parameters * ?,
       end
 
+      # Returns a detailed string representation for debugging.
+      #
+      # @return [String] A debug-friendly representation of the signature
       def inspect
         "#<#{self.class} (#{to_s})>"
       end
     end
 
+    # Retrieves the signature of the method this module is included in.
+    #
+    # @return [Signature] The method's signature
     def signature
       description style: :parameters
     end
 
+    # Generates a human-readable description of the method.
+    #
+    # @param style [:namespace, :name, :parameters] The output format style
+    # @return [String, Signature] The formatted description or signature object
     def description(style: :namespace)
       valid_styles = %i[ namespace name parameters ]
       valid_styles.include?(style) or
@@ -122,10 +205,10 @@ module Tins
           return signature
         end
       end
-      result = ''
+      result = +''
       if style == :namespace
         if owner <= Module
-          result << receiver.to_s << ?. # XXX Better to use owner here as well?
+          result << receiver.to_s << ?.
         else
           result << owner.name.to_s << ?#
         end

data/lib/tins/minimize.rb

@@ -1,19 +1,43 @@
 module Tins
-  # This module can be mixed into all classes, whose instances respond to the
-  # [] and size-methods, like for example Array. The returned elements from []
-  # should respond to the succ method.
+  # Tins::Minimize provides methods for compressing sequential data into ranges
+  # and expanding ranges back into individual elements.
+  #
+  # This module is designed for objects that respond to `[]` and `size` methods,
+  # such as Array, and whose elements respond to the `succ` method (like String
+  # and Numeric types). It's particularly useful for representing sequential data
+  # more compactly and efficiently.
+  #
+  # @example Basic minimization
+  #   [ 'A', 'B', 'C', 'G', 'K', 'L', 'M' ].minimize
+  #   # => [ 'A'..'C', 'G'..'G', 'K'..'M' ]
+  #
+  # @example Numeric minimization
+  #   [ 1, 2, 3, 7, 9, 10, 11 ].minimize
+  #   # => [ 1..3, 7..7, 9..11 ]
+  #
+  # @example Sorting before minimization
+  #   [ 5, 1, 4, 2 ].sort.minimize
+  #   # => [ 1..2, 4..5 ]
+  #
+  # @example Unminimization
+  #   [ 'A'..'C', 'G'..'G', 'K'..'M' ].unminimize
+  #   # => [ 'A', 'B', 'C', 'G', 'K', 'L', 'M' ]
   module Minimize
     # Returns a minimized version of this object, that is successive elements
     # are substituted with ranges a..b. In the situation ..., x, y,... and y !=
     # x.succ a range x..x is created, to make it easier to iterate over all the
-    # ranges in one run. A small example:
-    #  [ 'A', 'B', 'C', 'G', 'K', 'L', 'M' ].minimize # => [ 'A'..'C', 'G'..'G', 'K'..'M' ]
+    # ranges in one run.
     #
-    # If the order of the original elements doesn't matter, it's a good idea to
-    # first sort them and then minimize:
-    #  [ 5, 1, 4, 2 ].sort.minimize # => [ 1..2, 4..5 ]
+    # @return [Array<Range>] An array of ranges representing the minimized data
+    # @example Sequential string elements
+    #   [ 'A', 'B', 'C', 'G', 'K', 'L', 'M' ].minimize
+    #   # => [ 'A'..'C', 'G'..'G', 'K'..'M' ]
+    #
+    # @example Numeric elements
+    #   [ 1, 2, 3, 7, 9, 10, 11 ].minimize
+    #   # => [ 1..3, 7..7, 9..11 ]
     def minimize
-      result = []
+      result     = []
       last_index = size - 1
       size.times do |i|
         result << [ self[0] ] if i == 0
@@ -27,6 +51,8 @@ module Tins
 
     # First minimizes this object, then calls the replace method with the
     # result.
+    #
+    # @return [Object] Returns self (modified in place)
     def minimize!
       replace minimize
     end
@@ -35,6 +61,8 @@ module Tins
     #  [ 'A'..'C', 'G'..'G', 'K'..'M' ].unminimize # => [ 'A', 'B', 'C', 'G', 'K', 'L', 'M' ]
     # and
     #  [ 1..2, 4..5 ].unminimize # => [ 1, 2, 4, 5 ]
+    #
+    # @return [Array] An array of individual elements expanded from ranges
     def unminimize
       result = []
       for range in self
@@ -46,10 +74,10 @@ module Tins
     end
 
     # Invert a minimized version of this object in place.
+    #
+    # @return [Object] Returns self (modified in place)
     def unminimize!
       replace unminimize
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/module_group.rb

@@ -1,5 +1,32 @@
 module Tins
+  # A module that allows grouping multiple modules together for type checking.
+  #
+  # This implementation creates a shared module that gets included in each of the
+  # specified modules, enabling the use of `===` for type checking across all
+  # grouped modules simultaneously.
   module ModuleGroup
+    # Creates a new module group from the given modules.
+    #
+    # This method dynamically creates an anonymous module and includes it in
+    # each of the provided modules. The returned module can then be used with
+    # the `===` operator for type checking across all grouped modules.
+    #
+    # @note This modifies the included modules by adding the new module to their
+    #   inheritance chain, which can have side effects in complex class hierarchies.
+    #
+    # @param modules [Array<Module>] One or more modules to include in this group
+    # @return [Module] A new anonymous module that is included in all passed modules
+    #
+    # @example Creating a module group
+    #   MyGroup = Tins::ModuleGroup[Array, String, Hash]
+    #   MyGroup === []     # => true
+    #   MyGroup === ""     # => true
+    #   MyGroup === {}     # => true
+    #
+    #   case some_value
+    #   when MyGroup
+    #     handle_collection_or_string(some_value)
+    #   end
     def self.[](*modules)
       modul = Module.new
       modules.each do |m|
@@ -9,5 +36,3 @@ module Tins
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/named_set.rb

@@ -1,12 +1,32 @@
 require 'set'
 
 module Tins
+  # NamedSet extends Ruby's Set class to include a descriptive name.
+  #
+  # This class provides all the functionality of Ruby's standard Set while
+  # adding a named identifier that can be useful for debugging, logging, and
+  # identification purposes. The name is stored as an instance variable and can
+  # be accessed or modified
+  # through the `name` accessor.
+  #
+  # @example Basic usage
+  #   set = Tins::NamedSet.new("user_roles")
+  #   set.add(:admin)
+  #   set.add(:user)
+  #   puts set.name  # => "user_roles"
+  #   puts set.to_a  # => [:admin, :user]
   class NamedSet < Set
+    # Initializes a new NamedSet with the given name.
+    #
+    # @param name [String] A descriptive name for this set
     def initialize(name)
       @name = name
       super()
     end
 
+    # Gets or sets the name of this NamedSet.
+    #
+    # @return [String] The current name of the set
     attr_accessor :name
   end
 end

data/lib/tins/null.rb

@@ -1,68 +1,131 @@
 module Tins
-  # Implementation of the null object pattern in Ruby.
+  # Tins::Null provides an implementation of the null object pattern in Ruby.
+  #
+  # The null object pattern is a behavioral design pattern that allows you to
+  # avoid null references by providing a default object that implements the
+  # expected interface but does nothing. This eliminates the need for null
+  # checks throughout your codebase.
+  #
+  # This module provides the core functionality for null objects, including:
+  # - Method missing behavior that returns self
+  # - Type conversion methods that return appropriate default values
+  # - Debugging support through NullPlus
+  #
+  # @example Basic usage
+  #   # Instead of checking for nil:
+  #   user = find_user(id)
+  #   if user
+  #     user.name
+  #   else
+  #     "Unknown"
+  #   end
+  #
+  #   # You can use the null object:
+  #   user = find_user(id) || Tins::NULL
+  #   user.name  # => "" (instead of nil)
+  #
+  # @example With NullPlus for debugging
+  #   user = find_user(id) || Tins::NullPlus.new(value: "Unknown", caller: caller)
+  #   user.value  # => "Unknown"
   module Null
+    # Handle missing methods by returning self, allowing method chaining.
+    #
+    # @return [self] Always returns self to allow chaining
     def method_missing(*)
       self
     end
 
+    # Handle missing constants by returning self.
+    #
+    # @return [self] Always returns self
     def const_missing(*)
       self
     end
 
+    # Convert to string representation.
+    #
+    # @return [String] Empty string
     def to_s
       ''
     end
 
-    def to_str
-      nil
-    end
-
+    # Convert to float.
+    #
+    # @return [Float] Zero as float
     def to_f
       0.0
     end
 
+    # Convert to integer.
+    #
+    # @return [Integer] Zero
     def to_i
       0
     end
 
-    def to_int
-      nil
-    end
-
+    # Convert to array.
+    #
+    # @return [Array] Empty array
     def to_a
       []
     end
 
-    def to_ary
-      nil
-    end
-
+    # Inspect representation.
+    #
+    # @return [String] "NULL"
     def inspect
       'NULL'
     end
 
+    # Check if object is nil.
+    #
+    # @return [Boolean] Always returns true
     def nil?
       true
     end
 
+    # Check if object is blank.
+    #
+    # @return [Boolean] Always returns true
     def blank?
       true
     end
 
+    # Convert to JSON (for compatibility with JSON serialization).
+    #
+    # @return [nil] returns nil value
     def as_json(*)
+      nil
     end
 
+    # Convert to JSON string.
+    #
+    # @return [String] "null"
     def to_json(*)
       'null'
     end
 
+    # Kernel extensions for null object creation.
     module Kernel
+      # Create a null object or return the provided value if not nil.
+      #
+      # @param value [Object] The value to check
+      # @return [Object] Tins::NULL if value is nil, otherwise value
       def null(value = nil)
         value.nil? ? Tins::NULL : value
       end
 
       alias Null null
 
+      # Create a null object with additional debugging information.
+      #
+      # This creates a NullPlus object that includes caller information for
+      # debugging purposes when the null object is used.
+      #
+      # @param opts [Hash] Options for the null object
+      # @option opts [Object] :value The value to return from the null object
+      # @option opts [Array] :caller Caller information
+      # @return [Object] Tins::NullPlus if value is nil, otherwise value
       def null_plus(opts = {})
         value = opts[:value]
         opts[:caller] = caller
@@ -77,17 +140,27 @@ module Tins
     end
   end
 
+  # NullClass represents the singleton null object instance.
   class NullClass < Module
     include Tins::Null
   end
 
+  # The singleton null object instance.
   NULL = NullClass.new
 
+  # Freeze the singleton to prevent modification.
   NULL.freeze
 
+  # Enhanced null object with debugging capabilities.
+  #
+  # NullPlus extends the basic null object with additional features for debugging,
+  # including caller information and custom attribute access.
   class NullPlus
     include Tins::Null
 
+    # Initialize a NullPlus object with options.
+    #
+    # @param opts [Hash] Configuration options
     def initialize(opts = {})
       singleton_class.class_eval do
         opts.each do |name, value|
@@ -97,5 +170,3 @@ module Tins
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/once.rb

@@ -1,9 +1,52 @@
 module Tins
+  # A module for ensuring exclusive execution of code blocks using file-based
+  # locking.
+  #
+  # This module provides mechanisms to prevent multiple instances of a script
+  # from running simultaneously by using file system locks on the script itself
+  # or a specified lock file.
+  #
+  # @example Basic usage with automatic lock file detection
+  #   Tins::Once.only_once do
+  #     # Critical section - only one instance runs at a time
+  #     perform_backup()
+  #   end
+  #
+  # @example Using custom lock file
+  #   Tins::Once.only_once("/var/run/myapp.lock") do
+  #     # Custom lock file
+  #     process_data()
+  #   end
+  #
+  # @example Non-blocking attempt
+  #   begin
+  #     Tins::Once.try_only_once do
+  #       # Will raise if another instance holds the lock
+  #       update_cache()
+  #     end
+  #   rescue => e
+  #     puts "Another instance is running"
+  #   end
   module Once
     include File::Constants
 
-    module_function
-
+    # Executes a block of code exclusively, ensuring only one instance runs at
+    # a time.
+    #
+    # Uses the script name (or specified lock file) as the locking mechanism.
+    # The first invocation will acquire an exclusive lock and execute the
+    # block, while subsequent invocations will block until the lock is
+    # released.
+    #
+    # @param lock_filename [String] Optional custom lock filename.
+    #   Defaults to `$0` (the script name), which means the script itself
+    #   is used as the lock file.
+    # @param locking_constant [Integer] File locking constant.
+    #   Defaults to `LOCK_EX` for exclusive locking.
+    # @yield [void] The block of code to execute exclusively
+    # @return [Object] The return value of the yielded block
+    # @raise [Errno::ENOENT] If the lock file doesn't exist
+    # @raise [SystemCallError] If file locking fails
     def only_once(lock_filename = nil, locking_constant = nil)
       lock_filename ||= $0
       locking_constant ||= LOCK_EX
@@ -16,10 +59,24 @@ module Tins
       end
     end
 
+    # Attempts to execute a block of code exclusively, but fails immediately
+    # if another instance holds the lock.
+    #
+    # This is a non-blocking version that will raise an exception if the lock
+    # cannot be acquired immediately.
+    #
+    # @param lock_filename [String] Optional custom lock filename.
+    #   Defaults to `$0` (the script name).
+    # @param locking_constant [Integer] File locking constant.
+    #   Defaults to `LOCK_EX | LOCK_NB` for non-blocking exclusive locking.
+    # @yield [void] The block of code to execute exclusively
+    # @return [Object] The return value of the yielded block
+    # @raise [Errno::EAGAIN] If another process holds the lock
+    # @raise [Errno::ENOENT] If the lock file doesn't exist
     def try_only_once(lock_filename = nil, locking_constant = nil, &block)
       only_once(lock_filename, locking_constant || LOCK_EX | LOCK_NB, &block)
     end
+
+    module_function :only_once, :try_only_once
   end
 end
-
-require 'tins/alias'

data/lib/tins/p.rb

@@ -1,23 +1,59 @@
 require 'pp'
 
 module Tins
+  # A module that provides debugging methods for inspecting objects by raising
+  # exceptions with their inspected representations.
+  #
+  # This module adds p! and pp! methods that raise RuntimeError exceptions
+  # containing the inspected or pretty-inspected output of objects, making it
+  # easy to quickly debug values during development without printing to stdout.
+  #
+  # @example Using p! to inspect a single object
+  #   p!(some_variable)
+  #
+  # @example Using pp! to inspect multiple objects
+  #   pp!(first_var, second_var)
   module P
     private
 
-    # Raise a runtime error with the inspected objects +objs+ (obtained by
-    # calling the #inspect method) as their message text. This is useful for
-    # quick debugging.
+    # Raises a RuntimeError with the inspected representation of the given
+    # objects.
+    #
+    # This method is useful for quick debugging by raising an exception that
+    # contains the inspected output of the provided objects. It behaves
+    # similarly to Ruby's built-in +p+ method but raises an exception instead
+    # of printing to stdout.
+    #
+    # @example Basic usage with single object
+    #   p!(some_variable)
+    #
+    # @example Basic usage with multiple objects
+    #   p!(first_var, second_var)
+    #
+    # @param objs [Array<Object>] One or more objects to inspect and raise
+    # @raise [RuntimeError] Always raises a RuntimeError with inspected content
     def p!(*objs)
       raise((objs.size < 2 ? objs.first : objs).inspect)
     end
 
-    # Raise a runtime error with the inspected objects +objs+ (obtained by
-    # calling the #pretty_inspect method) as their message text. This is useful
-    # for quick debugging.
+    # Raises a RuntimeError with the pretty-inspected representation of the
+    # given objects.
+    #
+    # This method is useful for quick debugging by raising an exception that
+    # contains the pretty-printed output of the provided objects. It behaves
+    # similarly to Ruby's built-in +pp+ method but raises an exception instead
+    # of printing to stdout.
+    #
+    # @example Basic usage with single object
+    #   pp!(some_variable)
+    #
+    # @example Basic usage with multiple objects
+    #   pp!(first_var, second_var)
+    #
+    # @param objs [Array<Object>] One or more objects to pretty-inspect and raise
+    # @raise [RuntimeError] Always raises a RuntimeError with pretty-inspected content
     def pp!(*objs)
       raise("\n" + (objs.size < 2 ? objs.first : objs).pretty_inspect.chomp)
     end
   end
 end
-
-require 'tins/alias'