sleeping_king_studios-tools 0.7.0.rc.0 → 1.0.0

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

data/lib/sleeping_king_studios/tools/object_tools.rb

@@ -1,16 +1,32 @@
-# lib/sleeping_king_studios/tools/object_tools.rb
+# frozen_string_literal: true
 
 require 'sleeping_king_studios/tools'
 
 module SleepingKingStudios::Tools
   # Low-level tools for working with objects.
-  module ObjectTools
-    extend self
+  class ObjectTools < SleepingKingStudios::Tools::Base
+    TEMPORARY_METHOD_NAME =
+      '__sleeping_king_studios_tools_apply_%i__'
+    private_constant :TEMPORARY_METHOD_NAME
+
+    class << self
+      def_delegators :instance,
+        :apply,
+        :deep_dup,
+        :deep_freeze,
+        :dig,
+        :eigenclass,
+        :immutable?,
+        :metaclass,
+        :mutable?,
+        :object?,
+        :try
+    end
 
     # Takes a proc or lambda and invokes it with the given object as
     # receiver, with any additional arguments or block provided.
     #
-    # @param [Object] base The receiver. The proc will be called in the
+    # @param [Object] receiver The receiver. The proc will be called in the
     #   context of this object.
     # @param [Proc] proc The proc or lambda to call.
     # @param [Array] args Optional. Additional arguments to pass in to the
@@ -20,20 +36,16 @@ module SleepingKingStudios::Tools
     #
     # @return The result of calling the proc or lambda with the given
     #   receiver and any additional arguments or block.
-    def apply base, proc, *args, &block
-      return base.instance_exec *args, &proc unless block_given?
+    def apply(receiver, proc, *args, &block)
+      return receiver.instance_exec(*args, &proc) unless block_given?
 
-      temporary_method_name = :__sleeping_king_studios_tools_object_tools_temporary_method_for_applying_proc__
+      method_name =
+        Kernel.format(TEMPORARY_METHOD_NAME, Thread.current.object_id)
 
-      metaclass = class << base; self; end
-      metaclass.send :define_method, temporary_method_name, &proc
-
-      begin
-        base.send temporary_method_name, *args, &block
-      ensure
-        metaclass.send :remove_method, temporary_method_name if temporary_method_name && defined?(temporary_method_name)
+      with_temporary_method(receiver, method_name, proc) do
+        receiver.send(method_name, *args, &block)
       end
-    end # method apply
+    end
 
     # Creates a deep copy of the object. If the object is an Array, returns a
     # new Array with deep copies of each array item. If the object is a Hash,
@@ -43,7 +55,7 @@ module SleepingKingStudios::Tools
     # @param [Object] obj The object to copy.
     #
     # @return The copy of the object.
-    def deep_dup obj
+    def deep_dup(obj)
       case obj
       when FalseClass, Integer, Float, NilClass, Symbol, TrueClass
         obj
@@ -53,8 +65,8 @@ module SleepingKingStudios::Tools
         HashTools.deep_dup obj
       else
         obj.respond_to?(:deep_dup) ? obj.deep_dup : obj.dup
-      end # case
-    end # method deep_dup
+      end
+    end
 
     # Performs a deep freeze of the object. If the object is an Array, freezes
     # the array and performs a deep freeze on each array item. If the object is
@@ -62,7 +74,7 @@ module SleepingKingStudios::Tools
     # value. Otherwise, calls Object#freeze.
     #
     # @param [Object] obj The object to freeze.
-    def deep_freeze obj
+    def deep_freeze(obj)
       case obj
       when FalseClass, Integer, Float, NilClass, Symbol, TrueClass
         # Object is inherently immutable; do nothing here.
@@ -72,34 +84,41 @@ module SleepingKingStudios::Tools
         HashTools.deep_freeze obj
       else
         obj.respond_to?(:deep_freeze) ? obj.deep_freeze : obj.freeze
