tins 1.32.0 → 1.44.0

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,8 +1,30 @@
 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 + ".tmp.#$$.#{Time.now.to_f}", mode)
+      temp = File.new(filename.to_s + ".tmp.#$$.#{Time.now.to_f}", mode)
       if content.nil? and block_given?
         yield temp
       elsif !content.nil?
@@ -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

@@ -1,65 +1,63 @@
+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 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'

data/lib/tins/string_camelize.rb

@@ -1,5 +1,36 @@
 module Tins
+  # Tins::StringCamelize provides methods for converting snake_case strings
+  # to camelCase or PascalCase format.
+  #
+  # This module contains the `camelize` method which is commonly used in Ruby
+  # applications, particularly in Rails-style naming conventions where developers
+  # need to convert between different naming styles.
+  #
+  # @example Converting snake_case to PascalCase (default)
+  #   "snake_case_string".camelize
+  #   # => "SnakeCaseString"
+  #
+  # @example Converting snake_case to camelCase
+  #   "snake_case_string".camelize(:lower)
+  #   # => "snakeCaseString"
+  #
+  # @example Handling nested module paths
+  #   "my/module/class_name".camelize
+  #   # => "My::Module::ClassName"
   module StringCamelize
+    # Convert a snake_case string to camelCase or PascalCase format.
+    #
+    # This method handles various naming conventions:
+    # - Converts snake_case to PascalCase (default) or camelCase
+    # - Handles nested module paths with '/' separators
+    # - Supports different first letter cases
+    #
+    # @param first_letter [Symbol, Boolean] Controls capitalization of first letter
+    # @option first_letter :upper (default) Convert first letter to uppercase (PascalCase)
+    # @option first_letter :lower Convert first letter to lowercase (camelCase)
+    # @option first_letter true Same as :upper
+    # @option first_letter false Same as :lower
+    # @return [String] A new string in camelCase or PascalCase format
     def camelize(first_letter = :upper)
       case first_letter
       when :upper, true
@@ -12,5 +43,3 @@ module Tins
     alias camelcase camelize
   end
 end
-
-require 'tins/alias'

data/lib/tins/string_named_placeholders.rb

@@ -0,0 +1,70 @@
+module Tins
+  # A module that provides methods for working with named placeholders in strings.
+  #
+  # This module adds functionality to extract named placeholders from strings
+  # and assign values to them, making it easier to work with template-style
+  # strings that contain named substitution points.
+  #
+  # @example Extracting named placeholders from a string
+  #   "Hello %{name}, you have %{count} messages".named_placeholders
+  #   # => [:name, :count]
+  #
+  # @example Assigning values to named placeholders
+  #   template = "Welcome %{user}, your balance is %{amount}"
+  #   template.named_placeholders_assign(user: "Alice", amount: "$100")
+  #   # => {:user=>"Alice", :amount=>"$100"}
+  module StringNamedPlaceholders
+    # Returns an array of symbols representing the named placeholders found in
+    # the string.
+    #
+    # This method scans the string for patterns matching named placeholders in
+    # the format %{name} and extracts the placeholder names, returning them as
+    # symbols in an array.
+    #
+    # @return [Array<Symbol>] An array of unique symbol representations of the
+    # named placeholders found in the string.
+    def named_placeholders
+      scan(/%\{([^}]+)\}/).inject([], &:concat).uniq.map(&:to_sym)
+    end
+
+    # Assign values to named placeholders from a hash, using a default value
+    # for unspecified placeholders.
+    #
+    # This method takes a hash of placeholder values and assigns them to the
+    # named placeholders found in the string. If a placeholder is not present
+    # in the input hash, the provided default value is used instead. The
+    # default can be a static value or a proc that receives the placeholder
+    # symbol as an argument.
+    #
+    # @param hash [Hash] A hash mapping placeholder names to their corresponding values.
+    # @param default [Object, Proc] The default value to use for placeholders not present in the hash.
+    #                              If a proc is provided, it will be called with the placeholder symbol.
+    #
+    # @return [Hash] A new hash containing the assigned values for each named
+    # placeholder.
+    def named_placeholders_assign(hash, default: nil)
+      hash = hash.transform_keys(&:to_sym)
+      named_placeholders.each_with_object({}) do |placeholder, h|
+        h[placeholder] = hash[placeholder] ||
+          (default.is_a?(Proc) ? default.(placeholder) : default)
+      end
+    end
+
+    # Interpolate named placeholders in the string with values from a hash.
+    #
+    # This method takes a hash of placeholder values and substitutes the named
+    # placeholders found in the string with their corresponding values.
+    # Placeholders that are not present in the input hash will be replaced with
+    # the provided default value.
+    #
+    # @param hash [Hash] A hash mapping placeholder names to their corresponding values
+    # @param default [Object, Proc] The default value to use for placeholders not present in the hash
+    #                              If a proc is provided, it will be called with the placeholder symbol
+    #
+    # @return [String] A new string with named placeholders replaced by their values
+    def named_placeholders_interpolate(hash, default: nil)
+      values = named_placeholders_assign(hash, default:)
+      self % values
+    end
+  end
+end

data/lib/tins/string_underscore.rb

@@ -1,5 +1,38 @@
 module Tins
+  # Tins::StringUnderscore provides methods for converting camelCase and
+  # PascalCase strings to snake_case format.
+  #
+  # This module contains the `underscore` method which is commonly used in Ruby
+  # applications, particularly in Rails-style naming conventions where developers
+  # need to convert between different naming styles.
+  #
+  # @example Converting camelCase to snake_case
+  #   "camelCaseString".underscore
+  #   # => "camel_case_string"
+  #
+  # @example Converting PascalCase to snake_case
+  #   "PascalCaseString".underscore
+  #   # => "pascal_case_string"
+  #
+  # @example Handling nested modules
+  #   "My::Module::ClassName".underscore
+  #   # => "my/module/class_name"
+  #
+  # @example Mixed case with dashes
+  #   "camel-case-string".underscore
+  #   # => "camel_case_string"
   module StringUnderscore
+    # Convert a camelCase or PascalCase string to snake_case format.
+    #
+    # This method handles various naming conventions:
+    # - Converts camelCase to snake_case (e.g., "camelCase" → "camel_case")
+    # - Converts PascalCase to snake_case (e.g., "PascalCase" → "pascal_case")
+    # - Handles consecutive uppercase letters (e.g., "XMLParser" → "xml_parser")
+    # - Replaces dashes with underscores
+    # - Converts to lowercase
+    # - Handles nested module paths with '::' separators
+    #
+    # @return [String] A new string in snake_case format
     def underscore
       word = dup
       word.gsub!(/::/, '/')
@@ -11,5 +44,3 @@ module Tins
     end
   end
 end
-
-require 'tins/alias'