tins 1.32.0 → 1.44.0

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,22 +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_ALPHABET = "0123456789ABCDEF".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
@@ -26,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

data/lib/tins/unit.rb

@@ -1,179 +1,318 @@
 require 'strscan'
 require 'bigdecimal'
 
-module Tins::Unit
-  Prefix = Struct.new(:name, :step, :multiplier, :fraction)
-
-  PREFIX_LC = [
-    '', 'k', 'm', 'g', 't', 'p', 'e', 'z', 'y',
-  ].each_with_index.map { |n, i| Prefix.new(n.freeze, 1000, 1000 ** i, false) }.freeze
-
-  PREFIX_UC = [
-    '', 'K', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y',
-  ].each_with_index.map { |n, i| Prefix.new(n.freeze, 1024, 1024 ** i, false) }.freeze
-
-  PREFIX_F = [
-    '', 'm', 'µ', 'n', 'p', 'f', 'a', 'z', 'y',
-  ].each_with_index.map { |n, i| Prefix.new(n.freeze, 1000, 1000 ** -i, true) }.freeze
-
-  class ParserError < ArgumentError; end
-
-  module_function
-
-  def prefixes(identifier)
-    case identifier
-    when :uppercase, :uc, 1024
-      PREFIX_UC
-    when :lowercase, :lc, 1000
-      PREFIX_LC
-    when :fraction, :f, 0.001
-      PREFIX_F
-    when Array
-      identifier
-    end
-  end
+module Tins
+  # A module for parsing and formatting unit specifications with support for
+  # various prefix types and unit formats.
+  #
+  # @example Basic usage
+  #   Tins::Unit.parse('1.5 GB').round # => 1610612736
+  #   Tins::Unit.format(1610612736, unit: 'B') # => "1.500000 GB"
+  #   Tins::Unit.parse('1000 mb', prefix: 1000).round # => 1000000000
+  module Unit
+    # A simple data structure representing a unit prefix with name, scaling step,
+    # multiplier, and fraction flag.
+    Prefix = Struct.new(:name, :step, :multiplier, :fraction)
 
-  def format(value, format: '%f %U', prefix: 1024, unit: ?b)
-    prefixes = prefixes(prefix)
-    first_prefix = prefixes.first or
-      raise ArgumentError, 'a non-empty array of prefixes is required'
-    if value.zero?
-      result = format.sub('%U', unit)
-      result %= value
-    else
-      prefix = prefixes[
-        (first_prefix.fraction ? -1 : 1) * Math.log(value.abs) / Math.log(first_prefix.step)
-      ]
-      result = format.sub('%U', "#{prefix.name}#{unit}")
-      result %= (value / prefix.multiplier.to_f)
-    end
-  end
+    # An array of prefix objects for lowercase decimal prefixes (k, M, G...)
+    # based on 1000-step increments.
+    PREFIX_LC = [
+      '', 'k', 'm', 'g', 't', 'p', 'e', 'z', 'y',
+    ].each_with_index.map { |n, i| Prefix.new(n.freeze, 1000, 1000 ** i, false) }.freeze
 
-  class UnitParser < StringScanner
-    NUMBER = /([+-]?
-               (?:0|[1-9]\d*)
-               (?:
-                 \.\d+(?i:e[+-]?\d+) |
-                 \.\d+ |
-                 (?i:e[+-]?\d+)
-               )?
-             )/x
-
-    def initialize(source, unit, prefixes = nil)
-      super source
-      if prefixes
-        @unit_re    = unit_re(Tins::Unit.prefixes(prefixes), unit)
-        @unit_lc_re = @unit_uc_re = nil
-      else
-        @unit_lc_re = unit_re(Tins::Unit.prefixes(:lc), unit)
-        @unit_uc_re = unit_re(Tins::Unit.prefixes(:uc), unit)
-        @unit_re    = nil
+    # An array of prefix objects for uppercase binary prefixes (K, M, G...) based
+    # on 1024-step increments.
+    PREFIX_UC = [
+      '', 'K', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y',
+    ].each_with_index.map { |n, i| Prefix.new(n.freeze, 1024, 1024 ** i, false) }.freeze
+
+    # An array of prefix objects for fractional prefixes (m, µ, n...) based on
+    # 1000-step decrements.
+    PREFIX_F = [
+      '', 'm', 'µ', 'n', 'p', 'f', 'a', 'z', 'y',
+    ].each_with_index.map { |n, i| Prefix.new(n.freeze, 1000, 1000 ** -i, true) }.freeze
+
+    # A custom exception class for parser errors that inherits from ArgumentError
+    class ParserError < ArgumentError; end
+
+    module_function
+
+    # The prefixes method returns an array of prefix objects based on the given
+    # identifier.
+    #
+    # This method maps different identifier symbols and values to predefined
+    # arrays of prefix objects, allowing for flexible configuration of unit
+    # prefixes.
+    #
+    # @param identifier [Symbol, Integer, Array] the identifier specifying which
+    #   prefix set to return
+    # @return [Array] an array of prefix objects corresponding to the identifier
+    def prefixes(identifier)
+      case identifier
+      when :uppercase, :uc, 1024
+        PREFIX_UC
+      when :lowercase, :lc, 1000
+        PREFIX_LC
+      when :fraction, :f, 0.001
+        PREFIX_F
+      when Array
+        identifier
       end
