tins 1.38.0 → 1.51.0

data/lib/tins/attempt.rb

@@ -1,4 +1,6 @@
 module Tins
+  # A module that provides functionality for attempting operations with error
+  # handling and retry logic.
   module Attempt
     # Attempts code in block *attempts* times, sleeping according to *sleep*
     # between attempts and catching the exception(s) in *exception_class*.
@@ -63,6 +65,11 @@ module Tins
 
     private
 
+    # The sleep_duration method handles sleeping for a specified duration or
+    # based on a proc call.
+    #
+    # @param duration [ Numeric, Proc ] the duration to sleep or a proc that
+    # returns the duration
     def sleep_duration(duration, count)
       case duration
       when Numeric
@@ -72,6 +79,26 @@ module Tins
       end
     end
 
+    # Computes the base for exponential backoff that results in a specific
+    # total sleep duration.
+    #
+    # This method solves for the base `x` in the geometric series:
+    #   x^0 + x^1 + x^2 + ... + x^(attempts-1) = sleep
+    #
+    # The solution ensures that when using exponential delays with base `x`,
+    # the total time spent across all attempts equals approximately the
+    # specified sleep duration. This method of computation is used if a
+    # negative number of secondes was requested in the attempt method.
+    #
+    # @param sleep [Numeric] The total number of seconds to distribute across
+    # all attempts
+    # @param attempts [Integer] The number of attempts (must be > 2)
+    #
+    # @return [Float] The base for exponential backoff delays
+    # @raise [ArgumentError] If attempts <= 2, or if the sleep parameters are
+    # invalid
+    # @raise [ArgumentError] If the algorithm fails to converge after maximum
+    # iterations
     def compute_duration_base(sleep, attempts)
       x1, x2  = 1, sleep
       attempts <= sleep or raise ArgumentError,
@@ -98,6 +125,18 @@ module Tins
       result
     end
 
+    # The interpret_sleep method determines the sleep behavior for retry attempts.
+    #
+    # @param sleep [Numeric, Proc, nil] the sleep duration or proc to use
+    # between retries, nil if no sleep was requested
+    # @param attempts [Integer] the number of retry attempts
+    #
+    # @return [Proc, nil] a proc that calculates the sleep duration or nil if
+    # no sleep is needed
+    #
+    # @raise [ArgumentError] if a negative sleep value is provided with less
+    # than 3 attempts
+    # @raise [TypeError] if the sleep argument is not Numeric, Proc, or nil
     def interpret_sleep(sleep, attempts)
       case sleep
       when nil

data/lib/tins/bijection.rb

@@ -1,5 +1,12 @@
 module Tins
+  # A hash subclass that ensures bijection between keys and values
   class Bijection < Hash
+    # Creates a new Bijection instance with key-value pairs.
+    #
+    # @param pairs [Array] an array of key-value pairs to populate the
+    # bijection
+    #
+    # @return [Bijection] a new bijection populated with the provided pairs
     def self.[](*pairs)
       pairs.size % 2 == 0 or
         raise ArgumentError, "odd number of arguments for #{self}"
@@ -15,10 +22,20 @@ module Tins
       end
     end
 
+    # The initialize method sets up a new instance with an inverted bijection.
+    #
+    # @param inverted [ Bijection ] the inverted bijection object, defaults to
+    # a new Bijection instance
     def initialize(inverted = Bijection.new(self))
       @inverted = inverted
     end
 
+    # The fill method populates the object with content from a block if it is
+    # empty.
+    #
+    # @return [ self ] returns the object itself after filling or if it was not
+    # empty
+    # @yield [ self ] yields self to the block for population
     def fill
       if empty?
         yield self
@@ -27,6 +44,9 @@ module Tins
       self
     end
 
+    # The freeze method freezes the current object and its inverted attribute.
+    #
+    # @return [Object] the frozen object
     def freeze
       r = super
       unless @inverted.frozen?
