sleeping_king_studios-tools 0.7.0.beta.1 → 1.0.0.rc.0

data/lib/sleeping_king_studios/tools.rb

@@ -1,12 +1,18 @@
-# lib/sleeping_king_studios/tools.rb
+# frozen_string_literal: true
 
 # Hic iacet Arthurus, rex quondam, rexque futurus.
 module SleepingKingStudios
   # A library of utility services and concerns to expand the functionality of
   # core classes without polluting the global namespace.
   module Tools
-    autoload :Toolbelt, 'sleeping_king_studios/tools/toolbelt'
-  end # module
-end # module
-
-require 'sleeping_king_studios/tools/version'
+    autoload :Base,         'sleeping_king_studios/tools/base'
+    autoload :ArrayTools,   'sleeping_king_studios/tools/array_tools'
+    autoload :CoreTools,    'sleeping_king_studios/tools/core_tools'
+    autoload :HashTools,    'sleeping_king_studios/tools/hash_tools'
+    autoload :IntegerTools, 'sleeping_king_studios/tools/integer_tools'
+    autoload :ObjectTools,  'sleeping_king_studios/tools/object_tools'
+    autoload :StringTools,  'sleeping_king_studios/tools/string_tools'
+    autoload :Toolbelt,     'sleeping_king_studios/tools/toolbelt'
+    autoload :Version,      'sleeping_king_studios/tools/version'
+  end
+end

data/lib/sleeping_king_studios/tools/array_tools.rb

@@ -1,34 +1,48 @@
-# lib/sleeping_king_studios/tools/array_tools.rb
+# frozen_string_literal: true
 
 require 'sleeping_king_studios/tools'
-require 'sleeping_king_studios/tools/object_tools'
 
 module SleepingKingStudios::Tools
   # Tools for working with array-like enumerable objects.
-  module ArrayTools
-    extend self
-
-    ARRAY_METHODS = [:[], :count, :each].freeze
-    OTHER_METHODS = [:each_key, :each_pair].freeze
+  class ArrayTools < SleepingKingStudios::Tools::Base
+    # Expected methods that an Array-like object should implement.
+    ARRAY_METHODS = %i[[] count each].freeze
+
+    # Methods that an Array-like object should *not* implement.
+    OTHER_METHODS = %i[each_key each_pair].freeze
+
+    class << self
+      def_delegators :instance,
+        :array?,
+        :bisect,
+        :count_values,
+        :deep_dup,
+        :deep_freeze,
+        :humanize_list,
+        :immutable?,
+        :mutable?,
+        :splice,
+        :tally
+    end
 
     # Returns true if the object is or appears to be an Array.
     #
     # @param ary [Object] The object to test.
     #
     # @return [Boolean] True if the object is an Array, otherwise false.
-    def array? ary
-      return true if Array === ary
+    def array?(ary)
+      return true if ary.is_a?(Array)
 
       ARRAY_METHODS.each do |method_name|
         return false unless ary.respond_to?(method_name)
-      end # each
+      end
 
       OTHER_METHODS.each do |method_name|
         return false if ary.respond_to?(method_name)
-      end # each
+      end
 
       true
-    end # method array?
+    end
 
     # Separates the array into two arrays, the first containing all items in the
     # original array that matches the provided block, and the second containing
@@ -52,19 +66,20 @@ module SleepingKingStudios::Tools
     #   if no block is given.
     #
     # @return [Array<Array<Object>>] An array containing two arrays.
-    def bisect ary, &block
+    def bisect(ary)
       require_array! ary
 
-      raise ArgumentError.new('no block given') unless block_given?
+      raise ArgumentError, 'no block given' unless block_given?
 
-      selected, rejected = [], []
+      selected = []
+      rejected = []
 
       ary.each do |item|
         (yield(item) ? selected : rejected) << item
-      end # each
+      end
 
       [selected, rejected]
-    end # method bisect
+    end
 
     # @overload count_values(ary)
     #   Counts the number of times each value appears in the enumerable object.
@@ -96,15 +111,16 @@ module SleepingKingStudios::Tools
     #
     #   @return [Hash{Object, Integer}] The number of times each result
     #     appears.
