tins 1.43.0 → 1.44.0

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_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'

data/lib/tins/string_version.rb

@@ -1,29 +1,147 @@
 module Tins
+  # Provides version string parsing and comparison functionality.
+  #
+  # This module allows working with semantic version strings in a more intuitive way,
+  # supporting operations like comparison, incrementing, and accessing individual components.
+  #
+  # @example Basic usage
+  #   version = "1.2.3".version
+  #   puts version.major # => 1
+  #   puts version.minor # => 2
+  #   puts version.build # => 3
+  #
+  # @example Comparison operations
+  #   v1 = "1.2.3".version
+  #   v2 = "1.2.4".version
+  #   puts v1 < v2       # => true
+  #   puts v1 == v2      # => false
+  #
+  # @example Version manipulation
+  #   version = "1.2.3".version
+  #   version.bump(:minor) # => "1.3.0"
+  #   version.succ!        # increments last component
   module StringVersion
-    LEVELS  = [ :major, :minor, :build, :revision ].each_with_index.
+    # Map of version level symbols to their numeric indices
+    LEVELS = [ :major, :minor, :build, :revision ].each_with_index.
       each_with_object({}) { |(k, v), h| h[k] = v }.freeze
 
+    # Inverted map of LEVELS for symbol lookup
     SYMBOLS = LEVELS.invert.freeze
 
+    # Represents a version string with semantic comparison capabilities
+    #
+    # @example Creating a Version object
+    #   version = Tins::StringVersion::Version.new("1.2.3")
+    #
+    # @example Accessing components
+    #   v = "1.2.3".version
+    #   puts v.major # => 1
+    #   puts v.minor # => 2
+    #   puts v.build # => 3
     class Version
       include Comparable
 
+      # Creates a new version object from a string representation
+      #
+      # @param string [String] The version string (e.g., "1.2.3")
+      # @raise [ArgumentError] If the string doesn't match a valid version pattern
+      # @example
+      #   Tins::StringVersion::Version.new("1.2.3")
+      #   # => #<Tins::StringVersion::Version:0x00007f8b8c0b0a80 @version="1.2.3">
       def initialize(string)
         string =~ /\A\d+(\.\d+)*\z/ or
           raise ArgumentError, "#{string.inspect} isn't a version number"
         @version = string.frozen? ? string.dup : string
       end
 
-      LEVELS.each do |symbol, level|
-        define_method(symbol) do
-          self[level]
-        end
+      # Returns the major version component
+      #
+      # @return [Integer] The major version number
+      # @example
+      #   "1.2.3".version.major # => 1
+      def major
+        self[0]
+      end
 
-        define_method("#{symbol}=") do |new_level|
-          self[level] = new_level
-        end
+      # Sets the major version component
+      #
+      # @param new_level [Integer] The new major version number
+      # @return [Integer] The updated major version number
+      # @example
+      #   v = "1.2.3".version
+      #   v.major = 5 # sets major to 5
+      def major=(new_level)
+        self[0] = new_level
+      end
+
+      # Returns the minor version component
+      #
+      # @return [Integer] The minor version number
+      # @example
+      #   "1.2.3".version.minor # => 2
+      def minor
+        self[1]
+      end
+
+      # Sets the minor version component
+      #
+      # @param new_level [Integer] The new minor version number
+      # @return [Integer] The updated minor version number
+      # @example
+      #   v = "1.2.3".version
+      #   v.minor = 5 # sets minor to 5
+      def minor=(new_level)
+        self[1] = new_level
+      end
+
+      # Returns the build version component
+      #
+      # @return [Integer] The build version number
+      # @example
+      #   "1.2.3".version.build # => 3
+      def build
+        self[2]
+      end
+
+      # Sets the build version component
+      #
+      # @param new_level [Integer] The new build version number
+      # @return [Integer] The updated build version number
+      # @example
+      #   v = "1.2.3".version
+      #   v.build = 5 # sets build to 5
+      def build=(new_level)
+        self[2] = new_level
+      end
+
+      # Returns the revision version component
+      #
+      # @return [Integer] The revision version number
+      # @example
+      #   "1.2.3".version.revision # => nil (no revision component)
+      def revision
+        self[3]
+      end
+
+      # Sets the revision version component
+      #
+      # @param new_level [Integer] The new revision version number
+      # @return [Integer] The updated revision version number
+      # @example
+      #   v = "1.2.3".version
+      #   v.revision = 5 # sets revision to 5
+      def revision=(new_level)
+        self[3] = new_level
       end
 
