tins 1.43.0 → 1.44.0

data/lib/tins/partial_application.rb

@@ -1,19 +1,80 @@
 module Tins
+  # A module that provides partial application functionality.
+  #
+  # This module is designed to be included in classes that respond to `call` and have
+  # an `arity` method. It's commonly used with Proc and Method objects, but can be
+  # included in any class that implements the required interface.
+  #
+  # Partial application allows you to create new callables by fixing some arguments
+  # of an existing callable, resulting in a callable with fewer parameters.
+  #
+  # @example Using partial application with Proc
+  #   add = proc { |x, y| x + y }
+  #   add_five = add.partial(5)           # Fixes first argument to 5
+  #   result = add_five.call(3)           # Returns 8 (5 + 3)
+  #
+  # @example Using partial application with Method
+  #   class Calculator
+  #     def calculate(x, y, z)
+  #       x + y * z
+  #     end
+  #   end
+  #
+  #   calc = Calculator.new
+  #   method_obj = calc.method(:calculate)
+  #   partial_calc = method_obj.partial(1, 2)  # Fixes first two arguments
+  #   result = partial_calc.call(3)            # Returns 7 (1 + 2 * 3)
   module PartialApplication
-    # If this module is included into a Proc (or similar object), it tampers
-    # with its Proc#arity method.
+    # Callback invoked when this module is included in a class. Overrides the
+    # `arity` method to support custom arity values for partial applications.
+    #
+    # This is particularly useful for Proc and Method objects where the arity
+    # needs to be adjusted after partial application.
+    #
+    # @param modul [Module] The module that included this module
     def self.included(modul)
       modul.module_eval do
         old_arity = instance_method(:arity)
         define_method(:arity) do
-          defined?(@__arity__) or old_arity.bind(self).call
+          if defined?(@__arity__)
+            @__arity__
+          else
+            old_arity.bind(self).call
+          end
         end
       end
       super
     end
 
-    # Create a partial application of this Proc (or similar object) using
-    # _args_ as the already applied arguments.
+    # Creates a partial application of the current object.
+    #
+    # If no arguments are provided, returns a duplicate of the current object.
+    # If more arguments are provided than the object's arity, raises an
+    # ArgumentError. Otherwise, creates a new lambda that combines the provided
+    # arguments with additional arguments when called.
+    #
+    # This method is particularly useful for creating curried functions or
+    # partially applied methods where some parameters are pre-filled.
+    #
+    # @param args [Array] Arguments to partially apply to the callable
+    # @return [Proc] A partial application of this object with adjusted arity
+    # @raise [ArgumentError] If too many arguments are provided for the arity
+    # @example
+    #   add = proc { |x, y| x + y }
+    #   add_five = add.partial(5)
+    #   add_five.call(3)  # => 8
+    #
+    # @example With Method objects
+    #   class MathOps
+    #     def multiply(a, b, c)
+    #       a * b * c
+    #     end
+    #   end
+    #
+    #   ops = MathOps.new
+    #   method_obj = ops.method(:multiply)
+    #   partial_mult = method_obj.partial(2, 3)
+    #   partial_mult.call(4)  # => 24 (2 * 3 * 4)
     def partial(*args)
       if args.empty?
         dup
@@ -27,5 +88,3 @@ module Tins
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/proc_compose.rb

@@ -1,15 +1,72 @@
 module Tins
+  # A module that provides function composition functionality for Proc objects.
+  #
+  # This module enables the composition of two functions (procs) such that the
+  # result is a new proc that applies the second function to the input, then
+  # applies the first function to the result. This follows the mathematical
+  # concept of function composition: (f ∘ g)(x) = f(g(x))
+  #
+  # @example Basic composition
+  #   add_one = proc { |x| x + 1 }
+  #   multiply_by_two = proc { |x| x * 2 }
+  #
+  #   composed = multiply_by_two.compose(add_one)
+  #   composed.call(5)  # => 12 (2 * (5 + 1))
+  #
+  # @example Using the alias operator
+  #   add_one = proc { |x| x + 1 }
+  #   multiply_by_two = proc { |x| x * 2 }
+  #
+  #   composed = multiply_by_two * add_one
+  #   composed.call(5)  # => 12
   module ProcCompose
