tins 1.38.0 → 1.51.0

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

data/lib/tins/time_dummy.rb

@@ -2,7 +2,22 @@ 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
@@ -11,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)
@@ -20,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)
@@ -36,28 +63,28 @@ module Tins
           end
         end
 
-        if Tins::StringVersion.compare(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
@@ -66,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}}/, '')

data/lib/tins/to_proc.rb

@@ -1,12 +1,25 @@
 module Tins
+  # This module provides a way to convert symbols into procs using the
+  # __send__ method for dynamic method invocation. It was necessary before
+  # Ruby 1.9's built-in Symbol#to_proc functionality. You still can use
+  # it for strings, though.
+  #
+  # Example Usage:
+  #   class String
+  #     include Tins::ToProc
+  #   end
+  #
+  #   ["hello", "world"].map(&'upcase')  # => ["HELLO", "WORLD"]
   module ToProc
-    # :nocov:
+    # Converts a Symbol into a Proc that sends the symbol's name to its
+    # argument
+    #
+    # @return [ Proc ] a Proc that when called will send the symbol's name as a
+    # message to obj with args
     def to_proc
       lambda do |obj, *args|
-        obj.__send__(self, *args[0..-1])
+        obj.__send__(self, *args)
       end
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/token.rb

@@ -1,26 +1,78 @@
 require 'securerandom'
 
 module Tins
+  # A secure token generator that creates cryptographically safe strings
+  # using customizable alphabets and random number generators.
+  #
+  # @example Basic usage
+  #   token = Tins::Token.new
+  #   # => "aB3xK9mN2pQ8rS4tU6vW7yZ1"
+  #
+  # @example Custom length
+  #   token = Tins::Token.new(length: 20)
+  #   # => "xYz123AbC456DeF789GhI0jK"
+  #
+  # @example Custom alphabet
+  #   token = Tins::Token.new(
+  #     alphabet: Tins::Token::BASE16_UPPERCASE_ALPHABET,
+  #     length: 16
+  #   )
+  #   # => "A1B2C3D4E5F6G7H8"
+  #
+  # @example Custom random number generator
+  #   token = Tins::Token.new(random: Random.new(42))
+  #   # => "xYz123AbC456DeF789GhI0jK"
   class Token < String
+    # Default alphabet for token generation
     DEFAULT_ALPHABET =
       "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ".freeze
 
+    # Base64 alphabet
     BASE64_ALPHABET =
       "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/".freeze
 
+    # URL-safe base64 alphabet
     BASE64_URL_FILENAME_SAFE_ALPHABET =
       "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_".freeze
 
+    # Base32 alphabet
     BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567".freeze
 
+    # Extended hex base32 alphabet
     BASE32_EXTENDED_HEX_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUV".freeze
 
+    # Base16 uppercase alphabet
     BASE16_UPPERCASE_ALPHABET = "0123456789ABCDEF".freeze
 
+    # Base16 lowercase alphabet
     BASE16_LOWERCASE_ALPHABET = "0123456789abcdef".freeze
 
+    # Base16 default alphabet (uppercase)
     BASE16_ALPHABET = BASE16_UPPERCASE_ALPHABET
 
+    # Initializes a new Token instance with specified bit length, length,
+    # alphabet, and random number generator.
+    #
+    # @example Basic initialization
+    #   token = Tins::Token.new
+    #   # => "aB3xK9mN2pQ8rS4tU6vW7yZ1"
+    #
+    # @example Custom parameters
+    #   token = Tins::Token.new(
+    #     bits: 256,
+    #     alphabet: Tins::Token::BASE32_ALPHABET
+    #   )
+    #
+    # @param bits [Integer] the number of bits for the token (default: 128)
+    # @param length [Integer] the length of the token (optional, mutually exclusive with bits)
+    # @param alphabet [String] the alphabet to use for token generation (default: DEFAULT_ALPHABET)
+    # @param random [Object] the random number generator to use (default: SecureRandom)
+    #
+    # @return [Tins::Token] a new Token instance
+    #
+    # @raise [ArgumentError] if alphabet has fewer than 2 symbols
+    # @raise [ArgumentError] if bits is not positive when length is not specified
+    # @raise [ArgumentError] if length is not positive when specified
     def initialize(bits: 128, length: nil, alphabet: DEFAULT_ALPHABET, random: SecureRandom)
       alphabet.size > 1 or raise ArgumentError, 'need at least 2 symbols in alphabet'
       if length
@@ -29,12 +81,32 @@ module Tins
         bits > 0 or raise ArgumentError, 'bits has to be positive'
         length = (Math.log(1 << bits) / Math.log(alphabet.size)).ceil
       end
-      self.bits = (Math.log(alphabet.size ** length) / Math.log(2)).floor
-      token = ''
+      self.bits = self.class.analyze(alphabet:, length:)
+      token = +''
       length.times { token << alphabet[random.random_number(alphabet.size)] }
       super token
     end
 
+    # The bit length of the token.
+    #
+    # @return [Integer] the number of bits of entropy in the token
     attr_accessor :bits
+
+    # The analyze method calculates the bit length of a token based on its
+    # alphabet and length.
+    #
+    # @param alphabet [String] the alphabet used for token generation, defaults
+    #   to Tins::Token::DEFAULT_ALPHABET
+    # @param token [String, nil] the token string to analyze, optional
+    # @param length [Integer, nil] the length of the token, optional
+    #
+    # @return [Integer] the calculated bit length of the token
+    #
+    # @raise [ArgumentError] if neither token nor length is provided, or if both are provided
+    def self.analyze(alphabet: Tins::Token::DEFAULT_ALPHABET, token: nil, length: nil)
+      token.nil? ^ length.nil? or raise ArgumentError, 'either token or length is required'
+      length ||= token.length
+      (Math.log(alphabet.size ** length) / Math.log(2)).floor
+    end
   end
 end