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

data/lib/sleeping_king_studios/tools/toolbelt.rb

@@ -1,34 +1,55 @@
-# lib/sleeping_king_studios/tools/toolbelt.rb
+# frozen_string_literal: true
 
-require 'sleeping_king_studios/tools/all'
+require 'sleeping_king_studios/tools'
 
 module SleepingKingStudios::Tools
   # Helper object for quick access to all available tools.
   class Toolbelt < BasicObject
+    # @return [SleepingKingStudios::Tools::Toolbelt] a memoized instance of the
+    #   toolbelt class.
     def self.instance
       @instance ||= new
-    end # class method instance
+    end
 
-    namespace = ::SleepingKingStudios::Tools
+    # @param deprecation_strategy [String] The name of the strategy used when
+    #   deprecated code is called. Must be 'ignore', 'raise', or 'warn'.
+    # @param inflector [Object] An object that conforms to the interface used
+    #   by SleepingKingStudios::Tools::Toolbox::Inflector, such as
+    #   ActiveSupport::Inflector .
+    def initialize(deprecation_strategy: nil, inflector: nil)
+      @array_tools   = ::SleepingKingStudios::Tools::ArrayTools.new
+      @core_tools    = ::SleepingKingStudios::Tools::CoreTools.new(
+        deprecation_strategy: deprecation_strategy
+      )
+      @hash_tools    = ::SleepingKingStudios::Tools::HashTools.new
+      @integer_tools = ::SleepingKingStudios::Tools::IntegerTools.new
+      @object_tools  = ::SleepingKingStudios::Tools::ObjectTools.new
+      @string_tools  =
+        ::SleepingKingStudios::Tools::StringTools.new(inflector: inflector)
+    end
 
-    %w(array core hash integer object string).each do |name|
-      define_method(name) do
-        begin
-          namespace.const_get("#{name.capitalize}Tools")
-        rescue NameError => exception
-          nil
-        end # begin-rescue
-      end # each
-    end # each
+    attr_reader :array_tools
 
+    attr_reader :core_tools
+
+    attr_reader :hash_tools
+
+    attr_reader :integer_tools
+
+    attr_reader :object_tools
+
+    attr_reader :string_tools
+
+    alias ary array_tools
+    alias hsh hash_tools
+    alias int integer_tools
+    alias obj object_tools
+    alias str string_tools
+
+    # @return [String] a human-readable representation of the object.
     def inspect
-      @to_s ||=
-        begin
-          object_class = class << self; self; end.superclass
-
-          "#<#{object_class.name}>"
-        end # string
-    end # method inspect
-    alias_method :to_s, :inspect
-  end # module
-end # module
+      "#<#{::Object.instance_method(:class).bind(self).call.name}>"
+    end
+    alias to_s inspect
+  end
+end

data/lib/sleeping_king_studios/tools/toolbox.rb

@@ -1,4 +1,4 @@
-# lib/sleeping_king_studios/tools/toolbox.rb
+# frozen_string_literal: true
 
 require 'sleeping_king_studios/tools'
 
@@ -7,4 +7,4 @@ module SleepingKingStudios::Tools
   # are larger than or do not fit the functional paradigm of the tools.*
   # pattern.
   module Toolbox; end
-end # module
+end

data/lib/sleeping_king_studios/tools/toolbox/constant_map.rb

@@ -1,94 +1,95 @@
-# lib/sleeping_king_studios/tools/toolbox/constant_map.rb
+# frozen_string_literal: true
 
-require 'sleeping_king_studios/tools/string_tools'
+require 'forwardable'
+
+require 'sleeping_king_studios/tools/toolbelt'
 require 'sleeping_king_studios/tools/toolbox'
 
 module SleepingKingStudios::Tools::Toolbox
   # Provides an enumerable interface for defining a group of constants.
