tins 1.32.0 → 1.44.0

data/lib/tins/null.rb

@@ -1,68 +1,131 @@
 module Tins
-  # Implementation of the null object pattern in Ruby.
+  # Tins::Null provides an implementation of the null object pattern in Ruby.
+  #
+  # The null object pattern is a behavioral design pattern that allows you to
+  # avoid null references by providing a default object that implements the
+  # expected interface but does nothing. This eliminates the need for null
+  # checks throughout your codebase.
+  #
+  # This module provides the core functionality for null objects, including:
+  # - Method missing behavior that returns self
+  # - Type conversion methods that return appropriate default values
+  # - Debugging support through NullPlus
+  #
+  # @example Basic usage
+  #   # Instead of checking for nil:
+  #   user = find_user(id)
+  #   if user
+  #     user.name
+  #   else
+  #     "Unknown"
+  #   end
+  #
+  #   # You can use the null object:
+  #   user = find_user(id) || Tins::NULL
+  #   user.name  # => "" (instead of nil)
+  #
+  # @example With NullPlus for debugging
+  #   user = find_user(id) || Tins::NullPlus.new(value: "Unknown", caller: caller)
+  #   user.value  # => "Unknown"
   module Null
+    # Handle missing methods by returning self, allowing method chaining.
+    #
+    # @return [self] Always returns self to allow chaining
     def method_missing(*)
       self
     end
 
+    # Handle missing constants by returning self.
+    #
+    # @return [self] Always returns self
     def const_missing(*)
       self
     end
 
+    # Convert to string representation.
+    #
+    # @return [String] Empty string
     def to_s
       ''
     end
 
-    def to_str
-      nil
-    end
-
+    # Convert to float.
+    #
+    # @return [Float] Zero as float
     def to_f
       0.0
     end
 
+    # Convert to integer.
+    #
+    # @return [Integer] Zero
     def to_i
       0
     end
 
-    def to_int
-      nil
-    end
-
+    # Convert to array.
+    #
+    # @return [Array] Empty array
     def to_a
       []
     end
 
-    def to_ary
-      nil
-    end
-
+    # Inspect representation.
+    #
+    # @return [String] "NULL"
     def inspect
       'NULL'
     end
 
+    # Check if object is nil.
+    #
+    # @return [Boolean] Always returns true
     def nil?
       true
     end
 
+    # Check if object is blank.
+    #
+    # @return [Boolean] Always returns true
     def blank?
       true
     end
 
+    # Convert to JSON (for compatibility with JSON serialization).
+    #
+    # @return [nil] returns nil value
     def as_json(*)
+      nil
     end
 
+    # Convert to JSON string.
+    #
+    # @return [String] "null"
     def to_json(*)
       'null'
     end
 
+    # Kernel extensions for null object creation.
     module Kernel
+      # Create a null object or return the provided value if not nil.
+      #
+      # @param value [Object] The value to check
+      # @return [Object] Tins::NULL if value is nil, otherwise value
       def null(value = nil)
         value.nil? ? Tins::NULL : value
       end
 
       alias Null null
 
+      # Create a null object with additional debugging information.
+      #
+      # This creates a NullPlus object that includes caller information for
+      # debugging purposes when the null object is used.
+      #
+      # @param opts [Hash] Options for the null object
+      # @option opts [Object] :value The value to return from the null object
+      # @option opts [Array] :caller Caller information
+      # @return [Object] Tins::NullPlus if value is nil, otherwise value
       def null_plus(opts = {})
         value = opts[:value]
         opts[:caller] = caller
@@ -77,17 +140,27 @@ module Tins
     end
   end
 
+  # NullClass represents the singleton null object instance.
   class NullClass < Module
     include Tins::Null
   end
 
+  # The singleton null object instance.
   NULL = NullClass.new
 
+  # Freeze the singleton to prevent modification.
   NULL.freeze
 
+  # Enhanced null object with debugging capabilities.
+  #
+  # NullPlus extends the basic null object with additional features for debugging,
+  # including caller information and custom attribute access.
   class NullPlus
     include Tins::Null
 
+    # Initialize a NullPlus object with options.
+    #
+    # @param opts [Hash] Configuration options
     def initialize(opts = {})
       singleton_class.class_eval do
         opts.each do |name, value|
@@ -97,5 +170,3 @@ module Tins
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/once.rb

@@ -1,9 +1,52 @@
 module Tins
+  # A module for ensuring exclusive execution of code blocks using file-based
+  # locking.
+  #
+  # This module provides mechanisms to prevent multiple instances of a script
+  # from running simultaneously by using file system locks on the script itself
+  # or a specified lock file.
+  #
+  # @example Basic usage with automatic lock file detection
+  #   Tins::Once.only_once do
+  #     # Critical section - only one instance runs at a time
+  #     perform_backup()
+  #   end
+  #
+  # @example Using custom lock file
+  #   Tins::Once.only_once("/var/run/myapp.lock") do
+  #     # Custom lock file
+  #     process_data()
+  #   end
+  #
+  # @example Non-blocking attempt
+  #   begin
+  #     Tins::Once.try_only_once do
+  #       # Will raise if another instance holds the lock
+  #       update_cache()
+  #     end
+  #   rescue => e
+  #     puts "Another instance is running"
+  #   end
   module Once
     include File::Constants
 
