sleeping_king_studios-tools 0.7.1 → 0.8.0

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

@@ -1,26 +1,21 @@
-# lib/sleeping_king_studios/tools/toolbox/constant_map.rb
+# frozen_string_literal: true
 
 require 'sleeping_king_studios/tools/string_tools'
 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
+  class ConstantMap < Module
+    # @param constants [Hash] The constants to define.
+    def initialize(constants)
+      super()
 
-        constants.each do |const_name, const_value|
-          mod.const_set const_name, const_value
-        end # each
+      constants.each do |const_name, const_value|
+        const_set(const_name, const_value)
 
-        mod
-      end # class method new
-    end # eigenclass
+        define_reader(const_name)
+      end
+    end
 
     # Returns a hash with the names and values of the defined constants.
     #
@@ -28,17 +23,17 @@ module SleepingKingStudios::Tools::Toolbox
     def all
       constants.each.with_object({}) do |const_name, hsh|
         hsh[const_name] = const_get(const_name)
-      end # each
-    end # method all
+      end
+    end
 
     # 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
+    def each(&block)
       all.each(&block)
-    end # method each
+    end
 
     # Freezes the constant map and recursively freezes every constant value
     # using ObjectTools#deep_freeze. Also pre-emptively defines any reader
@@ -47,48 +42,26 @@ module SleepingKingStudios::Tools::Toolbox
     # @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
+      end
 
       super
-    end # method freeze
+    end
 
     private
 
-    def define_reader const_name, reader_name = nil
-      reader_name ||= const_name.downcase
-
-      define_singleton_method reader_name, ->() { const_get const_name }
-    end # method define_reader
-
-    def method_missing symbol, *args, &block
-      const_name = string_tools.underscore(symbol.to_s).upcase.intern
-
-      if constants.include?(const_name)
-        define_reader(const_name, symbol)
+    def define_reader(const_name, reader_name = nil)
+      reader_name ||= string_tools.underscore(const_name.to_s).intern
 
-        return send(symbol, *args, &block)
-      end # if
-
-      super
-    end # method method_missing
+      define_singleton_method(reader_name) { const_get const_name }
+    end
 
     def object_tools
       ::SleepingKingStudios::Tools::ObjectTools
-    end # method object_tools
-
-    def respond_to_missing? symbol, include_all = false
-      const_name = string_tools.underscore(symbol.to_s).upcase.intern
-
-      constants.include?(const_name) || super
-    end # method respond_to_missing?
+    end
 
     def string_tools
       ::SleepingKingStudios::Tools::StringTools
-    end # method string_tools
-  end # module
-end # module
+    end
+  end
+end

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

@@ -1,7 +1,12 @@
-# lib/sleeping_king_studios/tools/toolbox/delegator.rb
+# frozen_string_literal: true
 
+require 'sleeping_king_studios/tools/core_tools'
 require 'sleeping_king_studios/tools/toolbox'
 
+# rubocop:disable Metrics/AbcSize
+# rubocop:disable Metrics/CyclomaticComplexity
+# rubocop:disable Metrics/MethodLength
+# rubocop:disable Metrics/PerceivedComplexity
 module SleepingKingStudios::Tools::Toolbox
   # Module for extending classes with basic delegation. Supports passing
   # arguments, keywords, and blocks to the delegated method.
@@ -13,6 +18,15 @@ module SleepingKingStudios::Tools::Toolbox
   #     delegate :my_method, :to => MyService
   #   end # class
   module Delegator
+    def self.extended(_module)
+      super
+
+      SleepingKingStudios::Tools::CoreTools.deprecate(
+        'SleepingKingStudios::Tools::Toolbox::Delegator',
+        message: 'Use Ruby stdlib Forwardable instead.'
+      )
+    end
+
     # Defines a wrapper method to delegate implementation of the specified
     # method or methods to an object, to the object at another specified method,
     # or to the object at a specified instance variable.
@@ -58,13 +72,13 @@ module SleepingKingStudios::Tools::Toolbox
     #   variable of that name and call `method_name` on the result.
     #
     # @raise ArgumentError if no delegate is specified.