@@ -35,12 +55,26 @@ module Tins
       r
     end
 
+    # The []= method assigns a value to a key in the hash and maintains an
+    # inverted index.
+    #
+    # @param key [ Object ] the key to assign
+    # @param value [ Object ] the value to assign
+    #
+    # @return [ Object ] the assigned value
+    #
+    # @note This method will not overwrite existing keys, it will return early
+    # if the key already exists.
     def []=(key, value)
       key?(key) and return
       super
       @inverted[value] = key
     end
 
+    # The inverted attribute returns the inverted state of the object.
+    # Creates a new Bijection instance filled with key-value pairs.
+    #
+    # @return [Bijection] a new bijection instance with the specified key-value pairs
     attr_reader :inverted
   end
 end

data/lib/tins/case_predicate.rb

@@ -1,5 +1,26 @@
 module Tins
+  # A module that provides a predicate method for checking if a value matches
+  # any of the given cases.
   module CasePredicate
+    # Checks if the object matches any of the given arguments using the ===
+    # operator.
+    #
+    # This method provides pattern matching functionality similar to Ruby's
+    # case/when statements, using the === operator for semantic equality
+    # checking.
+    #
+    # @example Basic type matching
+    #   "hello".case?(String, Integer)     # => String (matches first argument)
+    #   42.case?(String, Integer)          # => Integer (matches first argument)
+    #   nil.case?(String, Integer)         # => nil (no matches)
+    #
+    # @example Range and pattern matching
+    #   15.case?(1..10, 11..20, 21..30)    # => 11..20 (matches range)
+    #   "hello world".case?(/foo/, /hello/) # => /hello/ (matches regex)
+    #
+    # @param args [Array] the arguments to check against using === operator
+    # @return [Object, nil] the first matching argument, or nil if no match is
+    # found
     def case?(*args)
       args.find { |a| a === self }
     end

data/lib/tins/complete.rb

@@ -1,11 +1,27 @@
 require 'readline'
 
 module Tins
+  # A module that provides completion functionality for objects.
   module Complete
     module_function
 
     @@sync = Sync.new
 
+    # The complete method reads a line of input from the user with optional
+    # prompt and history support.
+    #
+    # @param prompt [ String ] the prompt string to display to the user
+    # @param add_hist [ Boolean ] whether to add the input to the command
+    # history
+    #
+    # @yield [ String ] the completion procedure to use for tab completion
+    #
+    # @return [ String ] the line of input entered by the user
+    #
+    # @example Prompt with easy tab completion
+    #   complete(prompt: 'Pick a ruby file! ') {
+    #     Dir['**/*.rb'].grep(/#{it}/)
+    #   }.then { '%u lines' % File.new(it).each_line.count }
     def complete(prompt: '', add_hist: false, &block)
       @@sync.synchronize do
         Readline.completion_proc = block

data/lib/tins/concern.rb

@@ -1,9 +1,49 @@
 module Tins
+  # A module concern implementation that supports dependency tracking, class
+  # method inclusion, and block execution hooks.
+  #
+  # This module provides a way to define reusable module functionality with
+  # automatic dependency management, class method injection, and lifecycle
+  # callbacks similar to ActiveSupport::Concern but with more control.
+  #
+  # @example Basic usage
+  #   module MyConcern
+  #     extend Tins::Concern
+  #
+  #     included do
+  #       attr_accessor :logger
+  #     end
+  #
+  #     def log(message)
+  #       logger&.info message
+  #     end
+  #
+  #     class_methods do
+  #       def my_class_method
+  #         # ...
+  #       end
+  #     end
+  #   end
+  #
+  #   class MyClass
+  #     include MyConcern
+  #   end
   module Concern
+    # Extends the base object with dependency tracking capabilities.
+    #
+    # This method initializes an instance variable on the base object to store
+    # dependency information.
+    #
+    # @param base [ Object ] the object being extended
     def self.extended(base)
       base.instance_variable_set("@_dependencies", [])
     end
 
