sleeping_king_studios-tools 0.7.0.beta.0 → 0.8.0

data/lib/sleeping_king_studios/tools/base.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require 'sleeping_king_studios/tools'
+
+module SleepingKingStudios::Tools
+  # Abstract base class for Tools classes.
+  class Base
+    class << self
+      extend Forwardable
+    end
+
+    def self.instance
+      @instance ||= new
+    end
+  end
+end

data/lib/sleeping_king_studios/tools/core_tools.rb

@@ -1,11 +1,26 @@
-# lib/sleeping_king_studios/tools/core_tools.rb
+# frozen_string_literal: true
 
 require 'sleeping_king_studios/tools'
 
 module SleepingKingStudios::Tools
   # Tools for working with an application or working environment.
-  module CoreTools
-    extend self
+  class CoreTools < Base
+    class DeprecationError < StandardError; end
+
+    class << self
+      def_delegators :instance,
+        :deprecate,
+        :empty_binding,
+        :require_each
+    end
+
+    def initialize(deprecation_strategy: nil)
+      @deprecation_strategy =
+        deprecation_strategy || ENV.fetch('DEPRECATION_STRATEGY', 'warn')
+    end
+
+    # @return [String] The current deprecation strategy.
+    attr_reader :deprecation_strategy
 
     # @overload deprecate(name, message: nil)
     #   Prints a deprecation warning.
@@ -22,30 +37,74 @@ module SleepingKingStudios::Tools
     #   @param format [String] The format string.
     #   @param message [String] An optional message to print after the formatted
     #     string. Defaults to nil.
-    def deprecate *args, format: nil, message: nil
-      format ||= "[WARNING] %s has been deprecated."
+    def deprecate(*args, format: nil, message: nil)
+      send(
+        :"deprecate_as_#{deprecation_strategy}",
+        *args,
+        format:  format,
+        message: message
+      )
+    end
 
-      str = format % args
-      str << ' ' << message if message
+    # Generates an empty Binding object with a BasicObject as the receiver.
+    #
+    # @return [Binding] The empty binding object.
+    def empty_binding
+      context = Object.new
 
-      str << "\n  called from #{caller[1]}"
+      def context.binding
+        Kernel.instance_method(:binding).bind(self).call
+      end
 
-      Kernel.warn str
-    end # method deprecate
+      context.binding
+    end
 
     # Expands each file pattern and requires each file.
     #
     # @param file_patterns [Array] The files to require.
-    def require_each *file_patterns
+    def require_each(*file_patterns)
       file_patterns.each do |file_pattern|
         if file_pattern.include?('*')
           Dir[file_pattern].each do |file_name|
             Kernel.require file_name
-          end # each
+          end
         else
           Kernel.require file_pattern
-        end # unless
-      end # each
-    end # method require_each
-  end # module
-end # module
+        end
+      end
+    end
+
+    private
+
+    def deprecate_as_ignore(*_args, **_kwargs); end
+
+    def deprecate_as_raise(*args, format: nil, message: nil)
+      format ||= '%s has been deprecated.'
+
+      str = format % args
+      str << ' ' << message if message
+
+      raise DeprecationError, str, caller(2..-1)
+    end
+
+    def deprecate_as_warn(*args, format: nil, message: nil)
+      format ||= '[WARNING] %s has been deprecated.'
+
+      str = format % args
+      str << ' ' << message if message
+
+      str << "\n  called from #{external_caller}"
+
+      Kernel.warn str
+    end
+
+    def external_caller
+      caller.find do |line|
+        !(
+          line.include?('forwardable.rb') ||
+          line.include?('sleeping_king_studios-tools')
+        )
+      end
+    end
+  end
+end

data/lib/sleeping_king_studios/tools/enumerable_tools.rb

@@ -1,8 +1,11 @@
-# lib/sleeping_king_studios/tools/enumerable_tools.rb
+# frozen_string_literal: true
 
-require 'sleeping_king_studios/tools/array_tools'
+require 'sleeping_king_studios/tools'
+
+SleepingKingStudios::Tools::CoreTools
+  .deprecate('SleepingKingStudios::Tools::EnumerableTools')
 
 module SleepingKingStudios::Tools
   # Alias for ArrayTools to ensure backward compatibility.
   EnumerableTools = ArrayTools