-      @number       = 1.0
     end
 
-    def unit_re(prefixes, unit)
-      re = Regexp.new(
-        "(#{prefixes.reverse.map { |pre| Regexp.quote(pre.name) } * ?|})(#{unit})"
-      )
-      re.singleton_class.class_eval do
-        define_method(:prefixes) { prefixes }
+    # Format a value using unit prefixes and a specified format template.
+    #
+    # This method takes a numerical value and formats it according to the given
+    # format string, inserting the appropriate unit prefix based on the specified
+    # prefix type and unit identifier.
+    #
+    # @param value [Numeric] the numerical value to format
+    # @param format [String] the format template to use for output, default is '%f %U'
+    # @param prefix [Object] the prefix configuration to use, default is 1024 (binary prefixes)
+    # @param unit [String, Symbol] the unit identifier to append, default is ?b (bytes)
+    def format(value, format: '%f %U', prefix: 1024, unit: ?b)
+      prefixes = prefixes(prefix)
+      first_prefix = prefixes.first or
+        raise ArgumentError, 'a non-empty array of prefixes is required'
+      if value.zero?
+        result = format.sub('%U', unit)
+        result %= value
+      else
+        prefix = prefixes[
+          (first_prefix.fraction ? -1 : 1) * Math.log(value.abs) / Math.log(first_prefix.step)
+        ]
+        result = format.sub('%U', "#{prefix.name}#{unit}")
+        result %= (value / prefix.multiplier.to_f)
       end
-      re
     end
 
-    private :unit_re
+    # A parser for unit specifications that extends StringScanner
+    #
+    # This class is responsible for parsing strings that contain numerical values
+    # followed by unit specifications, supporting various prefix types and unit
+    # formats for flexible unit parsing.
+    class UnitParser < StringScanner
+      # A regular expression matching a number.
+      NUMBER = /([+-]?
+                 (?:0|[1-9]\d*)
+                 (?:
+                  \.\d+(?i:e[+-]?\d+) |
+                 \.\d+ |
+                 (?i:e[+-]?\d+)
+                 )?
+                )/x
 
-    attr_reader :number
+                 # The initialize method sets up a new UnitParser instance with the given
+                 # source string, unit identifier, and optional prefixes configuration.
+                 #
+                 # @param source [String] the input string to parse for units
+                 # @param unit [String, Symbol] the unit identifier to look for in the source
+                 # @param prefixes [Object, nil] optional prefixes configuration (can be array or symbol)
+                 # @return [UnitParser] a new UnitParser instance configured with the provided parameters
+                 def initialize(source, unit, prefixes = nil)
+                   super source
+                   if prefixes
+                     @unit_re    = unit_re(Tins::Unit.prefixes(prefixes), unit)
+                     @unit_lc_re = @unit_uc_re = nil
+                   else
+                     @unit_lc_re = unit_re(Tins::Unit.prefixes(:lc), unit)
+                     @unit_uc_re = unit_re(Tins::Unit.prefixes(:uc), unit)
+                     @unit_re    = nil
+                   end
+                   @number       = 1.0
+                 end
 
-    def scan(re)
-      re.nil? and return
-      super
-    end
+                 # The unit_re method creates a regular expression for matching units with
+                 # prefixes
+                 #
+                 # This method constructs a regular expression pattern that can match unit
+                 # strings including their associated prefixes, which is useful for parsing
+                 # formatted unit specifications in text.
+                 #
+                 # @param prefixes [Array] an array of prefix objects with name attributes
+                 # @param unit [String] the base unit string to match against
+                 #
+                 # @return [Regexp] a regular expression object that can match prefixed units
+                 def unit_re(prefixes, unit)
+                   re = Regexp.new(
+                     "(#{prefixes.reverse.map { |pre| Regexp.quote(pre.name) } * ?|})(#{unit})"
+                   )
+                   re.singleton_class.class_eval do
+                     define_method(:prefixes) { prefixes }
+                   end
+                   re
+                 end
 
-    def scan_number
-      scan(NUMBER) or return
-      @number *= BigDecimal(self[1])
-    end
+                 private :unit_re
 