-  module ConstantMap
-    class << self
-      # Creates a new ConstantMap.
-      #
-      # @param constants [Hash] The constants to define.
-      def new constants
-        mod = Module.new
-        mod.extend self
-
-        constants.each do |const_name, const_value|
-          mod.const_set const_name, const_value
-        end # each
-
-        mod
-      end # class method new
-    end # eigenclass
-
-    # Returns a hash with the names and values of the defined constants.
-    #
-    # @return [Hash] The defined constants.
-    def all
-      constants.each.with_object({}) do |const_name, hsh|
-        hsh[const_name] = const_get(const_name)
-      end # each
-    end # method all
-
-    # Iterates through the defined constants, yielding the name and value of
-    # each constant to the block.
+  class ConstantMap < Module
+    extend  Forwardable
+    include Enumerable
+
+    # @param constants [Hash] The constants to define.
+    def initialize(constants)
+      super()
+
+      @to_h = constants.dup
+
+      constants.each do |const_name, const_value|
+        const_set(const_name, const_value)
+
+        define_reader(const_name)
+      end
+    end
+
+    def_delegators :@to_h,
+      :each,
+      :each_key,
+      :each_pair,
+      :each_value,
+      :keys,
+      :values
+
+    # @!method each
+    #   Iterates through the defined constants, yielding the name and value of
+    #   each constant to the block.
     #
-    # @yieldparam key [Symbol] The name of the symbol.
-    # @yieldparam value [Object] The value of the symbol.
-    def each &block
-      all.each(&block)
-    end # method each
+    #   @yieldparam key [Symbol] The name of the constant.
+    #   @yieldparam value [Object] The value of the constant.
 
-    # Freezes the constant map and recursively freezes every constant value
-    # using ObjectTools#deep_freeze. Also pre-emptively defines any reader
-    # methods that are not already undefined.
+    # @!method each_key
+    #   Iterates through the defined constants, yielding the name of each
+    #   constant to the block.
     #
-    # @see ObjectTools#deep_freeze
-    def freeze
-      constants.each do |const_name|
-        reader_name = const_name.downcase
-
-        define_reader(const_name, reader_name) unless methods.include?(reader_name)
-
-        object_tools.deep_freeze const_get(const_name)
-      end # each
+    #   @yieldparam key [Symbol] The name of the constant.
 
-      super
-    end # method freeze
+    # @!method each_pair
+    #   Iterates through the defined constants, yielding the name and value of
+    #   each constant to the block.
+    #
+    #   @yieldparam key [Symbol] The name of the constant.
+    #   @yieldparam value [Object] The value of the constant.
 
-    private
+    # @!method each_value
+    #   Iterates through the defined constants, yielding the value of each
+    #   constant to the block.
+    #
+    #   @yieldparam value [Object] The value of the constant.
 
-    def define_reader const_name, reader_name = nil
-      reader_name ||= const_name.downcase
+    # @!method keys
+    #   @return [Array] the names of the defined constants.
 
-      define_singleton_method reader_name, ->() { const_get const_name }
-    end # method define_reader
+    # @!method values
+    #   @return [Array] the values of the defined constants.
 
-    def method_missing symbol, *args, &block
-      const_name = string_tools.underscore(symbol.to_s).upcase.intern
+    # @return [Hash] The defined constants.
+    attr_reader :to_h
+    alias all to_h
 
-      if constants.include?(const_name)
-        define_reader(const_name, symbol)
+    # Freezes the constant map and recursively freezes every constant value
+    # using ObjectTools#deep_freeze.
+    #
+    # @see ObjectTools#deep_freeze
+    def freeze
+      super
 
-        return send(symbol, *args, &block)
-      end # if
+      tools.hsh.deep_freeze(@to_h)
 
-      super
-    end # method method_missing
+      self
+    end
 
-    def object_tools
-      ::SleepingKingStudios::Tools::ObjectTools
-    end # method object_tools
+    private
 
-    def respond_to_missing? symbol, include_all = false
-      const_name = string_tools.underscore(symbol.to_s).upcase.intern
+    def define_reader(const_name)
+      reader_name ||= tools.str.underscore(const_name.to_s).intern
 
-      constants.include?(const_name) || super
-    end # method respond_to_missing?
+      define_singleton_method(reader_name) { const_get const_name }
+    end
 
-    def string_tools
-      ::SleepingKingStudios::Tools::StringTools
-    end # method string_tools
-  end # module
-end # module
+    def tools
+      ::SleepingKingStudios::Tools::Toolbelt.instance
+    end
+  end
+end

