tins 1.32.0 → 1.44.0

data/lib/tins/xt/blank.rb

@@ -1,34 +1,83 @@
 module Tins
+  # The Tins::Blank module provides a consistent way to check if objects are
+  # "blank" (empty, nil, or contain only whitespace). This follows Rails'
+  # convention.
+  #
+  # @example Basic usage
+  #   "".blank?        # => true
+  #   "   ".blank?     # => true
+  #   "foo".blank?     # => false
+  #   [].blank?        # => true
+  #   [1, 2].blank?    # => false
+  #   nil.blank?       # => true
+  #   false.blank?     # => true
+  #   true.blank?      # => false
+  #
+  # @example Using present?
+  #   "".present?      # => false
+  #   "foo".present?   # => true
   module Blank
+    # Blank behavior for Object instances
     module Object
+      # Provides a fallback implementation that checks for `empty?` method,
+      # falling back to negation of truthiness if not defined.
+      #
+      # @return [Boolean] true if the object is considered blank, false otherwise
       def blank?
         respond_to?(:empty?) ? empty? : !self
       end
 
+      # Checks if the object is not blank
+      #
+      # @return [Boolean] true if the object is present, false otherwise
       def present?
         !blank?
       end
     end
 
+    # Blank behavior for NilClass instances
     module NilClass
+      #
+      # Nil values are always considered blank.
+      #
+      # @return [Boolean] true (always)
       def blank?
         true
       end
     end
 
+    # Blank behavior for FalseClass instances
     module FalseClass
+      # False values are always considered blank.
+      #
+      # @return [Boolean] true (always)
       def blank?
         true
       end
     end
 
+    # Blank behavior for TrueClass instances
     module TrueClass
+      # True values are never considered blank.
+      #
+      # @return [Boolean] false (always)
       def blank?
         false
       end
     end
 
+    # Blank behavior for Array instances
+    #
+    # Arrays are blank if they are empty.
+    # This implementation aliases the `empty?` method to `blank?`.
     module Array
+      # The included method is a hook that gets called when this module is
+      # included in another class or module.
+      #
+      # It sets up blank? behavior by aliasing the empty? method to blank? in
+      # the including class/module.
+      #
+      # @param modul [Object] the class or module that includes this module
       def self.included(modul)
         modul.module_eval do
           alias_method :blank?, :empty?
@@ -36,7 +85,18 @@ module Tins
       end
     end
 
+    # Blank behavior for Hash instances
+    #
+    # Hashes are blank if they are empty.
+    # This implementation aliases the `empty?` method to `blank?`.
     module Hash
+      # The included method is a hook that gets called when this module is
+      # included in another class or module.
+      #
+      # It sets up blank? behavior by aliasing the empty? method to blank? in
+      # the including class/module.
+      #
+      # @param modul [Object] the class or module that includes this module
       def self.included(modul)
         modul.module_eval do
           alias_method :blank?, :empty?
@@ -44,20 +104,39 @@ module Tins
       end
     end
 
+    # Blank behavior for String instances
     module String
+      # Strings are blank if they contain only whitespace characters.
+      # This uses a regex match against non-whitespace characters.
+      #
+      # @return [Boolean] true if the string contains only whitespace, false otherwise
       def blank?
         self !~ /\S/
       end
     end
 
+    # Blank behavior for Numeric instances
+    #
+    # Numbers are considered blank only if they are zero.
+    # This implementation aliases the `zero?` method to `blank?`.
     module Numeric
-      def blank?
-        false
+      # The included method is a hook that gets called when this module is
+      # included in another class or module.
+      #
+      # It sets up blank? behavior by aliasing the zero? method to blank? in
+      # the including class/module.
+      #
+      # @param modul [Object] the class or module that includes this module
+      def self.included(modul)
+        modul.module_eval do
+          alias_method :blank?, :zero?
+        end
       end
     end
   end
 end
 
+# Extend constant classes with Blank behavior unless blank? is already defined
 unless Object.respond_to?(:blank?)
   for k in Tins::Blank.constants
     Object.const_get(k).class_eval do

data/lib/tins/xt/concern.rb

@@ -1,19 +1,70 @@
 require 'tins/concern'
 
 module Tins