+    # The append_features method includes dependencies and class methods in the
+    # base class.
+    #
+    # @param base [ Object ] the base class to include features in
+    # @return [ Boolean ] true if features were appended, false otherwise
     def append_features(base)
       if base.instance_variable_defined?("@_dependencies")
         base.instance_variable_get("@_dependencies") << self
@@ -19,6 +59,14 @@ module Tins
       end
     end
 
+    # Prepends the features of this module to the base class.
+    #
+    # This method handles the inclusion of dependencies and class methods when
+    # a module is included in a class. It manages dependency tracking and
+    # ensures proper extension of the base class with ClassMethods.
+    #
+    # @param base [Class] the class that includes this module
+    # @return [Boolean] true if the module was successfully prepended, false otherwise
     def prepend_features(base)
       if base.instance_variable_defined?("@_dependencies")
         base.instance_variable_get("@_dependencies") << self
@@ -34,6 +82,11 @@ module Tins
       end
     end
 
+    # The included method is called when the module is included in a class or
+    # module.
+    #
+    # @param base [ Object ] the class or module that includes this module
+    # @param block [ Proc ] optional block to be executed when included
     def included(base = nil, &block)
       if base.nil?
         instance_variable_defined?(:@_included_block) and
@@ -44,6 +97,11 @@ module Tins
       end
     end
 
+    # The prepended method handles the setup of a block for prepend
+    # functionality or delegates to the superclass implementation
+    #
+    # @param base [ Object ] the base object to prepend to, or nil to set up a block
+    # @param block [ Proc ] the block to be used for prepend functionality
     def prepended(base = nil, &block)
       if base.nil?
         instance_variable_defined?(:@_prepended_block) and
@@ -54,6 +112,12 @@ module Tins
       end
     end
 
+    # Defines a ClassMethods module for the current class and evaluates the
+    # given block within it.
+    #
+    # @param block [Proc] The block to be evaluated in the context of the
+    # ClassMethods module
+    # @return [Module] The ClassMethods module that was defined or retrieved
     def class_methods(&block)
       modul = const_get(:ClassMethods) if const_defined?(:ClassMethods, false)
       unless modul

data/lib/tins/date_dummy.rb

@@ -1,13 +1,34 @@
 require 'date'
 
 module Tins
+  # A module that provides dummy date functionality for testing purposes.
+  #
+  # @example Setting a dummy date
+  #   Date.dummy = Date.parse('2009-09-09')
+  #
+  # @example Using a dummy date in a block
+  #   Date.dummy Date.parse('2009-09-09') do
+  #     # Your code here
+  #   end
   module DateDummy
+    # The included method is a hook that gets called when this module is
+    # included in another class or module.
+    #
+    # It sets up date freezing functionality by extending the including
+    # class/module with special date handling methods. The method modifies the
+    # including class/module's singleton class to provide dummy date
+    # capabilities.
+    #
+    # @param modul [Object] the class or module that includes this module
     def self.included(modul)
       class << modul
         alias really_today today
 
         remove_method :today rescue nil
 
+        # Sets the dummy date value for date freezing functionality.
+        #
+        # @param value [Date, String] the date value to set as dummy
         def dummy=(value)
           if value.respond_to?(:to_str)
             value = Date.parse(value.to_str)
@@ -17,6 +38,16 @@ module Tins
           @dummy = value
         end
 
+        # The dummy method provides a way to set and temporarily override a
+        # dummy value within a block.
+        #
+        # @param value [Object] the dummy value to set, or nil to get the
+        # current dummy value
+        # @yield [] yields control to the block if a value is provided
+        # @return [Object] the current dummy value if no value parameter was
+        # provided
+        # @yieldparam value [Object] the dummy value to set within the block
+        # @yieldreturn [Object] the result of the block execution
         def dummy(value = nil)
           if value.nil?
             if defined?(@dummy)
