tins 1.43.0 → 1.44.0

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
@@ -30,11 +82,14 @@ module Tins
         length = (Math.log(1 << bits) / Math.log(alphabet.size)).ceil
       end
       self.bits = (Math.log(alphabet.size ** length) / Math.log(2)).floor
-      token = ''
+      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
   end
 end