-      end # case
-    end # method deep_freeze
+      end
+    end
 
     # Accesses deeply nested attributes by calling the first named method on the
     # given object, and each subsequent method on the result of the previous
     # method call. If the object does not respond to the method name, nil is
     # returned instead of calling the method.
     #
-    # @param [Object] obj The object to dig.
+    # @param [Object] object The object to dig.
     # @param [Array] method_names The names of the methods to call.
     #
     # @return [Object] The result of the last method call, or nil if the last
     #   object does not respond to the last method.
-    def dig object, *method_names
+    def dig(object, *method_names)
       method_names.reduce(object) do |memo, method_name|
         memo.respond_to?(method_name) ? memo.send(method_name) : nil
-      end # reduce
-    end # method object
+      end
+    end
+
+    # @!method metaclass(object)
+    #   Returns the object's singleton class.
+    #
+    #   @param [Object] object The object for which an eigenclass is required.
+    #
+    #   @return [Class] The object's eigenclass.
 
     # Returns the object's eigenclass.
     #
     # @param [Object] object The object for which an eigenclass is required.
     #
-    # @return [Class] The object's eigenclass.
-    def eigenclass object
-      class << object; self; end
-    end # method eigenclass
-    alias_method :metaclass, :eigenclass
+    # @return [Class] The object's singleton class.
+    def eigenclass(object)
+      object.singleton_class
+    end
+    alias metaclass eigenclass
 
     # Returns true if the object is immutable. Values of nil, false, and true
     # are always immutable, as are instances of Numeric and Symbol. Arrays are
@@ -110,7 +129,7 @@ module SleepingKingStudios::Tools
     # @param obj [Object] The object to test.
     #
     # @return [Boolean] True if the object is immutable, otherwise false.
-    def immutable? obj
+    def immutable?(obj)
       case obj
       when NilClass, FalseClass, TrueClass, Numeric, Symbol
         true
@@ -120,8 +139,8 @@ module SleepingKingStudios::Tools
         HashTools.immutable? obj
       else
         obj.frozen?
-      end # case
-    end # method immutable?
+      end
+    end
 
     # Returns true if the object is mutable.
     #
@@ -130,9 +149,9 @@ module SleepingKingStudios::Tools
     # @return [Boolean] True if the object is mutable, otherwise false.
     #
     # @see #immutable?
-    def mutable? obj
+    def mutable?(obj)
       !immutable?(obj)
-    end # method mutable?
+    end
 
     # Returns true if the object is an Object. This should return true only for
     # objects that have an alternate inheritance chain from BasicObject, such as
@@ -141,9 +160,9 @@ module SleepingKingStudios::Tools
     # @param obj [Object] The object to test.
     #
     # @return [Boolean] True if the object is an Object, otherwise false.
-    def object? obj
-      Object === obj
-    end # method object?
+    def object?(obj)
+      Object.instance_method(:is_a?).bind(obj).call(Object)
+    end
 
     # As #send, but returns nil if the object does not respond to the method.
     #
@@ -151,23 +170,27 @@ module SleepingKingStudios::Tools
     # @param [String, Symbol] method_name The name of the method to call.
     # @param [Array] args The arguments to the message.
     #
-    # @see active_support/core_ext/object/try.rb
-    def try object, method_name, *args
-      if object.nil?
-        return object.respond_to?(method_name) ?
-          object.send(method_name, *args) :
-          nil
-      end # if
-
-      # Delegate to ActiveSupport::CoreExt::Object#try.
+    # @see ActiveSupport::CoreExt::Object#try.
+    def try(object, method_name, *args)
       return object.try(method_name, *args) if object.respond_to?(:try)
 
+      return nil unless object.respond_to?(method_name)
+
       object.send method_name, *args
-    rescue NoMethodError => exception
-      nil
-    end # method try
-  end # module
-end # module
+    end
+
+    private
+
+    def with_temporary_method(receiver, method_name, proc)
+      metaclass = class << receiver; self; end
+      metaclass.send :define_method, method_name, &proc
+
+      yield
+    ensure
+      metaclass.send :remove_method, method_name
+    end
+  end
+end
 
 require 'sleeping_king_studios/tools/array_tools'
 require 'sleeping_king_studios/tools/hash_tools'