+      # Increments a specified version component and resets subsequent components
+      #
+      # @param level [Symbol, Integer] The level to bump (default: last component)
+      # @return [self] Returns self for chaining
+      # @example
+      #   v = "1.2.3".version
+      #   v.bump(:minor) # => "1.3.0"
+      #   v.bump         # => "1.3.1" (bumps last component)
       def bump(level = array.size - 1)
         level = level_of(level)
         self[level] += 1
@@ -33,6 +151,10 @@ module Tins
         self
       end
 
+      # Converts a symbolic level to its numeric index
+      #
+      # @param specifier [Symbol, Integer] The level specification
+      # @return [Integer] The corresponding numeric index
       def level_of(specifier)
         if specifier.respond_to?(:to_sym)
           LEVELS.fetch(specifier)
@@ -41,10 +163,20 @@ module Tins
         end
       end
 
+      # Gets a version component by index or symbol
+      #
+      # @param level [Symbol, Integer] The level to retrieve
+      # @return [Integer] The version component value
       def [](level)
         array[level_of(level)]
       end
 
+      # Sets a version component by index or symbol
+      #
+      # @param level [Symbol, Integer] The level to set
+      # @param value [Integer] The new value for the component
+      # @return [Integer] The updated value
+      # @raise [ArgumentError] If value is negative
       def []=(level, value)
         level = level_of(level)
         value = value.to_i
@@ -56,16 +188,26 @@ module Tins
         @version.replace a * ?.
       end
 
+      # Increments the last version component
+      #
+      # @return [self] Returns self for chaining
       def succ!
         self[-1] += 1
         self
       end
 
+      # Decrements the last version component
+      #
+      # @return [self] Returns self for chaining
       def pred!
         self[-1] -= 1
         self
       end
 
+      # Compares this version with another
+      #
+      # @param other [Tins::StringVersion::Version] The version to compare against
+      # @return [Integer] -1 if self < other, 0 if equal, 1 if self > other
       def <=>(other)
         pairs = array.zip(other.array)
         pairs.map! { |a, b| [ a.to_i, b.to_i ] }
@@ -73,40 +215,67 @@ module Tins
         a <=> b
       end
 
+      # Checks equality with another version
+      #
+      # @param other [Tins::StringVersion::Version] The version to compare against
+      # @return [Boolean] true if versions are equal
       def ==(other)
         (self <=> other).zero?
       end
 
+      # Converts the version to an array of integers
+      #
+      # @return [Array<Integer>] Array representation of the version
       def array
         @version.split(?.).map(&:to_i)
       end
 
+      # Alias for {#array}
       alias to_a array
 
+      # Returns the string representation of this version
+      #
+      # @return [String] The version string
       def to_s
         @version
       end
 
+      # Creates a copy of this version object
+      #
+      # @param source [Tins::StringVersion::Version] Source version to copy from
+      # @return [void]
       def initialize_copy(source)
         super
         @version = source.instance_variable_get(:@version).dup
       end
 
+      # Alias for {#to_s}
       alias inspect to_s
     end
 
+    # Creates a Version object from this string
+    #
+    # @return [Tins::StringVersion::Version] The version object
     def version
       Version.new(self)
     end
 
+    # Compares two version strings using the specified operator
+    #
+    # @param version1 [String] First version string
+    # @param operator [Symbol] Comparison operator (:<, :<=, :==, :>=, :>)
+    # @param version2 [String] Second version string
+    # @return [Boolean] Result of the comparison
     def self.compare(version1, operator, version2)
       Version.new(version1).send(operator, Version.new(version2))
     end
   end
 
+  # Creates a Version object directly from a string-like object
+  #
+  # @param string [String] The version string
+  # @return [Tins::StringVersion::Version] The version object
   def self.StringVersion(string)
     StringVersion::Version.new(string.to_str)
   end
 end
-
-require 'tins/alias'

data/lib/tins/subhash.rb

@@ -1,14 +1,41 @@
 module Tins
+  # Tins::Subhash provides methods for creating filtered subsets of hashes
+  # based on pattern matching against keys.
+  #
+  # The subhash method allows you to extract key-value pairs from a hash
+  # that match specified patterns, making it easy to work with subsets of
+  # hash data based on naming conventions or other criteria.
+  #
+  # @example Basic usage with string patterns
+  #   hash = { 'foo' => 1, 'bar' => 2, 'foobar' => 3 }
+  #   sub = hash.subhash('foo')
+  #   # => { 'foo' => 1, 'foobar' => 3 }
+  #
+  # @example Usage with regular expressions
+  #   hash = { 'foo' => 1, 'barfoot' => 2, 'foobar' => 3 }
+  #   sub = hash.subhash(/^foo/)
+  #   # => { 'foo' => 1, 'foobar' => 3 }
+  #
+  # @example Usage with block for value transformation
+  #   hash = { 'foo' => 1, 'bar' => 2, 'foobar' => 3 }
+  #   sub = hash.subhash('foo') { |key, value, match_data| value * 2 }
+  #   # => { 'foo' => 2, 'foobar' => 6 }
   module Subhash