+  # Concern provides a mechanism for module configuration that persists across
+  # inheritance and inclusion boundaries using thread-local storage.
+  #
+  # This module implements a pattern where modules can be configured with
+  # arguments that are then available throughout the module's lifecycle in
+  # a thread-safe manner. It's particularly useful for implementing
+  # configuration-based concerns that need to maintain state across
+  # different scopes.
+  #
+  # @example Configured concern usage
+  #   module MyConcern
+  #     extend Tins::Concern
+  #   end
+  #
+  #   # Configure the concern with parameters
+  #   include MyConcern.tins_concern_configure(:option1, :option2)
   module Concern
+    # ModuleMixin provides thread-local storage for concern configuration.
+    #
+    # This mixin adds methods to any module that includes it, allowing for
+    # configuration of concerns through thread-local storage. The configuration
+    # is stored in the current thread's context and persists during the
+    # execution of code that uses this concern.
+    #
+    # @note This implementation relies on Thread.current which makes it
+    # thread-safe but scoped to individual threads.
     module ModuleMixin
+      # Configures the module with the given arguments and returns self.
+      #
+      # This method stores the provided arguments in thread-local storage,
+      # making them available via {tins_concern_args}. It's designed to be
+      # chainable (returns self).
+      #
+      # @param args [Array] Arguments to configure this concern with
+      # @return [Module] The module itself, for chaining
+      # @example
+      #   MyConcern.tins_concern_configure(:option1, :option2)
       def tins_concern_configure(*args)
         Thread.current[:tin_concern_args] = args
         self
       end
 
+      # Retrieves the current concern configuration arguments.
+      #
+      # This method fetches the arguments that were previously set using
+      # {tins_concern_configure}. If no configuration has been set, it returns
+      # nil.
+      #
+      # @return [Array, nil] The stored configuration arguments or nil
+      # @example
+      #   MyConcern.tins_concern_configure(:option1, :option2)
+      #   puts MyConcern.tins_concern_args  # => [:option1, :option2]
       def tins_concern_args
         Thread.current[:tin_concern_args]
       end
     end
   end
 
+  # Extends the core Module class with the concern functionality.
+  #
+  # This line makes the concern configuration methods available to all modules
+  # in the system, allowing any module to be configured as a concern.
+  #
+  # @see Tins::Concern::ModuleMixin
   class ::Module
     include Tins::Concern::ModuleMixin
   end

data/lib/tins/xt/deep_dup.rb

@@ -1,7 +1,9 @@
 require 'tins/deep_dup'
 
 module Tins
-  class ::Object
-    include Tins::DeepDup
+  unless Object.respond_to?(:deep_dup)
+    class ::Object
+      include Tins::DeepDup
+    end
   end
 end

data/lib/tins/xt/deprecate.rb

@@ -0,0 +1,5 @@
+require 'tins/deprecate'
+
+class Module
+  include Tins::Deprecate
+end

data/lib/tins/xt/full.rb

@@ -1,18 +1,51 @@
 require 'tins/xt/blank'
 
 module Tins
+  # Provides methods for checking if objects are "full" (non-blank) and safely
+  # processing them in conditional contexts.
+  #
+  # This module adds the `full?` and `all_full?` methods to all objects, enabling
+  # clean, readable patterns for validation and conditional processing.
+  #
+  # @example Basic usage
+  #   "hello".full?        # => "hello"
+  #   "".full?             # => nil
+  #
+  # @example Method dispatch with block
+  #   user.full?(:name) { |name| "Hello #{name}" }  # Returns "Hello John" if name is full
+  #
+  # @example Safe assignment and processing
+  #   if name = user.full?(:name)
+  #     puts "Hello #{name}"
+  #   end
   module Full
-    # Returns the object if it isn't blank (as in Object#blank?), otherwise it
-    # returns nil. If a block was given as an argument and the object isn't
-    # blank, the block is executed with the object as its first argument. If an
-    # argument +dispatch+ was given and the object wasn't blank the method
-    # given by dispatch is called on the object. This is the same as
-    # foo.full?(&:bar) in the previous block form.
+    # Checks if the object is not blank, returning the object itself if it's
+    # full, or nil if it's blank. If a method name is provided as +dispatch+,
+    # that method is called on the object and the result is checked for being
+    # full.
+    #
+    # @param dispatch [Symbol, nil] The method to call on the object (optional)
+    # @param args [Array] Arguments to pass to the dispatched method (optional)
+    # @yield [Object] Optional block to execute with the result if result or
+    # dispatched result not nil
+    # @return [Object, nil] The object itself if not blank, or the result of
+    #   dispatching +dispatch+ if provided and valid, or nil if the object is blank
+    #
+    # @example Basic usage
+    #   "hello".full?        # => "hello"
+    #   "".full?             # => nil
+    #
+    # @example Method dispatch
+    #   user.full?(:name)    # Returns user.name if not blank, nil otherwise
+    #
+    # @example Method dispatch with arguments
+    #   user.full?(:method_with_args, arg1, arg2)
+    #
+    # @example With block execution
+    #   user.full?(:name) { |name| "Hello #{name}" }
     def full?(dispatch = nil, *args)
       if blank?
         obj = nil