data/lib/sleeping_king_studios/tools/string_tools.rb

@@ -1,14 +1,40 @@
-# lib/sleeping_king_studios/tools/string_tools.rb
+# frozen_string_literal: true
 
 require 'sleeping_king_studios/tools'
-require 'sleeping_king_studios/tools/object_tools'
+require 'sleeping_king_studios/tools/toolbox/inflector'
 
 module SleepingKingStudios::Tools
   # Tools for working with strings.
-  module StringTools
-    extend self
-
-    autoload :PluralInflector, 'sleeping_king_studios/tools/string_tools/plural_inflector'
+  class StringTools < SleepingKingStudios::Tools::Base
+    class << self
+      def_delegators :instance,
+        :camelize,
+        :chain,
+        :define_irregular_word,
+        :define_plural_rule,
+        :define_singular_rule,
+        :define_uncountable_word,
+        :indent,
+        :map_lines,
+        :plural?,
+        :pluralize,
+        :singular?,
+        :singularize,
+        :string?,
+        :underscore
+    end
+
+    # @param inflector [Object] An object that conforms to the interface used
+    #   by SleepingKingStudios::Tools::Toolbox::Inflector, such as
+    #   ActiveSupport::Inflector .
+    def initialize(inflector: nil)
+      super()
+
+      @inflector =
+        inflector || SleepingKingStudios::Tools::Toolbox::Inflector.new
+    end
+
+    attr_reader :inflector
 
     # Converts a lowercase, underscore-separated string to CamelCase.
     #
@@ -17,13 +43,11 @@ module SleepingKingStudios::Tools
     # @return [String] The converted string.
     #
     # @see ActiveSupport::Inflector#camelize.
-    def camelize str
+    def camelize(str)
       str = require_string! str
 
-      str = str.dup
-      str.gsub!(/(\b|[_-])([a-z])/) { |match| $2.upcase }
-      str
-    end # method camelize
+      inflector.camelize(str)
+    end
 
     # Performs multiple string tools operations in sequence, starting with the
     # given string and passing the result of each operation to the next.
@@ -32,31 +56,11 @@ module SleepingKingStudios::Tools
     # @param commands [Array<String, Symbol>] The string operations to apply.
     #
     # @return [String] The processed string.
-    def chain str, *commands
+    def chain(str, *commands)
       str = require_string! str
 
       commands.reduce(str) { |memo, command| send(command, memo) }
-    end # method chain
-
-    # (see PluralInflector#define_irregular_word)
-    def define_irregular_word singular, plural
-      plural_inflector.define_irregular_word singular, plural
-    end # method define_irregular_word
-
-    # (see PluralInflector#define_plural_rule)
-    def define_plural_rule match, replace
-      plural_inflector.define_plural_rule match, replace
-    end # method define_plural_rule
-
-    # (see PluralInflector#define_singular_rule)
-    def define_singular_rule match, replace
-      plural_inflector.define_singular_rule match, replace
-    end # method define_singular_rule
-
-    # (see PluralInflector#define_uncountable_word)
-    def define_uncountable_word word
-      plural_inflector.define_uncountable_word word
-    end # method define_uncountable_word
+    end
 
     # Adds the specified number of spaces to the start of each line of the
     # string. Defaults to 2 spaces.
@@ -65,12 +69,12 @@ module SleepingKingStudios::Tools
     # @param count [Integer] The number of spaces to add.
     #
     # @return [String] The indented string.
-    def indent str, count = 2
+    def indent(str, count = 2)
       str = require_string! str
-      pre = " " * count
+      pre = ' ' * count
 
       map_lines(str) { |line| "#{pre}#{line}" }
-    end # method indent
+    end
 
     # Yields each line of the string to the provided block and combines the
     # results into a new multiline string.
@@ -81,23 +85,23 @@ module SleepingKingStudios::Tools
     # @yieldparam index [Integer] The index of the current line.
     #
     # @return [String] The mapped string.