@@ -33,6 +64,11 @@ module Tins
           end
         end
 
+        # The today method returns the current date. When a dummy date is set,
+        # it returns a duplicate of that date. Otherwise, it delegates to the
+        # actual today method implementation.
+        #
+        # @return [Date] the current date or the dummy date if set
         def today
           if dummy
             dummy.dup
@@ -42,12 +78,8 @@ module Tins
             really_today
           end
         end
-
       end
       super
     end
   end
 end
-
-require 'tins/alias'
-

data/lib/tins/date_time_dummy.rb

@@ -1,13 +1,30 @@
 require 'date'
 
 module Tins
+  # A module that provides dummy functionality for DateTime class
+  #
+  # This module allows setting a fixed date and time that will be returned by
+  # DateTime.now instead of the actual current time. This is useful for testing
+  # purposes where consistent timestamps are required.
   module DateTimeDummy
+    # The included method is a hook that gets called when this module is
+    # included in another class or module.
+    #
+    # It sets up date time freezing functionality by extending the including
+    # class/module with special date time handling methods. The method modifies
+    # the including class/module's singleton class to provide dummy date time
+    # capabilities.
+    #
+    # @param modul [Object] the class or module that includes this module
     def self.included(modul)
       class << modul
         alias really_now now
 
         remove_method :now rescue nil
 
+        # Sets the dummy value for datetime handling.
+        #
+        # @param value [DateTime, String] the datetime value to set as dummy
         def dummy=(value)
           if value.respond_to?(:to_str)
             value = DateTime.parse(value.to_str)
@@ -17,6 +34,18 @@ module Tins
           @dummy = value
         end
 
+        # The dummy method provides a way to set and restore a dummy value
+        # within a block.
+        #
+        # @param value [Object] the dummy value to set, or nil to get the
+        # current dummy value
+        #
+        # @yield [void] yields control to the block if a value is provided
+        #
+        # @return [Object] the current dummy value if no value parameter is
+        # provided
+        # @return [Object] the result of the block if a value parameter is
+        # provided
         def dummy(value = nil)
           if value.nil?
             if defined?(@dummy)
@@ -33,6 +62,11 @@ module Tins
           end
         end
 
+        # The now method returns the current time, using a dummy time if one
+        # has been set. If no dummy time is set, it delegates to the actual
+        # time retrieval method.
+        #
+        # @return [Time] the current time or a mocked time if dummy is set
         def now
           if dummy
             dummy.dup
@@ -47,5 +81,3 @@ module Tins
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/deep_dup.rb

@@ -1,5 +1,14 @@
 module Tins
+  # DeepDup module provides a method to deeply duplicate objects in Ruby.
+  #
+  # This module extends the Object class with a deep_dup method that creates a
+  # recursive copy of an object and all its nested objects.
   module DeepDup
+    # Duplicates an object deeply by marshaling and unmarshaling it. For
+    # objects that can't be marshaled, it returns the object itself.
+    #
+    # @return [Object] a deep duplicate of the object or the object itself if
+    # it can't be marshaled
     def deep_dup
       Marshal.load(Marshal.dump(self))
     rescue TypeError
@@ -7,5 +16,3 @@ module Tins
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/deprecate.rb

@@ -1,5 +1,17 @@
 module Tins
+  # A module for deprecating methods with customizable messages and warnings.
+  #
+  # @example
+  #   class MyClass
+  #     extend Tins::Deprecate
+  #     deprecate method: :old_method, new_method: :new_method
+  #   end
   module Deprecate
+    # Deprecates a method and issues a warning when called.
+    #
+    # @param method [ Symbol ] the name of the method to deprecate
+    # @param new_method [ Symbol ] the name of the replacement method
+    # @param message [ String ] the warning message to display
     def deprecate(method:, new_method: nil, message: nil)
       message ||= '[DEPRECATION] `%{method}` is deprecated. Please use `%{new_method}` instead.'
       message = message % { method: method, new_method: new_method }