-      #elsif Module === dispatch # TODO
-      #  dispatch.found?(self)
       elsif dispatch
         obj = __send__(dispatch, *args)
         obj = nil if obj.blank?
@@ -26,14 +59,26 @@ module Tins
       end
     end
 
+    # Checks if all elements in a collection are "full" (not blank). If the
+    # object responds to +all?+ and all elements pass the +full?+ test, then
+    # the block is executed with the collection itself or the collection is returned.
+    #
+    # @return [Object, nil] The collection if all elements are full, otherwise nil
+    #
+    # @example Basic usage
+    #   [1,2,3].all_full?    # => [1,2,3]
+    #   [1,nil,3].all_full?  # => nil
+    #
+    # @example With block execution
+    #   [1,2,3].all_full? { |array| array.sum }
     def all_full?
       if respond_to?(:all?) && all?(&:full?)
         block_given? ? yield(self) : self
       end
     end
-  end
 
-  class ::Object
-    include Full
+    class ::Object
+      include Full
+    end
   end
 end

data/lib/tins/xt/hash_bfs.rb

@@ -0,0 +1,7 @@
+require 'tins/hash_bfs'
+
+module Tins
+  class ::Hash
+    include HashBFS
+  end
+end

data/lib/tins/xt/irb.rb

@@ -1,9 +1,42 @@
 require 'irb'
 
+# Provides interactive debugging capabilities through the IRB console.
+#
+# This module adds an `examine` method to all objects, allowing developers to
+# quickly drop into an interactive IRB session with the current binding or
+# examine specific objects. It's particularly useful for debugging and exploring
+# data structures during development.
+#
+# @example Basic usage
+#   # Drop into IRB with current context
+#   examine
+#
+# @example Examine a specific object
+#   data = [1, 2, 3]
+#   examine data  # Inspects just the 'data' variable
+#
+# @example Use from within methods
+#   def process_data
+#     result = expensive_operation
+#     examine result  # Debug the result immediately
+#   end
 module Tins
+  # We have our own IRB as well.
   IRB = ::IRB
 
+  # We extend the top level IRB module
   module ::IRB
+    # Starts an interactive IRB session with the given binding context. This
+    # method creates a new IRB instance and evaluates input from it, allowing for
+    # interactive exploration of variables and objects.
+    #
+    # @param binding [Binding, nil] The binding context to examine (defaults to TOPLEVEL_BINDING)
+    #
+    # @example Start IRB with current context
+    #   examine
+    #
+    # @example Examine specific binding
+    #   examine some_binding
     def self.examine(binding = TOPLEVEL_BINDING)
       setup nil
       workspace = WorkSpace.new binding
@@ -13,9 +46,20 @@ module Tins
     rescue Interrupt
       exit
     end
-  end
 
-  class ::Object
+    # Starts an interactive IRB session examining the current object and its context.
+    # This instance method provides a convenient way to debug objects without
+    # explicitly passing bindings.
+    #
+    # @param binding [Binding, nil] The binding context to examine (defaults to TOPLEVEL_BINDING)
+    # @return [void]
+    #
+    # @example Examine the current object
+    #   my_object.examine
+    #
+    # @example Examine a specific variable
+    #   data = [1, 2, 3]
+    #   data.examine  # Inspects just the 'data' variable
     def examine(binding = TOPLEVEL_BINDING)
       IRB.examine(binding)
     end

data/lib/tins/xt/method_description.rb

@@ -3,21 +3,9 @@ require 'tins/method_description'
 module Tins
   class ::UnboundMethod
     include MethodDescription
