tins 1.32.0 → 1.44.0

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,36 +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,15 +4,25 @@ 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)
-        console = IO.console
-        if console.respond_to?(:winsize)
-          console.winsize
+        c = IO.console
+        if c.respond_to?(:winsize)
+          c.winsize
         else
           []
         end
@@ -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,23 +1,68 @@
 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
-    @@mutex = Mutex.new
-
+    # 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}__"
-      @@mutex.synchronize do
-        for t in Thread.list
-          t[my_id] = nil if t[my_id]
-        end
+      for t in Thread.list
+        t[my_id] = nil if t[my_id]
       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 }
@@ -44,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

data/lib/tins/time_dummy.rb

@@ -1,7 +1,23 @@
+require 'tins/string_version'
 require 'time'
 
 module Tins
+  # A module that provides time dummy functionality for testing and development
+  # purposes.
+  #
+  # This module allows setting a fake current time that can be used in tests or
+  # development environments where you want to control the time returned by
+  # Time.now.
   module TimeDummy
+    # The included method is a hook that gets called when this module is
+    # included in another class or module.
+    #
+    # It sets up time freezing functionality by extending the including
+    # class/module with special time handling methods. The method modifies the
+    # including class/module's singleton class to provide dummy time
+    # capabilities.
+    #
+    # @param modul [Object] the class or module that includes this module
     def self.included(modul)
       class << modul
         alias really_new new
@@ -10,6 +26,12 @@ module Tins
         remove_method :now rescue nil
         remove_method :new rescue nil
 
+        # Sets the dummy time value for time freezing functionality.
+        #
+        # This method allows setting a specific time value that will be used
+        # as the frozen time when time freezing is enabled.
+        #
+        # @param value [Time, String] the time value to set as dummy
         def dummy=(value)
           if value.respond_to?(:to_str)
             value = Time.parse(value.to_str)
@@ -19,6 +41,12 @@ module Tins
           @dummy = value
         end
 
+        # The dummy method manages a dummy value for testing purposes.
+        #
+        # @param value [Object] the dummy value to set, or nil to get the current value
+        # @return [Object] the current dummy value when value is nil
+        # @yield [] executes the block with the dummy value set
+        # @return [Object] the return value of the block if a block is given
         def dummy(value = nil)
           if value.nil?
             if defined?(@dummy)
@@ -35,28 +63,28 @@ module Tins
           end
         end
 
-        if RUBY_VERSION >= "3.0"
-          def new(*a, **kw)
-            if dummy
-              dummy.dup
-            elsif caller.first =~ /`now`/
-              really_now(**kw)
-            else
-              really_new(*a, **kw)
-            end
-          end
-        else
-          def new(*a)
-            if dummy
-              dummy.dup
-            elsif caller.first =~ /`now`/
-              really_now
-            else
-              really_new(*a)
-            end
+        # The new method creates a new time instance, either by duplicating
+        # the dummy time or calling the real creation method.
+        #
+        # @param a [ Array ] the arguments to pass to the real creation
+        # method
+        # @param kw [ Hash ] the keyword arguments to pass to the real
+        # creation method
+        #
+        # @return [ Time ] the newly created time instance
+        def new(*a, **kw)
+          if dummy
+            dummy.dup
+          elsif caller.first =~ /`now`/
+            really_now(**kw)
+          else
+            really_new(*a, **kw)
           end
         end
 
+        # The now method returns a new instance of the current class.
+        #
+        # @return [Object] a new instance of the class this method is called on
         def now
           new
         end
@@ -65,5 +93,3 @@ module Tins
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/to.rb

@@ -1,5 +1,20 @@
 module Tins
+  # Provides a simple way to remove common leading whitespace from multi-line
+  # strings, mostly for to(<<-EOT), if require "tins/xt/to". Today you would
+  # probably use <<~EOT in this case.
+  #
+  # Example usage:
+  #   doc = to(<<-EOT)
+  #     hello
+  #       world
+  #     end
+  #   EOT
+  #   # => "hello\n  world\nend"
   module To
+    # Remove common leading whitespace from multi-line strings
+    #
+    # @param string [String] The multi-line string to deindent
+    # @return [String] String with common leading whitespace removed
     def to(string)
       shift_width = (string[/\A\s*/]).size
       string.gsub(/^[^\S\n]{0,#{shift_width}}/, '')