tins 1.43.0 → 1.44.0

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/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/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/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.rb

@@ -3,7 +3,6 @@ require 'tins'
 module Tins
   require 'tins/xt/attempt'
   require 'tins/xt/blank'
-  require 'tins/xt/count_by'
   require 'tins/xt/deep_dup'
   require 'tins/xt/file_binary'
   require 'tins/xt/full'
@@ -22,12 +21,10 @@ module Tins
   require 'tins/xt/time_dummy'
   require 'tins/xt/date_dummy'
   require 'tins/xt/date_time_dummy'
-  require 'tins/xt/uniq_by'
   require 'tins/xt/write'
   require 'tins/xt/if_predicate'
   require 'tins/xt/ask_and_send'
   require 'tins/xt/extract_last_argument_options'
-  require 'tins/xt/deep_const_get'
   require 'tins/xt/responding'
   require 'tins/xt/proc_compose'
   require 'tins/xt/proc_prelude'
@@ -44,4 +41,5 @@ module Tins
   require 'tins/xt/temp_io'
   require 'tins/xt/deprecate'
   require 'tins/xt/hash_bfs'
+  require 'tins/xt/minimize'
 end

data/lib/tins.rb

@@ -1,7 +1,22 @@
+# Tins is a collection of useful Ruby utilities and tools that provide
+# common functionality without requiring external dependencies. It's designed
+# to be a lightweight, drop-in library that enhances Ruby's standard library
+# with practical conveniences.
+#
+# @example Basic usage
+#   require 'tins'
+#
+#   Tins::Once.only_once { puts "Only one instance" }
+#
+# @example Automatic class extensions
+#   require 'tins/xt'
+#
+#   # Automatically extends core classes with useful methods
+#   "foo".full? # => "foo"
+#   "   ".full? # => nil
 module Tins
   require 'tins/attempt'
   require 'tins/bijection'
-  require 'tins/count_by'
   require 'tins/deep_dup'
   require 'tins/file_binary'
   require 'tins/find'
@@ -31,11 +46,9 @@ module Tins
   require 'tins/date_dummy'
   require 'tins/date_time_dummy'
   require 'tins/to_proc'
-  require 'tins/uniq_by'
   require 'tins/version'
   require 'tins/write'
   require 'tins/extract_last_argument_options'
-  require 'tins/deep_const_get'
   require 'tins/responding'
   require 'tins/proc_compose'
   require 'tins/proc_prelude'

data/tests/duration_test.rb

@@ -22,6 +22,10 @@ module Tins
       assert_equal '0+00:11:06.123456', Tins::Duration.new(666.123456).format
     end
 
+    def test_format_percentage
+      assert_equal '11%06', Tins::Duration.new(666.123456).format('%m%%%s')
+    end
+
     def test_smart_format
       assert_equal '00:11:06.123', Tins::Duration.new(666.123456).format('%D')
       assert_equal '7+17:11:06.123', Tins::Duration.new(666666.123456).format('%D')

data/tests/from_module_test.rb

@@ -11,6 +11,16 @@ class FromModuleTest < Test::Unit::TestCase
     end
   end
 
+  module MyIncludedModule2
+    def foo
+      :foo2
+    end
+
+    def bar
+      :bar2
+    end
+  end
+
   class MyKlass
     def foo
       :original_foo
@@ -35,14 +45,17 @@ class FromModuleTest < Test::Unit::TestCase
     def bar
       :original_bar
     end
+
+    def baz
+      :original_baz
+    end
     include MyIncludedModule
   end
 
   class AnotherDerivedKlass
-    include MyModule
-
     extend Tins::FromModule
 
+    include MyModule
     include from module: MyIncludedModule, methods: :foo
   end
 
@@ -57,4 +70,19 @@ class FromModuleTest < Test::Unit::TestCase
     assert_equal :foo, c.foo
     assert_equal :original_bar, c.bar
   end
+
+  class MixedClass
+    extend Tins::FromModule
+
+    include MyModule
+    include from module: MyIncludedModule, methods: :foo
+    include from module: MyIncludedModule2, methods: :bar
+  end
+
+  def test_mixed_klass
+    c = MixedClass.new
+    assert_equal :foo, c.foo
+    assert_equal :bar2, c.bar
+    assert_equal :original_baz, c.baz
+  end
 end