-
-    alias to_s description
-
-    def inspect
-      "#<#{self.class}: #{description}>"
-    end
   end
 
   class ::Method
     include MethodDescription
-
-    alias to_s description
-
-    def inspect
-      "#<#{self.class}: #{description}>"
-    end
   end
 end

data/lib/tins/xt/minimize.rb

@@ -0,0 +1,7 @@
+require 'tins/minimize'
+
+module Tins
+  class ::Array
+    include Tins::Minimize
+  end
+end

data/lib/tins/xt/named.rb

@@ -1,23 +1,78 @@
-require 'tins/xt/string_version'
+module Tins
+  # A dynamically created module class used internally by the
+  # {Tins::Object#named} and {Tins::Module#named} methods to create dynamic
+  # methods.
+  #
+  # This class inherits from Module and serves as a template for creating
+  # dynamically scoped methods that can be extended or included into objects
+  # or classes.
+  Named = ::Class.new(::Module)
 
-class Object
-  def named(name, method, *args, &named_block)
-    extend Module.new {
-      define_method(name) do |*rest, &block|
-        block = named_block if named_block
-        __send__(method, *(args + rest), &block)
+  class ::Object
+    # Adds a dynamically created method to the object instance. The method will
+    # call the specified +method+ with optional +args+ and combine any provided
+    # +named_block+ with runtime blocks.
+    #
+    # @param name [Symbol] The name of the method to create
+    # @param method [Symbol] The existing method to delegate to
+    # @param args [Array] Optional arguments to pre-bind to the delegated method
+    # @yield [Object] Optional block to be used as the method's block
+    # @return [Object] self
+    # @example Create a method that maps elements
+    #   a = [1, 2, 3]
+    #   a.named(:double, :map) { |x| x * 2 }
+    #   a.double  # => [2, 4, 6]
+    #
+    # @example Pre-bind arguments to a method
+    #   def process(data, multiplier, &block)
+    #     data.map { |x| block.call(x * multiplier) }
+    #   end
+    #
+    #   Object.named(:process_by_10, :process, 10) do |result|
+    #     result + 1
+    #   end
+    #   process_by_10([1, 2, 3]) { |x| x * 2 }  # => [21, 41, 61]
+    def named(name, method, *args, &named_block)
+      name = name.to_sym
+      m = Tins::Named.new {
+        define_method(name) do |*rest, &block|
+          block = named_block if named_block
+          __send__(method, *(args + rest), &block)
+        end
+      }
+      if m.respond_to?(:set_temporary_name)
+        m.set_temporary_name "#{m.class} for method #{name.inspect}"
       end
-    }
+      extend m
+    end
   end
-end
 
-class Module
-  def named(name, method, *args, &named_block)
-    include Module.new {
-      define_method(name) do |*rest, &block|
-        block = named_block if named_block
-        __send__(method, *(args + rest), &block)
+  class ::Module
+    # Adds a dynamically created method to all instances of the class. The
+    # method will call the specified +method+ with optional +args+ and combine
+    # any provided +named_block+ with runtime blocks.
+    #
+    # @param name [Symbol] The name of the method to create
+    # @param method [Symbol] The existing method to delegate to
+    # @param args [Array] Optional arguments to pre-bind to the delegated method
+    # @yield [Object] Optional block to be used as the method's block
+    # @return [Module] self
+    #
+    # @example Create a class-level method
+    #   Array.named(:sum_all, :reduce) { |acc, x| acc + x }
+    #   [1, 2, 3].sum_all  # => 6
+    def named(name, method, *args, &named_block)
+      name = name.to_sym
+      m = Tins::Named.new {
+        define_method(name) do |*rest, &block|
+          block = named_block if named_block
+          __send__(method, *(args + rest), &block)
+        end
+      }
+      if m.respond_to?(:set_temporary_name)
+        m.set_temporary_name "#{m.class} for method #{name.inspect}"
       end
-    }
+      include m
+    end
   end
 end

data/lib/tins/xt/proc_compose.rb

@@ -4,4 +4,8 @@ module Tins
   class ::Proc
     include Tins::ProcCompose
   end
+
+  class ::Method
+    include Tins::ProcCompose
+  end
 end

data/lib/tins/xt/secure_write.rb

@@ -1,10 +1,6 @@
 require 'tins/secure_write'
 
 module Tins
-  #class ::Object
-  #  include Tins::SecureWrite
-  #end
-
   class ::IO
     extend Tins::SecureWrite
   end