+    # Composes this proc with another callable, creating a new proc that
+    # applies the other callable first, then applies this proc to its result.
+    #
+    # The composition follows the mathematical convention:
+    #
+    # (self ∘ other)(args) = self(other(args))
+    #
+    # @param other [Proc, Method, Object] A callable object that responds to `call`
+    #   or can be converted to a proc via `to_proc`
+    # @return [Proc] A new proc representing the composition
+    # @example
+    #   square = proc { |x| x * x }
+    #   add_one = proc { |x| x + 1 }
+    #
+    #   composed = square.compose(add_one)
+    #   composed.call(3)  # => 16 ((3 + 1)²)
+    #
+    # @example With Method objects
+    #   class MathOps
+    #     def square(x)
+    #       x * x
+    #     end
+    #   end
+    #
+    #   math = MathOps.new
+    #   add_one = proc { |x| x + 1 }
+    #   composed = math.method(:square).compose(add_one)
+    #   composed.call(3)  # => 16 ((3 + 1)²)
     def compose(other)
-      self.class.new do |*args|
+      block = -> *args {
         if other.respond_to?(:call)
           call(*other.call(*args))
         else
           call(*other.to_proc.call(*args))
         end
+      }
+      if self.class.respond_to?(:new)
+        self.class.new(&block)
+      else
+        Proc.new(&block)
       end
     end
 
+    # Alias for {compose} method, enabling the use of the * operator for
+    # composition.
+    #
+    # @see compose
     alias * compose
   end
 end

data/lib/tins/proc_prelude.rb

@@ -1,71 +1,158 @@
 require 'tins/memoize'
 
 module Tins
+  # Tins::ProcPrelude provides a set of utility methods for creating and composing
+  # Proc objects with common functional programming patterns.
+  #
+  # This module contains various helper methods that return lambda functions,
+  # making it easier to build complex processing pipelines and functional
+  # transformations. These are particularly useful in functional programming
+  # contexts or when working with higher-order functions.
+  #
+  # The methods are typically accessed through the singleton interface:
+  #   Proc.array.(1, 2, 3)  # => [1, 2, 3]
+  #
+  # @example Basic usage with map_apply in reduce context
+  #   # Create a proc that applies a method to each element and accumulates results
+  #   proc = Proc.map_apply(:upcase) { |s, upcased| s << upcased }
+  #
+  #   # Use it with Array#reduce
+  #   ['hello', 'world'].reduce([], &proc)
+  #   # => ['HELLO', 'WORLD']
+  #
+  # @example Using array to convert arguments to list
+  #   proc = Proc.array
+  #   proc.(1, 2, 3)
+  #   # => [1, 2, 3]
   module ProcPrelude
+    # Create a proc that applies the given block to a list of arguments.
+    #
+    # @yield [list] The block to apply to the arguments
+    # @return [Proc] A proc that takes arguments and calls the block with them unpacked
     def apply(&my_proc)
       my_proc or raise ArgumentError, 'a block argument is required'
-      lambda { |list| my_proc.call(*list) }
+      lambda { |list| my_proc.(*list) }
     end
 
+    # Create a proc that applies a method to an object and then applies the block.
+    #
+    # @param my_method [Symbol] The method name to call on each element
+    # @param args [Array] Additional arguments to pass to the method
+    # @yield [x, y] The block to apply after calling the method
+    # @return [Proc] A proc that takes two arguments and applies the method + block
+    # @raise [ArgumentError] if no block is provided
     def map_apply(my_method, *args, &my_proc)
       my_proc or raise ArgumentError, 'a block argument is required'
-      lambda { |x, y| my_proc.call(x, y.__send__(my_method, *args)) }
+      lambda { |x, y| my_proc.(x, y.__send__(my_method, *args)) }
     end
 
+    # Create a proc that evaluates a block in the context of an object.
+    #
+    # @param obj [Object] The object to evaluate the block against
+    # @yield [obj] The block to evaluate in the object's context
+    # @return [Proc] A proc that takes an object and evaluates the block
     def call(obj, &my_proc)
       my_proc or raise ArgumentError, 'a block argument is required'
       obj.instance_eval(&my_proc)
     end
 
+    # Create a proc that converts all arguments to a list array.
+    #
+    # @return [Proc] A proc that takes any number of arguments and returns them as a list
     def array
       lambda { |*list| list }
     end
-    memoize_function :array, freeze:  true
+    memoize function: :array, freeze:  true
 
+    # Create a proc that returns the first element (the head) of a list.
+    #
+    # @return [Proc] A proc that takes a list and returns its first element
     def first
       lambda { |*list| list.first }
     end
-    memoize_function :first, freeze:  true
+    memoize function: :first, freeze:  true
 
     alias head first
 
+    # Create a proc that returns the second element of a list.
+    #
+    # @return [Proc] A proc that takes a list and returns its second element
     def second
       lambda { |*list| list[1] }
     end
-    memoize_function :second, freeze:  true
+    memoize function: :second, freeze:  true
 