-    module_function
-
+    # Executes a block of code exclusively, ensuring only one instance runs at
+    # a time.
+    #
+    # Uses the script name (or specified lock file) as the locking mechanism.
+    # The first invocation will acquire an exclusive lock and execute the
+    # block, while subsequent invocations will block until the lock is
+    # released.
+    #
+    # @param lock_filename [String] Optional custom lock filename.
+    #   Defaults to `$0` (the script name), which means the script itself
+    #   is used as the lock file.
+    # @param locking_constant [Integer] File locking constant.
+    #   Defaults to `LOCK_EX` for exclusive locking.
+    # @yield [void] The block of code to execute exclusively
+    # @return [Object] The return value of the yielded block
+    # @raise [Errno::ENOENT] If the lock file doesn't exist
+    # @raise [SystemCallError] If file locking fails
     def only_once(lock_filename = nil, locking_constant = nil)
       lock_filename ||= $0
       locking_constant ||= LOCK_EX
@@ -16,10 +59,24 @@ module Tins
       end
     end
 
+    # Attempts to execute a block of code exclusively, but fails immediately
+    # if another instance holds the lock.
+    #
+    # This is a non-blocking version that will raise an exception if the lock
+    # cannot be acquired immediately.
+    #
+    # @param lock_filename [String] Optional custom lock filename.
+    #   Defaults to `$0` (the script name).
+    # @param locking_constant [Integer] File locking constant.
+    #   Defaults to `LOCK_EX | LOCK_NB` for non-blocking exclusive locking.
+    # @yield [void] The block of code to execute exclusively
+    # @return [Object] The return value of the yielded block
+    # @raise [Errno::EAGAIN] If another process holds the lock
+    # @raise [Errno::ENOENT] If the lock file doesn't exist
     def try_only_once(lock_filename = nil, locking_constant = nil, &block)
       only_once(lock_filename, locking_constant || LOCK_EX | LOCK_NB, &block)
     end
+
+    module_function :only_once, :try_only_once
   end
 end
-
-require 'tins/alias'

data/lib/tins/p.rb

@@ -1,23 +1,59 @@
 require 'pp'
 
 module Tins
+  # A module that provides debugging methods for inspecting objects by raising
+  # exceptions with their inspected representations.
+  #
+  # This module adds p! and pp! methods that raise RuntimeError exceptions
+  # containing the inspected or pretty-inspected output of objects, making it
+  # easy to quickly debug values during development without printing to stdout.
+  #
+  # @example Using p! to inspect a single object
+  #   p!(some_variable)
+  #
+  # @example Using pp! to inspect multiple objects
+  #   pp!(first_var, second_var)
   module P
     private
 
-    # Raise a runtime error with the inspected objects +objs+ (obtained by
-    # calling the #inspect method) as their message text. This is useful for
-    # quick debugging.
+    # Raises a RuntimeError with the inspected representation of the given
+    # objects.
+    #
+    # This method is useful for quick debugging by raising an exception that
+    # contains the inspected output of the provided objects. It behaves
+    # similarly to Ruby's built-in +p+ method but raises an exception instead
+    # of printing to stdout.
+    #
+    # @example Basic usage with single object
+    #   p!(some_variable)
+    #
+    # @example Basic usage with multiple objects
+    #   p!(first_var, second_var)
+    #
+    # @param objs [Array<Object>] One or more objects to inspect and raise
+    # @raise [RuntimeError] Always raises a RuntimeError with inspected content
     def p!(*objs)
       raise((objs.size < 2 ? objs.first : objs).inspect)
     end
 
-    # Raise a runtime error with the inspected objects +objs+ (obtained by
-    # calling the #pretty_inspect method) as their message text. This is useful
-    # for quick debugging.
+    # Raises a RuntimeError with the pretty-inspected representation of the
+    # given objects.
+    #
+    # This method is useful for quick debugging by raising an exception that
+    # contains the pretty-printed output of the provided objects. It behaves
+    # similarly to Ruby's built-in +pp+ method but raises an exception instead
+    # of printing to stdout.
+    #
+    # @example Basic usage with single object
+    #   pp!(some_variable)
+    #
+    # @example Basic usage with multiple objects
+    #   pp!(first_var, second_var)
+    #
+    # @param objs [Array<Object>] One or more objects to pretty-inspect and raise
+    # @raise [RuntimeError] Always raises a RuntimeError with pretty-inspected content
     def pp!(*objs)
       raise("\n" + (objs.size < 2 ? objs.first : objs).pretty_inspect.chomp)
     end
   end
 end
-
-require 'tins/alias'

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