data/lib/tins/xt/string.rb

@@ -3,4 +3,5 @@ module Tins
   require 'tins/xt/string_underscore'
   require 'tins/xt/string_version'
   require 'tins/xt/string_byte_order_mark'
+  require 'tins/xt/string_named_placeholders'
 end

data/lib/tins/xt/string_camelize.rb

@@ -1,6 +1,8 @@
 module Tins
   require 'tins/string_camelize'
-  class ::String
-    include StringCamelize
+  unless String.respond_to?(:camelize)
+    class ::String
+      include StringCamelize
+    end
   end
 end

data/lib/tins/xt/string_named_placeholders.rb

@@ -0,0 +1,7 @@
+module Tins
+  require 'tins/string_named_placeholders'
+
+  class ::String
+    include StringNamedPlaceholders
+  end
+end

data/lib/tins/xt/string_underscore.rb

@@ -1,6 +1,8 @@
 module Tins
   require 'tins/string_underscore'
-  class ::String
-    include StringUnderscore
+  unless String.respond_to?(:underscore)
+    class ::String
+      include StringUnderscore
+    end
   end
 end

data/lib/tins/xt/subhash.rb

@@ -4,6 +4,17 @@ module Tins
   class ::Hash
     include Tins::Subhash
 
+    # The subhash! method creates a filtered subset of this hash based on the
+    # given patterns and replaces the current hash with the result.
+    #
+    # This method works by first calling subhash with the provided patterns to
+    # create a new hash containing only the matching key-value pairs, then
+    # replacing the contents of the current hash with those pairs.
+    #
+    # @param patterns [Array<Object>] One or more patterns to match against
+    # keys
+    # @return [Hash] Returns self after replacing its contents with the
+    # filtered subset
     def subhash!(*patterns)
       replace subhash(*patterns)
     end

data/lib/tins/xt/time_freezer.rb

@@ -2,12 +2,49 @@ require 'tins/xt/time_dummy'
 require 'tins/xt/date_time_dummy'
 require 'tins/xt/date_dummy'
 
-module Tins::TimeFreezer
-  def self.freeze(time)
-    Time.dummy(time) do
-      DateTime.dummy(time) do
-        Date.dummy(time) do
-          yield
+module Tins
+  # TimeFreezer provides a mechanism to temporarily freeze time across multiple
+  # time-related classes.
+  #
+  # This module allows you to temporarily replace the behavior of Time, DateTime,
+  # and Date classes with dummy implementations that always return a specific
+  # time value. This is particularly useful for testing code that depends on
+  # current time values.
+  #
+  # @example Basic usage
+  #   Tins::TimeFreezer.freeze(Time.new(2023, 1, 1)) do
+  #     # All Time, DateTime, and Date calls will return the frozen time
+  #     puts Time.now  # => 2023-01-01 00:00:00 +0000
+  #   end
+  #
+  # @example With DateTime and Date
+  #   Tins::TimeFreezer.freeze(Time.new(2023, 1, 1)) do
+  #     puts DateTime.now  # => 2023-01-01T00:00:00+00:00
+  #     puts Date.today    # => 2023-01-01
+  #   end
+  #
+  # @example Using time string (will be parsed by Time.parse)
+  #   Tins::TimeFreezer.freeze("2023-01-01 12:00:00") do
+  #     # Time.now will return the parsed time
+  #     puts Time.now  # => 2023-01-01 12:00:00 +0000
+  #   end
+  module TimeFreezer
+    # Freezes time for the duration of the given block.
+    #
+    # This method temporarily replaces the behavior of Time, DateTime, and Date
+    # classes with dummy implementations that always return the specified time
+    # value.
+    #
+    # @param time [Time, DateTime, Date] The time value to freeze all
+    # time-related classes to
+    # @yield [] The block of code to execute with frozen time
+    # @return [Object] The return value of the yielded block
+    def self.freeze(time)
+      Time.dummy(time) do
+        DateTime.dummy(time) do
+          Date.dummy(time) do
+            yield
+          end
         end
       end
     end

data/lib/tins/xt/write.rb

@@ -1,10 +1,6 @@
 require 'tins/write'
 
 module Tins
-  #class ::Object
-  #  include Tins::Write
-  #end
-
   class ::IO
     extend Tins::Write
   end