-    def map_lines str
+    def map_lines(str)
       str = require_string! str
 
-      str.each_line.with_index.reduce('') do |memo, (line, index)|
+      str.each_line.with_index.reduce(+'') do |memo, (line, index)|
         memo << yield(line, index)
-      end # each_line
-    end # method map_lines
+      end
+    end
 
     # Determines whether or not the given word is in plural form. If calling
     # #pluralize(word) is equal to word, the word is considered plural.
     #
     # @return [Boolean] True if the word is in plural form, otherwise false.
-    def plural? word
+    def plural?(word)
       word = require_string!(word)
 
       word == pluralize(word)
-    end # method plural?
+    end
 
     # @overload pluralize(str)
     #   Takes a word in singular form and returns the plural form, based on the
@@ -106,63 +110,41 @@ module SleepingKingStudios::Tools
     #   @param str [String] The word to pluralize.
     #
     #   @return [String] The pluralized word.
-    #
-    # @overload pluralize(count, single, plural)
-    #   @deprecated This functionality is deprecated as of version 0.4.0 and
-    #     will be removed in a future version. Use IntegerTools#pluralize
-    #     instead.
-    #
-    #   Returns the singular or the plural value, depending on the provided
-    #   item count.
-    #
-    #   @example
-    #     "There are four #{StringTools.pluralize 4, 'light', 'lights'}!"
-    #     #=> 'There are four lights!'
-    #
-    #   @param [Integer] count The number of items.
-    #   @param [String] single The singular form of the word or phrase.
-    #   @param [String] plural The plural form of the word or phrase.
-    #
-    #   @return [String] The single form if count == 1; otherwise the plural
-    #     form.
-    def pluralize *args
-      if args.count == 3
-        CoreTools.deprecate 'StringTools#pluralize with 3 arguments',
-          :message => 'Use IntegerTools#pluralize instead.'
-
-        return IntegerTools.pluralize(*args)
-      end # if
-
+    def pluralize(*args)
       str = require_string! args.first
 
-      plural_inflector.pluralize str
-    end # method pluralize
+      inflector.pluralize str
+    end
 
     # Determines whether or not the given word is in singular form. If calling
     # #singularize(word) is equal to word, the word is considered singular.
     #
     # @return [Boolean] True if the word is in singular form, otherwise false.
-    def singular? word
+    def singular?(word)
       word = require_string!(word)
 
       word == singularize(word)
-    end # method singular?
+    end
 
-    # (see PluralInflector#singularize)
-    def singularize str
+    # Transforms the word to a singular, lowercase form.
+    #
+    # @param str [String] The word to transform.
+    #
+    # @return [String] The word in singular form.
+    def singularize(str)
       require_string! str
 
-      plural_inflector.singularize str
-    end # method singularize
+      inflector.singularize str
+    end
 
     # Returns true if the object is a String.
     #
     # @param str [Object] The object to test.
     #
     # @return [Boolean] True if the object is a String, otherwise false.
-    def string? str
-      String === str
-    end # method string?
+    def string?(str)
+      str.is_a?(String)
+    end
 
     # Converts a mixed-case string expression to a lowercase, underscore
     # separated string.
@@ -172,29 +154,20 @@ module SleepingKingStudios::Tools
     # @return [String] The converted string.
     #
     # @see ActiveSupport::Inflector#underscore.
-    def underscore str
+    def underscore(str)
       str = require_string! str
 
-      str = str.dup
-      str.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
-      str.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
-      str.tr!("-", "_")
-      str.downcase!
-      str
-    end # method underscore
+      inflector.underscore(str)
+    end
 
     private
 
-    def plural_inflector
-      @plural_inflector ||= PluralInflector.new
-    end # method plural_inflector
-
-    def require_string! value
+    def require_string!(value)
       return value if string?(value)
 
       return value.to_s if value.is_a?(Symbol)
 
       raise ArgumentError, 'argument must be a string', caller[1..-1]
-    end # method require_array
-  end # module
-end # module
+    end
+  end
+end