data/tests/implement_test.rb

@@ -53,14 +53,12 @@ module Tins
       assert_equal('blab', error_message { A.new.quux })
     end
 
-    if RUBY_VERSION >= "2.1"
-      def test_implement_def_subclass
-        assert_equal(
-          'method foobar(arg1,arg2:?) has to be '\
-          'implemented in subclasses of Tins::ImplementTest::A',
-          error_message { A.new.foobar }
-        )
-      end
+    def test_implement_def_subclass
+      assert_equal(
+        'method foobar(arg1,arg2:…) has to be '\
+        'implemented in subclasses of Tins::ImplementTest::A',
+        error_message { A.new.foobar }
+      )
     end
 
     private

data/tests/lines_file_test.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: false
+
 require 'test_helper'
 require 'tempfile'
 

data/tests/lru_cache_test.rb

@@ -6,6 +6,18 @@ module Tins
       @cache = LRUCache.new(3)
     end
 
+    def test_too_low_capacity
+      assert_raise ArgumentError do
+        LRUCache.new(0)
+      end
+    end
+
+    def test_wrong_capacity_type
+      assert_raise TypeError do
+        LRUCache.new(:foo)
+      end
+    end
+
     def test_can_be_filled_to_capacity
       assert_equal 0, @cache.size
       @cache[1] = 1

data/tests/method_description_test.rb

@@ -12,10 +12,8 @@ module Tins
     end
 
     def test_static_nonstatic
-      assert_equal 'Tins::MethodDescriptionTest::A#foo()', A.instance_method(:foo).to_s
-      assert_equal '#<UnboundMethod: Tins::MethodDescriptionTest::A#foo()>', A.instance_method(:foo).inspect
-      assert_equal 'Tins::MethodDescriptionTest::A.foo()', A.method(:foo).to_s
-      assert_equal '#<Method: Tins::MethodDescriptionTest::A.foo()>', A.method(:foo).inspect
+      assert_equal 'Tins::MethodDescriptionTest::A#foo()', A.instance_method(:foo).description
+      assert_equal 'Tins::MethodDescriptionTest::A.foo()', A.method(:foo).description
     end
 
     class B
@@ -33,12 +31,12 @@ module Tins
     end
 
     def test_standard_parameters_namespace
-      assert_equal 'Tins::MethodDescriptionTest::B#foo(x,y=?,*r,&b)',
-        B.instance_method(:foo).to_s
+      assert_equal 'Tins::MethodDescriptionTest::B#foo(x,y=…,*r,&b)',
+        B.instance_method(:foo).description
     end
 
     def test_standard_parameters_name
-      assert_equal 'foo(x,y=?,*r,&b)',
+      assert_equal 'foo(x,y=…,*r,&b)',
         B.instance_method(:foo).description(style: :name)
     end
 
@@ -84,21 +82,17 @@ module Tins
     end
 
     def test_keyword_parameters
-      assert_equal 'Tins::MethodDescriptionTest::C#foo(x,k:?,&b)', C.instance_method(:foo).to_s
-      assert_equal 'Tins::MethodDescriptionTest::C#bar(x,**k,&b)', C.instance_method(:bar).to_s
+      assert_equal 'Tins::MethodDescriptionTest::C#foo(x,k:…,&b)', C.instance_method(:foo).description
+      assert_equal 'Tins::MethodDescriptionTest::C#bar(x,**k,&b)', C.instance_method(:bar).description
     end
 
-    if RUBY_VERSION >= "2.1"
-      eval %{
-        class D
-          def foo(x, k:, &b)
-          end
-        end
-
-        def test_keyword_parameters_required
-          assert_equal 'Tins::MethodDescriptionTest::D#foo(x,k:,&b)', D.instance_method(:foo).to_s
-        end
-      }
+    class D
+      def foo(x, k:, &b)
+      end
+    end
+
+    def test_keyword_parameters_required
+      assert_equal 'Tins::MethodDescriptionTest::D#foo(x,k:,&b)', D.instance_method(:foo).description
     end
   end
 end