-end # module
+end

data/lib/sleeping_king_studios/tools/hash_tools.rb

@@ -1,47 +1,58 @@
-# lib/sleeping_king_studios/tools/hash_tools.rb
+# frozen_string_literal: true
 
 require 'sleeping_king_studios/tools'
-require 'sleeping_king_studios/tools/array_tools'
-require 'sleeping_king_studios/tools/object_tools'
 
 module SleepingKingStudios::Tools
   # Tools for working with hash-like enumerable objects.
-  module HashTools
-    extend self
-
-    HASH_METHODS = [:[], :count, :each, :each_key, :each_pair].freeze
+  class HashTools < SleepingKingStudios::Tools::Base
+    HASH_METHODS = %i[[] count each each_key each_pair].freeze
+
+    class << self
+      def_delegators :instance,
+        :convert_keys_to_strings,
+        :convert_keys_to_symbols,
+        :deep_dup,
+        :deep_freeze,
+        :generate_binding,
+        :hash?,
+        :immutable?,
+        :mutable?
+
+      alias stringify_keys convert_keys_to_strings
+      alias symbolize_keys convert_keys_to_symbols
+    end
 
     # Returns a copy of the hash with the keys converted to strings.
     #
     # @param [Hash] hsh The hash to convert.
     #
     # @return [Hash] The converted copy of the hash.
-    def convert_keys_to_strings hsh
+    def convert_keys_to_strings(hsh)
       require_hash! hsh
 
       hsh.each.with_object({}) do |(key, value), cpy|
         sym = key.to_s
 
         cpy[sym] = convert_value_to_stringified_hash(value)
-      end # each
-    end # method convert_keys_to_strings
-    alias_method :stringify_keys, :convert_keys_to_strings
+      end
+    end
+    alias stringify_keys convert_keys_to_strings
 
     # Returns a copy of the hash with the keys converted to symbols.
     #
     # @param [Hash] hsh The hash to convert.
     #
     # @return [Hash] The converted copy of the hash.
-    def convert_keys_to_symbols hsh
+    def convert_keys_to_symbols(hsh)
       require_hash! hsh
 
       hsh.each.with_object({}) do |(key, value), cpy|
         sym = key.to_s.intern
 
         cpy[sym] = convert_value_to_symbolic_hash(value)
-      end # each
-    end # method convert_keys_to_symbols
-    alias_method :symbolize_keys, :convert_keys_to_symbols
+      end
+    end
+    alias symbolize_keys convert_keys_to_symbols
 
     # Creates a deep copy of the object by returning a new Hash with deep
     # copies of each key and value.
@@ -49,19 +60,19 @@ module SleepingKingStudios::Tools
     # @param [Hash<Object>] hsh The hash to copy.
     #
     # @return [Hash] The copy of the hash.
-    def deep_dup hsh
+    def deep_dup(hsh)
       require_hash! hsh
 
-      hsh.each.with_object(Hash.new) do |(key, value), copy|
+      hsh.each.with_object({}) do |(key, value), copy|
         copy[ObjectTools.deep_dup key] = ObjectTools.deep_dup(value)
-      end # each
-    end # method deep_dup
+      end
+    end
 
     # Freezes the hash and performs a deep freeze on each hash key and
     # value.
     #
     # @param [Hash] hsh The object to freeze.
-    def deep_freeze hsh
+    def deep_freeze(hsh)
       require_hash! hsh
 
       hsh.freeze
@@ -69,23 +80,33 @@ module SleepingKingStudios::Tools
       hsh.each do |key, value|
         ObjectTools.deep_freeze key
         ObjectTools.deep_freeze value
-      end # each
-    end # method deep_freeze
+      end
+    end
+
+    def generate_binding(hsh)
+      require_hash! hsh
+
+      CoreTools.empty_binding.tap do |binding|
+        hsh.each do |key, value|
+          binding.local_variable_set key, value
+        end
+      end
+    end
 
     # Returns true if the object is or appears to be a Hash.
     #
     # @param hsh [Object] The object to test.
     #
     # @return [Boolean] True if the object is a Hash, otherwise false.