-    def scan_unit
-      case
-      when scan(@unit_re)
-        prefix = @unit_re.prefixes.find { |pre| pre.name == self[1] } or return
-        @number *= prefix.multiplier
-      when scan(@unit_lc_re)
-        prefix = @unit_lc_re.prefixes.find { |pre| pre.name == self[1] } or return
-        @number *= prefix.multiplier
-      when scan(@unit_uc_re)
-        prefix = @unit_uc_re.prefixes.find { |pre| pre.name == self[1] } or return
-        @number *= prefix.multiplier
-      end
-    end
+                 # The number reader method returns the value of the number attribute.
+                 #
+                 # @return [Object] the current value of the number attribute
+                 attr_reader :number
 
-    def scan_char(char)
-      scan(/#{char}/) or return
-    end
+                 # The scan method scans a regular expression against the current string
+                 # scanner state.
+                 #
+                 # This method delegates to the parent StringScanner's scan method, but
+                 # includes a guard clause to return early if the provided regular
+                 # expression is nil.
+                 #
+                 # @param re [Regexp, nil] the regular expression to scan for
+                 # @return [String, nil] the matched string if found, or nil if no match
+                 def scan(re)
+                   re.nil? and return
+                   super
+                 end
 
-    def parse
-      raise NotImplementedError
-    end
-  end
+                 # The scan_number method parses a number from the current string scanner
+                 # state and multiplies the internal number value by it.
+                 def scan_number
+                   scan(NUMBER) or return
+                   @number *= BigDecimal(self[1])
+                 end
 
-  class FormatParser < StringScanner
-    def initialize(format, unit_parser)
-      super format
-      @unit_parser = unit_parser
-    end
+                 # The scan_unit method attempts to match unit patterns against the current
+                 # string and updates the internal number value by multiplying it with the
+                 # corresponding prefix multiplier
+                 def scan_unit
+                   case
+                   when scan(@unit_re)
+                     prefix = @unit_re.prefixes.find { |pre| pre.name == self[1] } or return
+                     @number *= prefix.multiplier
+                   when scan(@unit_lc_re)
+                     prefix = @unit_lc_re.prefixes.find { |pre| pre.name == self[1] } or return
+                     @number *= prefix.multiplier
+                   when scan(@unit_uc_re)
+                     prefix = @unit_uc_re.prefixes.find { |pre| pre.name == self[1] } or return
+                     @number *= prefix.multiplier
+                   end
+                 end
 
-    def reset
-      super
-      @unit_parser.reset
-    end
+                 # The scan_char method attempts to match a character pattern against the
+                 # current string scanner state.
+                 #
+                 # @param char [String] the character to scan for
+                 # @return [String, nil] the matched string if found, or nil if no match
+                 def scan_char(char)
+                   scan(/#{char}/) or return
+                 end
 
-    def location
-      @unit_parser.peek(10).inspect
+                 # The parse method is intended to be overridden by subclasses to provide
+                 # specific parsing functionality.
+                 #
+                 # @return [Object] the parsed result
+                 def parse
+                   raise NotImplementedError
+                 end
     end
 
-    private :location
-
-    def parse
-      reset
-      until eos? || @unit_parser.eos?
-        case
-        when scan(/%f/)
-          @unit_parser.scan_number or
-            raise ParserError, "\"%f\" expected at #{location}"
-        when scan(/%U/)
-          @unit_parser.scan_unit or
-            raise ParserError, "\"%U\" expected at #{location}"
-        when scan(/%%/)
-          @unit_parser.scan_char(?%) or
-            raise ParserError, "#{?%.inspect} expected at #{location}"
-        else
-          char = scan(/./)
-          @unit_parser.scan_char(char) or
-            raise ParserError, "#{char.inspect} expected at #{location}"
-        end
+    # A parser for unit specifications that extends StringScanner
+    #
+    # This class is responsible for parsing strings that contain numerical values
+    # followed by unit specifications, supporting various prefix types and unit
+    # formats for flexible unit parsing.
+    class FormatParser < StringScanner
+
+      # The initialize method sets up a new UnitParser instance with the given
+      # format and unit parser.
+      #
+      # @param format [String] the format string to use for parsing
+      # @param unit_parser [Tins::Unit::UnitParser] the unit parser to use for
+      # parsing units
+      # @return [Tins::Unit::FormatParser] a new FormatParser instance configured
+      # with the provided parameters
+      def initialize(format, unit_parser)
+        super format
+        @unit_parser = unit_parser
+      end
+
+      # The reset method resets the unit parser state.
+      #
+      # This method calls the superclass reset implementation and then resets
+      # the internal unit parser instance to its initial state.
+      def reset
+        super
+        @unit_parser.reset
+      end
+
+      # The location method returns a string representation of the current
+      # parsing position by peeking at the next 10 characters from the unit
+      # parser and inspecting them
+      # @return [String] the inspected representation of the next 10 characters from the parser
+      # @private
+      def location
+        @unit_parser.peek(10).inspect
       end
-      unless eos? && @unit_parser.eos?
-        raise ParserError,
-          "format #{string.inspect} and string "\
+
+      private :location
+
+      # The parse method parses a format string using a unit parser and returns
+      # the parsed number.
+      #
+      # This method processes a format template by scanning for specific pattern directives
+      # (%f for numbers, %U for units, %% for literal percent signs) and validates that
+      # the input string matches the expected format. It handles parsing errors by raising
+      # ParserError exceptions with descriptive messages about mismatches.
+      #
+      # @return [Float] the parsed numerical value with units applied
+      # @raise [ParserError] if the format string or input string doesn't match the expected pattern
+      # @raise [ParserError] if a required number or unit is missing at a specific location
+      # @raise [ParserError] if literal percent signs don't match expected positions
+      def parse
+        reset
+        until eos? || @unit_parser.eos?
+          case
+          when scan(/%f/)
+            @unit_parser.scan_number or
+              raise ParserError, "\"%f\" expected at #{location}"
+          when scan(/%U/)
+            @unit_parser.scan_unit or
+              raise ParserError, "\"%U\" expected at #{location}"
+          when scan(/%%/)
+            @unit_parser.scan_char(?%) or
+              raise ParserError, "#{?%.inspect} expected at #{location}"
+          else
+            char = scan(/./)
+            @unit_parser.scan_char(char) or
+              raise ParserError, "#{char.inspect} expected at #{location}"
+          end
+        end
+        unless eos? && @unit_parser.eos?
+          raise ParserError,
+            "format #{string.inspect} and string "\
             "#{@unit_parser.string.inspect} do not match"
+        end
+        @unit_parser.number
       end
-      @unit_parser.number
     end
-  end
 
-  # Parse the string +string+ if it matches +format+ with the unit +unit+ and
-  # the prefixes specified by +prefix+.
-  def parse(string, format: '%f %U', unit: ?b, prefix: nil)
-    prefixes = prefixes(prefix)
-    FormatParser.new(format, UnitParser.new(string, unit, prefixes)).parse
-  end
+    # Parse the string using the specified format and unit information
+    #
+    # This method takes a string and parses it according to a given format template,
+    # extracting numerical values and their associated units. It supports various
+    # prefix types and unit specifications for flexible parsing.
+    #
+    # @param string [String] the input string to parse
+    # @param format [String] the format template to use for parsing (default: '%f %U')
+    # @param unit [String, Symbol] the unit identifier to use (default: ?b)
+    # @param prefix [Object] the prefix configuration to use (default: nil)
+    #
+    # @return [Object] the parsed result based on the format and unit specifications
+    def parse(string, format: '%f %U', unit: ?b, prefix: nil)
+      prefixes = prefixes(prefix)
+      FormatParser.new(format, UnitParser.new(string, unit, prefixes)).parse
+    end
 
-  def parse?(string, **options)
-    parse(string, **options)
-  rescue ParserError
-    nil
+    # The parse? method attempts to parse a string using the specified options
+    # and returns nil if parsing fails.
+    #
+    # @param string [String] the string to parse
+    # @param options [Hash] the options to pass to the parse method
+    # @return [Object, nil] the parsed result or nil if parsing fails
+    def parse?(string, **options)
+      parse(string, **options)
+    rescue ParserError
+      nil
+    end
   end
 end

data/lib/tins/version.rb

@@ -1,6 +1,6 @@
 module Tins
   # Tins version
-  VERSION         = '1.32.0'
+  VERSION         = '1.44.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/lib/tins/write.rb

@@ -1,11 +1,24 @@
 require 'tins/secure_write'
 
 module Tins
+  # Tins::Write provides secure write functionality that can be extended onto
+  # modules/classes to add a `write` method.
+  #
+  # When a module is extended with Tins::Write, it will:
+  # - Extend the module with SecureWrite methods
+  # - Conditionally alias `secure_write` to `write` if no existing `write` method exists
+  # - Issue a warning if `write` already exists (when $DEBUG is enabled)
   module Write
+    # Called when Tins::Write is extended onto a module.
+    # Extends the receiving module with SecureWrite functionality
+    # and conditionally aliases secure_write to write.
+    #
+    # @param modul [Module] The module being extended
     def self.extended(modul)
       modul.extend SecureWrite
       if modul.respond_to?(:write)
-        $DEBUG and warn "Skipping inclusion of Tins::Write#write method, include Tins::Write::SecureWrite#secure_write instead"
+        $DEBUG and warn "Skipping inclusion of Tins::Write#write method, "\
+          "include Tins::Write::SecureWrite#secure_write instead"
       else
         class << modul; self; end.instance_eval do
           alias_method :write, :secure_write
@@ -15,5 +28,3 @@ module Tins
     end
   end
 end
-
-require 'tins/alias'