+    # Create a proc that returns all elements except the first (the tail) from
+    # a list.
+    #
+    # @return [Proc] A proc that takes a list and returns all but the first element
     def tail
       lambda { |*list| list[1..-1] }
     end
-    memoize_function :tail, freeze:  true
+    memoize function: :tail, freeze:  true
 
+    # Create a proc that returns the last element of a list.
+    #
+    # @return [Proc] A proc that takes a list and returns its last element
     def last
       lambda { |*list| list.last }
     end
-    memoize_function :last, freeze:  true
+    memoize function: :last, freeze:  true
 
+    # Create a proc that rotates a list by n positions.
+    #
+    # @param n [Integer] Number of positions to rotate (default: 1)
+    # @return [Proc] A proc that takes a list and returns it rotated
     def rotate(n = 1)
       lambda { |*list| list.rotate(n) }
     end
 
     alias swap rotate
 
+    # Create a proc that returns its argument unchanged.
+    #
+    # @return [Proc] A proc that takes an element and returns it unchanged
     def id1
       lambda { |obj| obj }
     end
-    memoize_function :id1, freeze:  true
+    memoize function: :id1, freeze:  true
 
+    # Create a proc that returns a constant value.
+    #
+    # @param konst [Object] The constant value to return (optional)
+    # @yield [konst] Block to compute the constant value if not provided
+    # @return [Proc] A proc that always returns the same value
     def const(konst = nil, &my_proc)
-      konst ||= my_proc.call
+      konst ||= my_proc.()
       lambda { |*_| konst }
     end
 
+    # Create a proc that returns the nth element of a list.
+    #
+    # @param n [Integer] The index of the element to return
+    # @return [Proc] A proc that takes a list and returns element at index n
     def nth(n)
       lambda { |*list| list[n] }
     end
 
+    # Create a proc that calls a method on self with given arguments.
+    #
+    # This method uses binding introspection to dynamically determine which
+    # method to call, making it useful for creating flexible function
+    # references.
+    #
+    # @yield [] The block that should return a method name (symbol)
+    # @return [Proc] A proc that takes arguments and calls the specified method
+    # @example Dynamic method invocation
+    #   def square(x)
+    #     x ** 2
+    #   end
+    #
+    #   proc = Proc.from { :square }
+    #   [1, 2, 3].map(&proc)
+    #   # => [1, 4, 9]
     def from(&block)
-      my_method, binding = block.call, block.binding
+      my_method, binding = block.(), block.binding
       my_self = eval 'self', binding
       lambda { |*list| my_self.__send__(my_method, *list) }
     end

data/lib/tins/range_plus.rb

@@ -1,9 +1,37 @@
 module Tins
+  # RangePlus extends the Range class with additional functionality.
+  #
+  # This module adds a `+` method to Range objects that concatenates the
+  # elements of two ranges into a single array.
+  #
+  # @example Basic usage
+  #   range1 = (1..3)
+  #   range2 = (4..6)
+  #   result = range1 + range2
+  #   # => [1, 2, 3, 4, 5, 6]
+  #
+  # @example With different range types
+  #   range1 = ('a'..'c')
+  #   range2 = ('d'..'f')
+  #   result = range1 + range2
+  #   # => ["a", "b", "c", "d", "e", "f"]
+  #
+  # @note This implementation converts both ranges to arrays and concatenates
+  # them. This means it will materialize the entire range into memory, which
+  # could be problematic for very large ranges.
   module RangePlus
+    # Concatenates two ranges by converting them to arrays and merging them.
+    #
+    # This method allows you to combine the elements of two ranges into a
+    # single array. Both ranges are converted to arrays using their `to_a`
+    # method, then concatenated together.
+    #
+    # @param other [Range] Another range to concatenate with this range
+    # @return [Array] A new array containing all elements from both ranges
+    # @example
+    #   (1..3) + (4..6)  # => [1, 2, 3, 4, 5, 6]
     def +(other)
       to_a + other.to_a
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/require_maybe.rb

@@ -1,5 +1,41 @@
 module Tins
+  # A module that provides a safe require mechanism with optional error handling.
+  #
+  # This module is included in Object, making the `require_maybe` method globally
+  # available throughout your Ruby application. It enables conditional loading of
+  # libraries where the failure to load a dependency is not necessarily an error
+  # condition, making it ideal for optional dependencies and feature detection.
+  #
+  # @example Basic usage anywhere in your codebase
+  #   # Available globally:
+  #   require_maybe 'foo'  # Returns true/false
+  #
+  # @example Providing fallback behavior
+  #   class MyParser
+  #     def parse_data(data)
+  #       if require_maybe('foo')
+  #         Foo::Parser.parse(data)
+  #       else
+  #         Bar.parse(data)  # Fallback
+  #       end
+  #     end
+  #   end
+  #
+  # @example With error handling block
+  #   require_maybe 'some_gem' do |error|
+  #     puts "Optional gem 'some_gem' not available: #{error.message}"
+  #   end
   module RequireMaybe