-    # Create a subhash from this hash, that only contains key-value pairs
-    # matching +patterns+ and return it. +patterns+ can be for example /^foo/
-    # to put 'foobar' and 'foobaz' or 'foo'/:foo to put 'foo' into the subhash.
+    # Create a subhash from this hash containing only key-value pairs
+    # where the key matches any of the given patterns.
     #
-    # If a block is given this method yields to it after the first pattern
-    # matched with a 3-tuple of +(key, value, match_data)+ using the return
-    # value of the block as the value of the result hash. +match_data+ is a
-    # MatchData instance if the matching pattern was a regular rexpression
-    # otherwise it is nil.
+    # Patterns can be:
+    # - Regular expressions (matched against key strings)
+    # - Strings (exact string matching)
+    # - Symbols (converted to strings for matching)
+    # - Any object that implements === operator
+    #
+    # @param patterns [Array<Object>] One or more patterns to match against keys
+    # @yield [key, value, match_data] Optional block to transform values
+    # @yieldparam key [String] The original hash key
+    # @yieldparam value [Object] The original hash value
+    # @yieldparam match_data [MatchData, nil] Match data when pattern is regex, nil otherwise
+    # @return [Hash] A new hash containing only matching key-value pairs
     def subhash(*patterns)
       patterns.map! do |pat|
         pat = pat.to_sym.to_s if pat.respond_to?(:to_sym)
@@ -38,5 +65,3 @@ module Tins
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/temp_io.rb

@@ -1,7 +1,14 @@
 require 'tmpdir'
 
 module Tins
+  # A module for creating temporary files and handling their contents securely.
   module TempIO
+    # Creates a temporary file with the given content and yields it to a block.
+    #
+    # @param content [String, #call] the content to write to the temporary file
+    # @param name [String, Symbol] the base name for the temporary file
+    # @yield [io] yields the temporary file handle to the given block
+    # @return [Object] the return value of the block
     def temp_io(content: nil, name: __method__)
       content.nil? and raise ArgumentError, "missing keyword: content"
       name = File.basename(name.to_s)

data/lib/tins/temp_io_enum.rb

@@ -2,9 +2,28 @@ require 'tins/temp_io'
 
 module Tins
   module TempIO
+    # A streaming enumerator that reads file content in configurable chunks
+    # from temporary files.
+    #
+    # This class provides an efficient way to process large files without
+    # loading them entirely into memory. It creates a temporary file from the
+    # provided content generator and yields data in fixed-size chunks.
     class Enum < Enumerator
       include Tins::TempIO
 
+      # This method creates an enumerator that yields chunks of data from a
+      # temporary file generated from the provided content proc. It's designed
+      # for streaming large files efficiently (to a user's web browser for
+      # example) by reading them in fixed-size chunks rather than loading
+      # everything into memory.
+      #
+      # @param chunk_size [ Integer ] the size of each chunk to read from the
+      # file
+      # @param filename [ String, nil ] optional filename to associate with the
+      # enumerator
+      # @param content_proc [ Proc ] a block that generates file content
+      # @return [ Enumerator ] an enumerator that yields file chunks,
+      # eventually having #filename defined as the parameter filename.
       def initialize(chunk_size: 2 ** 16, filename: nil, &content_proc)
         content_proc or raise ArgumentError, 'need a content proc as block argument'
         super() do |y|

data/lib/tins/terminal.rb

@@ -4,10 +4,20 @@ rescue LoadError
 end
 
 module Tins
+  # A module for handling terminal-related functionality and terminal
+  # input/output operations.
+  #
+  # Provides methods for interacting with terminal capabilities, reading from
+  # standard input, and managing terminal sessions.
   module Terminal
-
-    module_function
-
+    # Returns the window size of the console.
+    #
+    # This method attempts to retrieve the terminal window dimensions by
+    # accessing the console object and its winsize method.
+    #
+    # @return [ Array<Integer> ] an array containing the rows and columns
+    #   of the terminal window, or an empty array if the console is not
+    #   available or does not support winsize querying
     def winsize
       if IO.respond_to?(:console)
         c = IO.console
@@ -21,22 +31,34 @@ module Tins
       end
     end
 