-    def count_values ary, &block
+    def count_values(ary, &block)
       require_array! ary
 
       ary.each.with_object({}) do |item, hsh|
         value = block_given? ? block.call(item) : item
 
         hsh[value] = hsh.fetch(value, 0) + 1
-      end # each
-    end # method count_values
+      end
+    end
+    alias tally count_values
 
     # Creates a deep copy of the object by returning a new Array with deep
     # copies of each array item.
@@ -112,22 +128,22 @@ module SleepingKingStudios::Tools
     # @param [Array<Object>] ary The array to copy.
     #
     # @return [Array] The copy of the array.
-    def deep_dup ary
+    def deep_dup(ary)
       require_array! ary
 
       ary.map { |obj| ObjectTools.deep_dup obj }
-    end # method deep_dup
+    end
 
     # Freezes the array and performs a deep freeze on each array item.
     #
     # @param [Array] ary The object to freeze.
-    def deep_freeze ary
+    def deep_freeze(ary)
       require_array! ary
 
       ary.freeze
 
       ary.each { |obj| ObjectTools.deep_freeze obj }
-    end # method deep_freeze
+    end
 
     # Accepts a list of values and returns a human-readable string of the
     # values, with the format based on the number of items.
@@ -149,7 +165,10 @@ module SleepingKingStudios::Tools
     #   #=> 'spam, eggs, bacon, and spam'
     #
     # @example With Three Or More Items And Options
-    #   ArrayTools.humanize_list(['spam', 'eggs', 'bacon', 'spam'], :last_separator => ' or ')
+    #   ArrayTools.humanize_list(
+    #     ['spam', 'eggs', 'bacon', 'spam'],
+    #     :last_separator => ' or '
+    #   )
     #   #=> 'spam, eggs, bacon, or spam'
     #
     # @param [Array<String>] ary The list of values to format. Will be
@@ -166,31 +185,23 @@ module SleepingKingStudios::Tools
     # @raise ArgumentError If the first argument is not an Array-like object.
     #
     # @return [String] The formatted string.
-    def humanize_list ary, options = {}, &block
+    def humanize_list(ary, **options, &block)
       require_array! ary
 
-      ary = ary.map(&block) if block_given?
+      return '' if ary.empty?
 
-      separator = options.fetch(:separator, ', ')
-      last_separator = options.fetch(:last_separator, ' and ')
+      size = ary.size
+      ary  = ary.map(&block) if block_given?
 
-      case ary.count
-      when 0
-        ''
-      when 1
-        ary.first.to_s
-      when 2
-        "#{ary[0]}#{last_separator}#{ary[1]}"
-      else
-        if last_separator =~ /\A,?\s*/
-          last_separator = last_separator.sub /\A,?\s*/, separator
-        else
-          last_separator = "#{separator}#{last_separator}"
-        end # if-else
+      return ary[0].to_s if size == 1
+
+      separator, last_separator =
+        options_for_humanize_list(size: size, **options)
+
+      return "#{ary[0]}#{last_separator}#{ary[1]}" if size == 2
 
-        "#{ary[0...-1].join(separator)}#{last_separator}#{ary.last}"
-      end # case
-    end # method humanize_list
+      "#{ary[0...-1].join(separator)}#{last_separator}#{ary.last}"
+    end
 
     # Returns true if the array is immutable, i.e. the array is frozen and each
     # array item is immutable.
@@ -200,7 +211,7 @@ module SleepingKingStudios::Tools
     # @return [Boolean] True if the array is immutable, otherwise false.
     #
     # @see ObjectTools#immutable?
-    def immutable? ary
+    def immutable?(ary)
       require_array! ary
 
       return false unless ary.frozen?
@@ -208,7 +219,7 @@ module SleepingKingStudios::Tools
       ary.each { |item| return false unless ObjectTools.immutable?(item) }
 
       true
-    end # method immutable?
+    end
 
     # Returns true if the array is mutable.
     #
@@ -217,9 +228,9 @@ module SleepingKingStudios::Tools
     # @return [Boolean] True if the array is mutable, otherwise false.
     #
     # @see #immutable?