+    # Attempts to require a library, gracefully handling LoadError exceptions.
+    #
+    # This method is globally available because the module is included in
+    # Object. It's particularly useful for optional dependencies and feature
+    # detection.
+    #
+    # @param library [String] The name of the library to require
+    # @yield [LoadError] Optional block to handle the LoadError
+    # @yieldparam error [LoadError] The rescued LoadError exception
+    # @return [Boolean] Returns true if library was loaded successfully, false otherwise
     def require_maybe(library)
       require library
     rescue LoadError => e

data/lib/tins/responding.rb

@@ -1,5 +1,44 @@
 module Tins
+  # A module that provides a convenient way to check if objects respond to
+  # specific methods.
+  #
+  # The `responding?` method returns an object that can be used with the
+  # case/when construct to test if an object responds to certain methods. This is
+  # particularly useful for duck typing and implementing polymorphic behavior.
+  #
+  # @example Check duck types
+  #   if responding?(:eof?, :gets) === obj
+  #     until obj.eof?
+  #       puts obj.gets
+  #     end
+  #  end
+  #
+  # @example Easy interface checks
+  #   case obj
+  #   when responding?(:length, :keys)
+  #     puts "  → Hash-like object (has size and keys)"
+  #   when responding?(:size, :begin)
+  #     puts "  → Range-like object (has size and begin)"
+  #   when responding?(:length, :push)
+  #     puts "  → Array-like object (has size and push)"
+  #   when responding?(:length, :upcase)
+  #     puts "  → String-like object (has length and upcase)"
+  #   when responding?(:read, :write)
+  #     puts "  → IO-like object (has read and write)"
+  #   else
+  #     puts "  → Unknown interface"
+  #   end
   module Responding
+    # Returns a special object that can be used to test if objects respond to
+    # specific methods. The returned object implements `===` to perform the
+    # check.
+    #
+    # This is particularly useful for duck typing and case/when constructs
+    # where you want to match against objects based on their interface rather
+    # than their class.
+    #
+    # @param method_names [Array<Symbol>] One or more method names to check for
+    # @return [Object] A special object that responds to `===` for method checking
     def responding?(*method_names)
       Class.new do
         define_method(:to_s) do

data/lib/tins/secure_write.rb

@@ -1,6 +1,28 @@
 module Tins
+  # A module that provides secure file writing capabilities.
+  #
+  # This module extends objects with a method to write data to files in a way
+  # that ensures atomicity and prevents partial writes, making it safer for
+  # concurrent access.
   module SecureWrite
-    # Write to a file atomically
+    # Write to a file atomically by creating a temporary file and renaming it.
+    # This ensures that readers will either see the complete old content or
+    # the complete new content, never partial writes.
+    #
+    # @param filename [String, #to_s] The target filename
+    # @param content [String, nil] The content to write (optional)
+    # @param mode [String] File open mode (default: 'w')
+    # @yield [File] If a block is given, yields the temporary file handle
+    # @return [Integer] The number of bytes written
+    # @raise [ArgumentError] If neither content nor block is provided
+    #
+    # @example With content
+    #   File.secure_write('config.json', '{"timeout": 30}')
+    #
+    # @example With block
+    #   File.secure_write('output.txt') do |f|
+    #     f.write("Hello, World!")
+    #   end
     def secure_write(filename, content = nil, mode = 'w')
       temp = File.new(filename.to_s + ".tmp.#$$.#{Time.now.to_f}", mode)
       if content.nil? and block_given?
@@ -17,11 +39,9 @@ module Tins
       size
     ensure
       if temp
-        !temp.closed? and temp.close
+        temp.closed? or temp.close
         File.file?(temp.path) and File.unlink temp.path
       end
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/sexy_singleton.rb

@@ -2,65 +2,62 @@ require 'tins/string_version'
 require 'singleton'
 
 module Tins
-
+  # Enhanced singleton implementation that forwards method calls to the
+  # instance.
+  #
+  # This module provides a "sexy" singleton implementation that extends the
+  # standard Ruby singleton pattern by making the singleton class itself
+  # respond to methods defined on the instance. This allows for more intuitive
+  # usage where you can call singleton methods directly on the class without
+  # needing to access the instance explicitly.
+  #
+  # @example Basic usage
+  #   class MySingleton
+  #     include Tins::SexySingleton
+  #
+  #     def hello
+  #       "Hello World"
+  #     end
+  #   end
+  #
+  #   # You can now call methods directly on the class
+  #   MySingleton.hello  # => "Hello World"
   SexySingleton = Singleton.dup
 