-    def hash? hsh
-      return true if Hash === hsh
+    def hash?(hsh)
+      return true if hsh.is_a?(Hash)
 
       HASH_METHODS.each do |method_name|
         return false unless hsh.respond_to?(method_name)
-      end # each
+      end
 
       true
-    end # method hash?
+    end
 
     # Returns true if the hash is immutable, i.e. if the hash is frozen and each
     # hash key and hash value are immutable.
@@ -93,17 +114,19 @@ module SleepingKingStudios::Tools
     # @param hsh [Hash] The hash to test.
     #
     # @return [Boolean] True if the hash is immutable, otherwise false.
-    def immutable? hsh
+    def immutable?(hsh)
       require_hash! hsh
 
       return false unless hsh.frozen?
 
       hsh.each do |key, value|
-        return false unless ObjectTools.immutable?(key) && ObjectTools.immutable?(value)
-      end # each
+        unless ObjectTools.immutable?(key) && ObjectTools.immutable?(value)
+          return false
+        end
+      end
 
       true
-    end # method immutable
+    end
 
     # Returns true if the hash is mutable.
     #
@@ -112,36 +135,36 @@ module SleepingKingStudios::Tools
     # @return [Boolean] True if the hash is mutable, otherwise false.
     #
     # @see #immutable?
-    def mutable? hsh
+    def mutable?(hsh)
       !immutable?(hsh)
-    end # method mutable?
+    end
 
     private
 
-    def convert_value_to_stringified_hash value
+    def convert_value_to_stringified_hash(value)
       if hash?(value)
         convert_keys_to_strings(value)
       elsif ArrayTools.array?(value)
         value.map { |item| convert_value_to_stringified_hash(item) }
       else
         value
-      end # if-else
-    end # method convert_value_to_stringified_hash
+      end
+    end
 
-    def convert_value_to_symbolic_hash value
+    def convert_value_to_symbolic_hash(value)
       if hash?(value)
         convert_keys_to_symbols(value)
       elsif ArrayTools.array?(value)
         value.map { |item| convert_value_to_symbolic_hash(item) }
       else
         value
-      end # if-else
-    end # method convert_value_to_symbolic_hash
+      end
+    end
 
-    def require_hash! value
+    def require_hash!(value)
       return if hash?(value)
 
       raise ArgumentError, 'argument must be a hash', caller[1..-1]
-    end # method require_array
-  end # module
-end # module
+    end
+  end
+end

data/lib/sleeping_king_studios/tools/integer_tools.rb

@@ -1,19 +1,63 @@
-# lib/sleeping_king_studios/tools/integer_tools.rb
+# frozen_string_literal: true
 
 require 'sleeping_king_studios/tools'
-require 'sleeping_king_studios/tools/string_tools'
 
 module SleepingKingStudios::Tools
   # Tools for working with integers.
-  module IntegerTools
-    extend self
-
+  class IntegerTools < SleepingKingStudios::Tools::Base
     # Minimum integer value that can be converted to a roman numeral.
     ROMANIZE_MIN = 1
 
     # Maximum integer value that can be converted to a roman numeral.
     ROMANIZE_MAX = 4999
 
+    ROMANIZE_NUMERALS = [
+      %w[I V X].freeze,
+      %w[X L C].freeze,
+      %w[C D M].freeze,
+      ['M', 'MMM', ''].freeze
+    ].freeze
+    private_constant :ROMANIZE_NUMERALS
+
+    ROMANIZE_RULES = [
+      '',
+      '1',
+      '11',
+      '111',
+      '15',
+      '5',
+      '51',
+      '511',
+      '5111',
+      '1a',
+      'a'
+    ].freeze
+    private_constant :ROMANIZE_RULES
+
+    ROMANIZE_RULES_ADDITIVE = [
+      '',
+      '1',
+      '11',
+      '111',
+      '1111',
+      '5',
+      '51',
+      '511',
+      '5111',
+      '51111',
+      'a'
+    ].freeze
+    private_constant :ROMANIZE_RULES_ADDITIVE
+
+    class << self
+      def_delegators :instance,
+        :count_digits,
+        :digits,
+        :integer?,
+        :pluralize,
+        :romanize
+    end
+
     # Returns the number of digits in the given integer when represented in the
     # specified base. Ignores minus sign for negative numbers.
     #
