tins 1.32.0 → 1.44.0

data/lib/tins/memoize.rb

@@ -1,91 +1,119 @@
 require 'tins/extract_last_argument_options'
+require 'mize'
 
 module Tins
+  # Provides memoization functionality for methods and functions with support
+  # for instance-level and class-level caching respectively.
+  #
+  # @example Basic method memoization
+  #   class Calculator
+  #     def expensive_calculation(x, y)
+  #       # Some expensive computation
+  #       x * y
+  #     end
+  #     memoize_method :expensive_calculation
+  #   end
+  #
+  # @example Function memoization (shared across instances)
+  #   class MathUtils
+  #     def self.factorial(n)
+  #       n <= 1 ? 1 : n * factorial(n - 1)
+  #     end
+  #     memoize_function :factorial
+  #   end
+  #
+  # @example With freezing results
+  #   class DataProcessor
+  #     def process_data(input)
+  #       # Process data and return result
+  #       input.dup
+  #     end
+  #     memoize_method :process_data, freeze: true
+  #   end
+  #
+  # @note This module is deprecated in favor of the {https://github.com/flori/mize mize} gem.
+  #       Use `memoize method:` or `memoize function:` from the mize gem directly.
   module Memoize
+    # Provides cache management methods for memoized functions and methods.
+    # This module is included in classes that use memoization functionality.
+    #
+    # @example Using cache methods directly
+    #   class Example
+    #     include Tins::Memoize::CacheMethods
+    #
+    #     def expensive_method
+    #       # Some expensive computation
+    #     end
+    #     memoize_method :expensive_method
+    #   end
+    #
+    #   obj = Example.new
+    #   obj.memoize_cache_clear  # Clear all cached values
+    #   obj.__memoize_cache__    # Access the internal cache object
     module CacheMethods
-      # Return the cache object.
+      # Return the cache object used for memoization.
+      #
+      # @return [Object] The cache instance
       def __memoize_cache__
-        @__memoize_cache__ ||= {}
+        if @__memoize_cache__
+          @__memoize_cache__
+        else
+          @__memoize_cache__ = __mize_cache__
+          def @__memoize_cache__.empty?
+            @data.empty?
+          end
+          @__memoize_cache__
+        end
       end
 
-      # Clear cached values for all methods/functions.
+      # Clear cached values for all methods/functions of this object.
+      #
+      # @return [self] For chaining
       def memoize_cache_clear
          __memoize_cache__.clear
         self
       end
-
-      def memoize_apply_visibility(id)
-        visibility = instance_eval do
-          case
-          when private_method_defined?(id)
-            :private
-          when protected_method_defined?(id)
-            :protected
-          end
-        end
-        yield
-      ensure
-        visibility and __send__(visibility, id)
-      end
     end
 
     class ::Module
-      # Automatically memoize calls of the the methods +method_ids+. The
-      # memoized results do NOT ONLY depend on the arguments, but ALSO on the
-      # object the method is called on.
+      # Memoize a method so that its return value is cached based on the arguments
+      # and the object instance. Each instance maintains its own cache.
+      #
+      # @param method_ids [Array<Symbol>] One or more method names to memoize
+      # @option opts [Boolean] :freeze (false) Whether to freeze results
+      # @return [Symbol, Array<Symbol>] The memoized method name(s)
+      #
+      # @deprecated Use `memoize method:` from the mize gem instead.
       def memoize_method(*method_ids)
+        warn "[DEPRECATION] `memoize_method` is deprecated. Please use `memoize method:` from mize gem."
         method_ids.extend(ExtractLastArgumentOptions)
         method_ids, opts = method_ids.extract_last_argument_options
-        include CacheMethods
-        method_ids.each do |method_id|
-          method_id = method_id.to_s.to_sym
-          memoize_apply_visibility method_id do
-            orig_method = instance_method(method_id)
-            __send__(:define_method, method_id) do |*args|
-              mc = __memoize_cache__
-              if mc.key?(method_id) and result = mc[method_id][args]
-                result
-              else
-                (mc[method_id] ||= {})[args] = result = orig_method.bind(self).call(*args)
-                $DEBUG and warn "#{self.class} cached method #{method_id}(#{args.inspect unless args.empty?}) = #{result.inspect} [#{__id__}]"
-                opts[:freeze] and result.freeze
-              end
-              result
-            end
-          end
+        method_ids.each do |method|
+          memoize method:, **opts.slice(:freeze)
         end
+        include CacheMethods
         method_ids.size == 1 ? method_ids.first : method_ids
       end
 
       include CacheMethods
 
-      # Automatically memoize calls of the functions +function_ids+. The
-      # memoized result does ONLY depend on the arguments given to the
-      # function.
+      # Memoize a function (class method) so that its return value is cached
+      # based only on the arguments, shared across all instances of the class.
+      #
+      # @param function_ids [Array<Symbol>] One or more function names to memoize
+      # @option opts [Boolean] :freeze (false) Whether to freeze results
+      # @return [Symbol, Array<Symbol>] The memoized function name(s)
+      #
+      # @deprecated Use `memoize function:` from the mize gem instead.
       def memoize_function(*function_ids)
+        warn "[DEPRECATION] `memoize_function` is deprecated. Please use `memoize function:` from mize gem."
         function_ids.extend(ExtractLastArgumentOptions)
         function_ids, opts = function_ids.extract_last_argument_options
-        mc = __memoize_cache__
-        function_ids.each do |function_id|
-          function_id = function_id.to_s.to_sym
-          memoize_apply_visibility function_id do
-            orig_function = instance_method(function_id)
-            __send__(:define_method, function_id) do |*args|
-              if mc.key?(function_id) and result = mc[function_id][args]
-                result
-              else
-                (mc[function_id] ||= {})[args] = result = orig_function.bind(self).call(*args)
-                opts[:freeze] and result.freeze
-                $DEBUG and warn "#{self.class} cached function #{function_id}(#{args.inspect unless args.empty?}) = #{result.inspect}"
-              end
-              result
-            end
-          end
+        function_ids.each do |function|
+          memoize function:, **opts.slice(:freeze)
         end
         function_ids.size == 1 ? function_ids.first : function_ids
       end
     end
   end
 end
-
-require 'tins/alias'

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