-    def mutable? ary
+    def mutable?(ary)
       !immutable?(ary)
-    end # method mutable?
+    end
 
     # Accepts an array, a start value, a number of items to delete, and zero or
     # more items to insert at that index. Deletes the specified number of items,
@@ -235,10 +246,10 @@ module SleepingKingStudios::Tools
     #
     # @example Inserting items into an Array
     #   values = %w(longsword broadsword claymore)
-    #   ArrayTools.splice values, 1, 0, 'zweihänder'
+    #   ArrayTools.splice values, 1, 0, 'zweihander'
     #   #=> []
     #   values
-    #   #=> ['longsword', 'zweihänder', 'broadsword', 'claymore']
+    #   #=> ['longsword', 'zweihander', 'broadsword', 'claymore']
     #
     # @example Inserting and deleting items
     #   values = %w(shortbow longbow crossbow)
@@ -257,24 +268,41 @@ module SleepingKingStudios::Tools
     #
     # @return [Array<Object>] The deleted items, or an empty array if no items
     #   were deleted.
-    def splice ary, start, delete_count, *insert
+    def splice(ary, start, delete_count, *insert)
       require_array! ary
 
-      start   = start < 0 ? start + ary.count : start
+      start   = start.negative? ? start + ary.count : start
       range   = start...(start + delete_count)
       deleted = ary[range]
 
       ary[range] = insert
 
       deleted
-    end # method splice
+    end
 
     private
 
-    def require_array! value
+    def options_for_humanize_list(
+      size:,
+      last_separator: ' and ',
+      separator: ', '
+    )
+      return [separator, last_separator] if size < 3
+
+      last_separator =
+        if last_separator =~ /\A,?\s*/
+          last_separator.sub(/\A,?\s*/, separator)
+        else
+          "#{separator}#{last_separator}"
+        end
+
+      [separator, last_separator]
+    end
+
+    def require_array!(value)
       return if array?(value)
 
       raise ArgumentError, 'argument must be an array', caller[1..-1]
-    end # method require_array
-  end # module
-end # module
+    end
+  end
+end

data/lib/sleeping_king_studios/tools/base.rb

@@ -0,0 +1,20 @@
+# 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
+
+    # @return [SleepingKingStudios::Tools::Base] a memoized instance of the
+    #   tools class.
+    def self.instance
+      @instance ||= new
+    end
+  end
+end

data/lib/sleeping_king_studios/tools/core_tools.rb

@@ -1,11 +1,32 @@
-# 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
+    # Exception class used when deprecated code is called and the deprecation
+    # strategy is 'raise'.
+    class DeprecationError < StandardError; end
+
+    class << self
+      def_delegators :instance,
+        :deprecate,
+        :empty_binding,
+        :require_each
+    end
+
+    # @param deprecation_strategy [String] The name of the strategy used when
+    #   deprecated code is called. Must be 'ignore', 'raise', or 'warn'.
+    def initialize(deprecation_strategy: nil)
+      super()
+
+      @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 +43,68 @@ 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."
-
-      str = format % args
-      str << ' ' << message if message
+    def deprecate(*args, format: nil, message: nil)
+      send(
+        :"deprecate_as_#{deprecation_strategy}",
+        *args,
+        format:  format,
+        message: message
+      )
+    end
 
-      str << "\n  called from #{caller[1]}"
-
-      Kernel.warn str
-    end # method deprecate
+    # Generates an empty Binding object with an Object as the receiver.
+    #
+    # @return [Binding] The empty binding object.
+    def empty_binding
+      Object.new.instance_exec { 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/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
+    # Expected methods that a Hash-like object should implement.
+    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?,
+        :stringify_keys,
+        :symbolize_keys
+    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,37 @@ module SleepingKingStudios::Tools
       hsh.each do |key, value|
         ObjectTools.deep_freeze key
         ObjectTools.deep_freeze value
-      end # each
-    end # method deep_freeze
+      end
+    end
+
+    # Generates a Binding object with an Object as the receiver and the hash
+    # key-value pairs set as local variables.
+    #
+    # @return [Binding] The binding object.
+    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 +118,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 +139,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