data/lib/sleeping_king_studios/tools/toolbox/inflector.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require 'sleeping_king_studios/tools/toolbox'
+
+module SleepingKingStudios::Tools::Toolbox
+  # Transforms words (e.g. from singular to plural).
+  #
+  # Should maintain the same interface as ActiveSupport::Inflector.
+  class Inflector
+    extend Forwardable
+
+    autoload :Rules, 'sleeping_king_studios/tools/toolbox/inflector/rules'
+
+    def_delegators :@rules,
+      :irregular_words,
+      :irregular_words_reversed,
+      :plural_rules,
+      :singular_rules,
+      :uncountable_words
+
+    private \
+      :irregular_words,
+      :irregular_words_reversed,
+      :plural_rules,
+      :singular_rules,
+      :uncountable_words
+
+    # @return [Rules] An object defining the transformation rules.
+    def initialize(rules: nil)
+      @rules = rules || Rules.new
+    end
+
+    # @return [Rules] The defined rules object for the inflector.
+    attr_reader :rules
+
+    # Transforms the word to CamelCase.
+    #
+    # @param word [String] The word to transform.
+    # @param uppercase_first_letter [Boolean] If true, the first letter is
+    #   capitalized. Defaults to true.
+    #
+    # @return [String] The word in CamelCase.
+    def camelize(word, uppercase_first_letter = true) # rubocop:disable Style/OptionalBooleanParameter
+      return '' if word.nil? || word.empty?
+
+      word = word.to_s.gsub(/(\b|[_-])([a-z])/) { Regexp.last_match(2).upcase }
+
+      (uppercase_first_letter ? word[0].upcase : word[0].downcase) + word[1..-1]
+    end
+
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/CyclomaticComplexity
+
+    # Transforms the word to a plural, lowercase form.
+    #
+    # @param word [String] The word to transform.
+    #
+    # @return [String] The word in plural form.
+    def pluralize(word)
+      return '' if word.nil? || word.empty?
+
+      normalized = word.to_s.strip.downcase
+
+      return normalized if uncountable_words.include?(normalized)
+
+      return normalized if irregular_words_reversed.key?(normalized)
+
+      return irregular_words[normalized] if irregular_words.key?(normalized)
+
+      plural_rules.each do |match, replace|
+        next unless normalized =~ match
+
+        return normalized.sub(match, replace)
+      end
+
+      word
+    end
+    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/CyclomaticComplexity
+
+    # Transforms the word to a singular, lowercase form.
+    #
+    # @param word [String] The word to transform.
+    #
+    # @return [String] The word in singular form.
+    def singularize(word) # rubocop:disable Metrics/MethodLength
+      return '' if word.nil? || word.empty?
+
+      normalized = word.to_s.strip.downcase
+
+      return normalized if irregular_words.key?(normalized)
+
+      if irregular_words_reversed.key?(normalized)
+        return irregular_words_reversed[normalized]
+      end
+
+      singular_rules.each do |match, replace|
+        next unless normalized =~ match
+
+        return normalized.sub(match, replace)
+      end
+
+      word
+    end
+
+    # Transforms the word to a lowercase, underscore-separated form.
+    #
+    # @param word [String] the word to transform.
+    #
+    # @return [String] The word in underscored form.
+    def underscore(word)
+      return '' if word.nil? || word.empty?
+
+      word = word.to_s.gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+
+      word.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+      word.tr!('-', '_')
+      word.downcase!
+      word
+    end
+  end
+end