-  module SexySingleton
-    module SingletonClassMethods
-    end
-  end
-
-  class << SexySingleton
+  SexySingleton.singleton_class.class_eval do
     alias __old_singleton_included__ included
 
-    if Tins::StringVersion.compare(RUBY_VERSION, :<, "2.7")
-      def included(klass)
-        __old_singleton_included__(klass)
-        (class << klass; self; end).class_eval do
-          if Object.method_defined?(:respond_to_missing?)
-            def  respond_to_missing?(name, *args)
-              instance.respond_to?(name) || super
-            end
-          else
-            def respond_to?(name, *args)
-              instance.respond_to?(name) || super
-            end
+    # Extends the standard singleton inclusion to forward method calls from the
+    # singleton class to the instance.
+    #
+    # This method is automatically called when including {SexySingleton} in a
+    # class. It sets up the singleton class to delegate method calls to the
+    # instance, making it possible to call singleton methods directly on the
+    # class.
+    #
+    # @param klass [Class] The class that includes this module
+    def included(klass)
+      __old_singleton_included__(klass)
+      klass.singleton_class.class_eval do
+        if Object.method_defined?(:respond_to_missing?)
+          def  respond_to_missing?(name, *args, **kwargs)
+            instance.respond_to?(name) || super
           end
-
-          def method_missing(name, *args, &block)
-            if instance.respond_to?(name)
-              instance.__send__(name, *args, &block)
-            else
-              super
-            end
+        else
+          def respond_to?(name, *args, **kwargs)
+            instance.respond_to?(name) || super
           end
         end
-        super
-      end
-    else
-      def included(klass)
-        __old_singleton_included__(klass)
-        (class << klass; self; end).class_eval do
-          if Object.method_defined?(:respond_to_missing?)
-            def  respond_to_missing?(name, *args, **kwargs)
-              instance.respond_to?(name) || super
-            end
-          else
-            def respond_to?(name, *args, **kwargs)
-              instance.respond_to?(name) || super
-            end
-          end
 
-          def method_missing(name, *args, **kwargs, &block)
-            if instance.respond_to?(name)
-              instance.__send__(name, *args, **kwargs, &block)
-            else
-              super
-            end
+        def method_missing(name, *args, **kwargs, &block)
+          if instance.respond_to?(name)
+            instance.__send__(name, *args, **kwargs, &block)
+          else
+            super
           end
         end
-        super
       end
+      super
     end
   end
 end

data/lib/tins/string_byte_order_mark.rb

@@ -1,7 +1,40 @@
 require 'tins/concern'
 
 module Tins
+  # Tins::StringByteOrderMark provides methods for detecting and identifying
+  # byte order marks (BOMs) in strings.
+  #
+  # This module contains the `bom_encoding` method which analyzes the beginning
+  # of a string to determine its encoding based on the presence of BOM bytes.
+  # This is particularly useful when working with text files that may have
+  # different encodings and BOM markers.
+  #
+  # @example Detecting UTF-8 BOM
+  #   "\xef\xbb\xbfhello".bom_encoding
+  #   # => Encoding::UTF_8
+  #
+  # @example Detecting UTF-16BE BOM
+  #   "\xfe\xffhello".bom_encoding
+  #   # => Encoding::UTF_16BE
+  #
+  # @example No BOM detected
+  #   "hello".bom_encoding
+  #   # => nil
   module StringByteOrderMark
+    # Detect the encoding of a string based on its byte order mark (BOM).
+    #
+    # This method examines the first 4 bytes of the string to identify
+    # common Unicode BOM patterns and returns the corresponding Encoding object.
+    # The method handles various Unicode encodings that use BOM markers:
+    # - UTF-8 (EF BB BF)
+    # - UTF-16BE (FE FF)
+    # - UTF-16LE (FF FE)
+    # - UTF-32BE (00 00 FF FE)
+    # - UTF-32LE (FF FE 00 00)
+    # - UTF-7 (2B 2F 76 followed by specific bytes)
+    # - GB18030 (84 31 95 33)
+    #
+    # @return [Encoding, nil] The detected encoding if a BOM is found, otherwise nil
     def bom_encoding
       prefix = self[0, 4].force_encoding(Encoding::ASCII_8BIT)
       case prefix
@@ -16,5 +49,3 @@ module Tins
     end
   end
 end
-
-require 'tins/alias'