+    # Returns the number of rows (lines) in the terminal window.
+    #
+    # Attempts to determine the terminal size by checking various sources in
+    # order of preference: window size, stty command output, tput command
+    # output, and defaults to 25 lines if all methods fail.
+    #
+    # @return [ Integer ] the number of terminal rows, or 25 as fallback
     def rows
       winsize[0] || `stty size 2>/dev/null`.split[0].to_i.nonzero? ||
         `tput lines 2>/dev/null`.to_i.nonzero? || 25
     end
 
-    def lines
-      rows
-    end
+    alias lines rows
 
+    # Returns the number of columns in the terminal
+    #
+    # This method attempts to determine the terminal width by checking various sources
+    # in order of preference: system winsize information, stty output, tput output,
+    # and falls back to a default of 80 columns if none are available
+    #
+    # @return [Integer] the number of columns in the terminal or 80 as fallback
     def columns
       winsize[1] || `stty size 2>/dev/null`.split[1].to_i.nonzero? ||
         `tput cols 2>/dev/null`.to_i.nonzero? || 80
     end
 
-    def cols
-      columns
-    end
+    alias cols columns
+
+    extend self
   end
 end

data/lib/tins/thread_local.rb

@@ -1,5 +1,39 @@
 module Tins
+  # Provides thread-local storage capabilities for classes and modules.
+  # Thread-local variables are scoped to individual threads, allowing each
+  # thread to maintain its own copy of the variable value.
+  #
+  # @example Basic usage with a class
+  #   class MyClass
+  #     extend Tins::ThreadLocal
+  #
+  #     thread_local :counter, 0
+  #     thread_local :name, "default"
+  #   end
+  #
+  #   # Each thread gets its own copy of the variables
+  #   t1 = Thread.new { puts MyClass.new.counter }  # => 0
+  #   t2 = Thread.new { puts MyClass.new.counter }  # => 0
+  #   t1.join; t2.join
+  #
+  # @example Usage with default blocks
+  #   class Config
+  #     extend Tins::ThreadLocal
+  #
+  #     thread_local :database_url do
+  #       ENV['DATABASE_URL'] || 'sqlite3://default.db'
+  #     end
+  #   end
+  #
+  # @example Instance-level thread local variables
+  #   class MyClass
+  #     include Tins::ThreadLocal
+  #
+  #     instance_thread_local :user_id, 0
+  #   end
   module ThreadLocal
+    # Cleanup lambda that removes thread-local data when objects are garbage
+    # collected
     @@cleanup = lambda do |my_object_id|
       my_id = "__thread_local_#{my_object_id}__"
       for t in Thread.list
@@ -7,13 +41,28 @@ module Tins
       end
     end
 
-    # Define a thread local variable named _name_ in this module/class. If the
-    # value _value_ is given, it is used to initialize the variable.
+    # Define a thread local variable named +name+ in this module/class.
+    # If the value +value+ is given, it is used to initialize the variable.
+    #
+    # @param name [Symbol, String] The name of the thread-local variable
+    # @param default_value [Object] Optional default value for the variable
+    # @yield [void] Optional block that returns the default value
+    # @return [self]
+    # @raise [TypeError] If receiver is not a Module
+    # @raise [ArgumentError] If both default_value and default block are provided
+    #
+    # @example With static default value
+    #   thread_local :counter, 0
+    #
+    # @example With dynamic default value via block
+    #   thread_local :timestamp do
+    #     Time.now
+    #   end
     def thread_local(name, default_value = nil, &default)
       is_a?(Module) or raise TypeError, "receiver has to be a Module"
 
       default_value && default and raise ArgumentError,
-        "require either default_falue or default block"
+        "require either default_value or default block"
 
       if default_value
         default = -> * { default_value }
@@ -40,13 +89,26 @@ module Tins
       self
     end
 
-    # Define a thread local variable for the current instance with name _name_.
-    # If the value _value_ is given, it is used to initialize the variable.
+    # Define a thread local variable for the current instance with name +name+.
+    # If the value +value+ is given, it is used to initialize the variable.
+    #
+    # @param name [Symbol, String] The name of the thread-local variable
+    # @param default_value [Object] Optional default value for the variable
+    # @yield [void] Optional block that returns the default value
+    # @return [self]
+    #
+    # @example Basic usage
+    #   class MyClass
+    #     include Tins::ThreadLocal
+    #
+    #     instance_thread_local :user_id, 0
+    #   end
     def instance_thread_local(name, default_value = nil, &default)
       class << self
         extend Tins::ThreadLocal
         self
       end.thread_local name, default_value, &default
+
       self
     end
   end