data/lib/sleeping_king_studios/tools/toolbox/inflector/rules.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/toolbox'
+
+class SleepingKingStudios::Tools::Toolbox::Inflector
+  # Rules for inflecting words.
+  class Rules
+    # @param irregular_words [Hash<String, String>] Hash of irregular word
+    #   pairs in singular => plural order, e.g. "child" => "children".
+    # @param plural_rules [Array<Array<(Regexp, String)>>] Rules for
+    #   pluralizing words.
+    # @param singular_rules [Array<Array<(Regexp, String)>>] Rules for
+    #   singularizing words.
+    # @param uncountable_words [Array<String>] List of uncountable words,
+    #   e.g. "data".
+    def initialize(
+      irregular_words:   nil,
+      plural_rules:      nil,
+      singular_rules:    nil,
+      uncountable_words: nil
+    )
+      @plural_rules      = plural_rules    || default_plural_rules
+      @singular_rules    = singular_rules  || default_singular_rules
+      @irregular_words   = irregular_words || default_irregular_words
+      @uncountable_words =
+        Set.new(uncountable_words || default_uncountable_words)
+
+      @irregular_words_reversed = reverse_hash(@irregular_words)
+    end
+
+    # @return [Array<Array<(String, String)>] Hash of irregular word pairs in
+    #   singular => plural order.
+    attr_reader :irregular_words
+
+    # @return [Array<Array<(String, String)>] Hash of irregular word pairs in
+    #   plural => singular order.
+    attr_reader :irregular_words_reversed
+
+    # @return [Array<Array<(Regexp, String)>>] Rules for pluralizing words.
+    attr_reader :plural_rules
+
+    # @return [Array<Array<(Regexp, String)>>] Rules for singularizing words.
+    attr_reader :singular_rules
+
+    # @return [Array<String>] List of uncountable words.
+    attr_reader :uncountable_words
+
+    # Defines an irregular word pair.
+    #
+    # @param singular [String] The singular form of the word.
+    # @param plural [String] The plural form of the word.
+    #
+    # @return [Rules] The rules object.
+    def define_irregular_word(singular, plural)
+      validate_string(singular)
+      validate_string(plural)
+
+      @irregular_words[singular]        = plural
+      @irregular_words_reversed[plural] = singular
+
+      self
+    end
+
+    # Defines a pluralization rule.
+    #
+    # @param pattern [Regexp] The pattern to match.
+    # @param replace [String] The string to replace.
+    #
+    # @return [Rules] The rules object.
+    def define_plural_rule(pattern, replace)
+      validate_pattern(pattern)
+      validate_string(replace, as: 'replace')
+
+      @plural_rules.unshift([pattern, replace])
+
+      self
+    end
+
+    # Defines a singularization rule.
+    #
+    # @param pattern [Regexp] The pattern to match.
+    # @param replace [String] The string to replace.
+    #
+    # @return [Rules] The rules object.
+    def define_singular_rule(pattern, replace)
+      validate_pattern(pattern)
+      validate_string(replace, as: 'replace')
+
+      @singular_rules.unshift([pattern, replace])
+
+      self
+    end
+
+    # Defines an uncountable word.
+    #
+    # @param word [String] The uncountable word.
+    #
+    # @return [Rules] The rules object.
+    def define_uncountable_word(word)
+      validate_string(word)
+
+      @uncountable_words << word
+
+      self
+    end
+
+    # @return [String] A human-readable representation of the rules object.
+    def inspect
+      "#<SleepingKingStudios::Tools::Toolbox::Inflector::Rules:#{object_id}>"
+    end
+
+    private
+
+    def default_irregular_words
+      {
+        'child'  => 'children',
+        'person' => 'people'
+      }
+    end
+
+    def default_plural_rules
+      [
+        [/([^aeiouy])y$/i, '\1ies'],   # Winery => Wineries
+        [/([^aeiouy]o)$/i, '\1es'],    # Halo   => Haloes
+        [/(ss|[xz]|[cs]h)$/i, '\1es'], # Truss  => Trusses
+        [/s$/i, 's'],                  # Words  => Words
+        [/$/, 's']                     # Word   => Words
+      ]
+    end
+
+    def default_singular_rules
+      [
+        [/([^aeiouy])ies$/i, '\1y'],   # Wineries => Winery
+        [/([^aeiouy]o)es$/, '\1'],     # Haloes   => Halo
+        [/(ss|[sxz]|[cs]h)es$/, '\1'], # Torches  => Torch
+        [/ss$/i, 'ss'],                # Truss    => Truss
+        [/s$/i, '']                    # Words    => Word
+      ]
+    end
+
+    def default_uncountable_words
+      %w[data]
+    end
+
+    def reverse_hash(hsh)
+      hsh.each.with_object({}) do |(key, value), reversed|
+        reversed[value] = key
+      end
+    end
+
+    def validate_pattern(rxp)
+      raise ArgumentError, "pattern can't be blank", caller(1..-1) if rxp.nil?
+
+      return if rxp.is_a?(Regexp)
+
+      raise ArgumentError, 'pattern must be a Regexp', caller(1..-1)
+    end
+
+    def validate_string(word, as: 'word')
+      raise ArgumentError, "#{as} can't be blank", caller(1..-1) if word.nil?
+
+      unless word.is_a?(String)
+        raise ArgumentError, "#{as} must be a String", caller(1..-1)
+      end
+
+      return unless word.empty?
+
+      raise ArgumentError, "#{as} can't be blank", caller(1..-1)
+    end
+  end
+end