-    def delegate *method_names, to: nil, allow_nil: false
-      raise ArgumentError.new('must specify a delegate') if to.nil? && !allow_nil
+    def delegate(*method_names, to: nil, allow_nil: false)
+      raise ArgumentError, 'must specify a delegate' if to.nil? && !allow_nil
 
       method_names.each do |method_name|
-        delegate_method method_name, to, { :allow_nil => !!allow_nil }
-      end # each
-    end # method delegate
+        delegate_method method_name, to, { allow_nil: !!allow_nil }
+      end
+    end
 
     # Wraps a delegate object by automatically delegating each method that is
     # defined on the delegate class from the instance to the delegate. The
@@ -79,7 +93,10 @@ module SleepingKingStudios::Tools::Toolbox
     #   class Errors
     #     extend SleepingKingStudios::Tools::Delegator
     #
-    #     wrap_delegate Hash.new { |hsh, key| hsh[key] = Errors.new }, :klass => Hash
+    #     wrap_delegate(
+    #       Hash.new { |hsh, key| hsh[key] = Errors.new },
+    #       :klass => Hash
+    #     )
     #
     #     def messages
     #       @messages ||= []
@@ -116,33 +133,33 @@ module SleepingKingStudios::Tools::Toolbox
     #   belong to the specified klass.
     #
     # @see #delegate
-    def wrap_delegate target, klass: nil, except: [], only: []
+    def wrap_delegate(target, klass: nil, except: [], only: [])
       if klass.is_a?(Module)
-        unless target.is_a?(String) || target.is_a?(Symbol) || target.is_a?(klass)
-          raise ArgumentError.new "expected delegate to be a #{klass.name}"
-        end # unless
+        unless target.is_a?(String) ||
+               target.is_a?(Symbol) ||
+               target.is_a?(klass)
+          raise ArgumentError, "expected delegate to be a #{klass.name}"
+        end
 
         method_names = klass.instance_methods - Object.instance_methods
       elsif target.is_a?(String) || target.is_a?(Symbol)
-        raise ArgumentError.new 'must specify a delegate class'
+        raise ArgumentError, 'must specify a delegate class'
       else
         method_names = target.methods - Object.new.methods
-      end # if-elsif-else
+      end
 
       if except.is_a?(Array) && !except.empty?
-        method_names = method_names - except.map(&:intern)
-      end # if
+        method_names -= except.map(&:intern)
+      end
 
-      if only.is_a?(Array) && !only.empty?
-        method_names = method_names & only.map(&:intern)
-      end # if
+      method_names &= only.map(&:intern) if only.is_a?(Array) && !only.empty?
 
-      delegate *method_names, :to => target
-    end # method wrap_delegate
+      delegate(*method_names, to: target)
+    end
 
     private
 
-    def delegate_method method_name, target, options = {}
+    def delegate_method(method_name, target, options = {})
       if target.is_a?(String) || target.is_a?(Symbol)
         target = target.intern
 
@@ -153,7 +170,7 @@ module SleepingKingStudios::Tools::Toolbox
             return nil if receiver.nil? && options[:allow_nil]
 
             receiver.send(method_name, *args, &block)
-          end # define_method
+          end
         else
           define_method method_name do |*args, &block|
             receiver = send(target)
@@ -161,15 +178,19 @@ module SleepingKingStudios::Tools::Toolbox
             return nil if receiver.nil? && options[:allow_nil]
 
             receiver.send(method_name, *args, &block)
-          end # define_method
-        end # if-else
+          end
+        end
       else
         define_method method_name do |*args, &block|
           return nil if target.nil? && options[:allow_nil]
 
           target.send(method_name, *args, &block)
-        end # define_method
-      end # if
-    end # method delegate_method
-  end # module
-end # module
+        end
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/AbcSize
+# rubocop:enable Metrics/CyclomaticComplexity
+# rubocop:enable Metrics/MethodLength
+# rubocop:enable Metrics/PerceivedComplexity

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

@@ -0,0 +1,130 @@
+# 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)
+      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
+
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/MethodLength
+
+    # 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)
+      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
+
+    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/MethodLength
+
+    # Transforms the word to a lowercase, underscore-separated form.
+    #
+    # @params 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