@@ -38,9 +82,9 @@ module SleepingKingStudios::Tools
     #   Defaults to 10.
     #
     # @return [Integer] The number of digits.
-    def count_digits integer, base: 10
-      digits(integer.abs, :base => base).count
-    end # method count_digits
+    def count_digits(integer, base: 10)
+      digits(integer.abs, base: base).count
+    end
 
     # Decomposes the given integer into its digits when represented in the
     # given base.
@@ -63,18 +107,18 @@ module SleepingKingStudios::Tools
     #
     # @return [Array<String>] The digits of the decomposed integer,
     #   represented as a bigendian array of strings.
-    def digits integer, base: 10
+    def digits(integer, base: 10)
       integer.to_s(base).split('')
-    end # method digits
+    end
 
     # Returns true if the object is an Integer.
     #
     # @param int [Object] The object to test.
     #
     # @return [Boolean] True if the object is an Integer, otherwise false.
-    def integer? int
-      Integer === int
-    end # method integer?
+    def integer?(int)
+      int.is_a?(Integer)
+    end
 
     # Returns the singular or the plural value, depending on the provided
     # item count.
@@ -89,11 +133,11 @@ module SleepingKingStudios::Tools
     #
     # @return [String] The single form if count == 1; otherwise the plural
     #   form.
-    def pluralize count, single, plural = nil
+    def pluralize(count, single, plural = nil)
       plural ||= StringTools.pluralize(single)
 
-      1 == count ? single : plural
-    end # method pluralize
+      count == 1 ? single : plural
+    end
 
     # Represents an integer between 1 and 4999 (inclusive) as a Roman numeral.
     #
@@ -114,42 +158,40 @@ module SleepingKingStudios::Tools
     # @return [String] The representation of the integer as a Roman numeral.
     #
     # @raise [RangeError] If the integer is less than 1 or greater than 4999.
-    def romanize integer, additive: false
-      # Validate input value.
-      unless (ROMANIZE_MIN..ROMANIZE_MAX).include? integer
-        raise RangeError.new "integer to romanize must be within range #{ROMANIZE_MIN} to #{ROMANIZE_MAX}"
-      end # unless
-
-      # Define conversion rules.
-      rules = [
-        '',
-        '%one',
-        '%one%one',
-        '%one%one%one',
-        additive ? '%one%one%one%one' : '%one%five',
-        '%five',
-        '%five%one',
-        '%five%one%one',
-        '%five%one%one%one',
-        additive ? '%five%one%one%one%one' : '%one%ten',
-        '%ten'
-      ] # end array
-
-      # Define numeral values.
-      numerals = [
-        %w(I V X),
-        %w(X L C),
-        %w(C D M),
-        ['M', 'MMM', '']
-      ] # end array numerals
-
-      # Generate string representation.
-      digits(integer).reverse.map.with_index do |digit, index|
-        rules[digit.to_i]
-          .gsub('%one',  numerals[index][0])
-          .gsub('%five', numerals[index][1])
-          .gsub('%ten',  numerals[index][2])
-      end.reverse.join ''
-    end # method romanize
-  end # module
-end # module
+    def romanize(integer, additive: false)
+      check_romanize_range(integer)
+
+      digits(integer)
+        .reverse
+        .map
+        .with_index do |digit, index|
+          romanize_digit(additive: additive, digit: digit.to_i, tens: index)
+        end
+        .reverse
+        .join ''
+    end
+
+    private
+
+    def check_romanize_range(integer)
+      return if (ROMANIZE_MIN..ROMANIZE_MAX).include?(integer)
+
+      error_message =
+        "integer to romanize must be within range #{ROMANIZE_MIN} to" \
+        " #{ROMANIZE_MAX}"
+
+      raise RangeError, error_message, caller(1..-1)
+    end
+
+    def romanize_digit(additive:, digit:, tens:)
+      rules    = (additive ? ROMANIZE_RULES_ADDITIVE : ROMANIZE_RULES)
+      rule     = rules[digit]
+      numerals = ROMANIZE_NUMERALS[tens]
+
+      rule
+        .gsub('1', numerals[0])
+        .gsub('5', numerals[1])
+        .gsub('a', numerals[2])
+    end
+  end
+end