sleeping_king_studios-tools 0.8.0 → 1.0.0.rc.0

data/lib/sleeping_king_studios/tools/base.rb

@@ -11,6 +11,8 @@ module SleepingKingStudios::Tools
       extend Forwardable
     end
 
+    # @return [SleepingKingStudios::Tools::Base] a memoized instance of the
+    #   tools class.
     def self.instance
       @instance ||= new
     end

data/lib/sleeping_king_studios/tools/core_tools.rb

@@ -5,6 +5,8 @@ require 'sleeping_king_studios/tools'
 module SleepingKingStudios::Tools
   # Tools for working with an application or working environment.
   class CoreTools < Base
+    # Exception class used when deprecated code is called and the deprecation
+    # strategy is 'raise'.
     class DeprecationError < StandardError; end
 
     class << self
@@ -14,7 +16,11 @@ module SleepingKingStudios::Tools
         :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
@@ -46,17 +52,11 @@ module SleepingKingStudios::Tools
       )
     end
 
-    # Generates an empty Binding object with a BasicObject as the receiver.
+    # Generates an empty Binding object with an Object as the receiver.
     #
     # @return [Binding] The empty binding object.
     def empty_binding
-      context = Object.new
-
-      def context.binding
-        Kernel.instance_method(:binding).bind(self).call
-      end
-
-      context.binding
+      Object.new.instance_exec { binding }
     end
 
     # Expands each file pattern and requires each file.

data/lib/sleeping_king_studios/tools/hash_tools.rb

@@ -5,6 +5,7 @@ require 'sleeping_king_studios/tools'
 module SleepingKingStudios::Tools
   # Tools for working with hash-like enumerable objects.
   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
@@ -16,10 +17,9 @@ module SleepingKingStudios::Tools
         :generate_binding,
         :hash?,
         :immutable?,
-        :mutable?
-
-      alias stringify_keys convert_keys_to_strings
-      alias symbolize_keys convert_keys_to_symbols
+        :mutable?,
+        :stringify_keys,
+        :symbolize_keys
     end
 
     # Returns a copy of the hash with the keys converted to strings.
@@ -83,6 +83,10 @@ module SleepingKingStudios::Tools
       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
 

data/lib/sleeping_king_studios/tools/integer_tools.rb

@@ -168,7 +168,7 @@ module SleepingKingStudios::Tools
           romanize_digit(additive: additive, digit: digit.to_i, tens: index)
         end
         .reverse
-        .join ''
+        .join
     end
 
     private

data/lib/sleeping_king_studios/tools/object_tools.rb

@@ -17,11 +17,10 @@ module SleepingKingStudios::Tools
         :dig,
         :eigenclass,
         :immutable?,
+        :metaclass,
         :mutable?,
         :object?,
         :try
-
-      alias metaclass eigenclass
     end
 
     # Takes a proc or lambda and invokes it with the given object as
@@ -93,7 +92,7 @@ module SleepingKingStudios::Tools
     # 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
@@ -104,11 +103,18 @@ module SleepingKingStudios::Tools
       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.
+    # @return [Class] The object's singleton class.
     def eigenclass(object)
       object.singleton_class
     end

data/lib/sleeping_king_studios/tools/string_tools.rb

@@ -24,7 +24,12 @@ module SleepingKingStudios::Tools
         :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
@@ -57,34 +62,6 @@ module SleepingKingStudios::Tools
       commands.reduce(str) { |memo, command| send(command, memo) }
     end
 
-    # (see PluralInflector#define_irregular_word)
-    def define_irregular_word(singular, plural)
-      CoreTools.deprecate 'StringTools#define_irregular_word'
-
-      inflector.rules.define_irregular_word singular, plural
-    end
-
-    # (see PluralInflector#define_plural_rule)
-    def define_plural_rule(match, replace)
-      CoreTools.deprecate 'StringTools#define_plural_rule'
-
-      inflector.rules.define_plural_rule match, replace
-    end
-
-    # (see PluralInflector#define_singular_rule)
-    def define_singular_rule(match, replace)
-      CoreTools.deprecate 'StringTools#define_singular_rule'
-
-      inflector.rules.define_singular_rule match, replace
-    end
-
-    # (see PluralInflector#define_uncountable_word)
-    def define_uncountable_word(word)
-      CoreTools.deprecate 'StringTools#define_uncountable_word'
-
-      inflector.rules.define_uncountable_word word
-    end
-
     # Adds the specified number of spaces to the start of each line of the
     # string. Defaults to 2 spaces.
     #
@@ -133,33 +110,7 @@ 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
-
       str = require_string! args.first
 
       inflector.pluralize str
@@ -175,7 +126,11 @@ module SleepingKingStudios::Tools
       word == singularize(word)
     end
 
-    # (see PluralInflector#singularize)
+    # 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
 

data/lib/sleeping_king_studios/tools/toolbelt.rb

@@ -5,10 +5,17 @@ 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
 
+    # @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(
@@ -39,17 +46,7 @@ module SleepingKingStudios::Tools
     alias obj object_tools
     alias str string_tools
 
-    %w[array core hash integer object string].each do |name|
-      define_method(name) do
-        ::SleepingKingStudios::Tools::CoreTools.deprecate(
-          "SleepingKingStudios::Tools::Toolbelt##{name}",
-          message: "Use ##{name}_tools instead."
-        )
-
-        ::SleepingKingStudios::Tools.const_get("#{name.capitalize}Tools")
-      end
-    end
-
+    # @return [String] a human-readable representation of the object.
     def inspect
       "#<#{::Object.instance_method(:class).bind(self).call.name}>"
     end

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

@@ -1,15 +1,22 @@
 # 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.
   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)
 
@@ -17,51 +24,72 @@ module SleepingKingStudios::Tools::Toolbox
       end
     end
 
-    # Returns a hash with the names and values of the defined constants.
+    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.
     #
-    # @return [Hash] The defined constants.
-    def all
-      constants.each.with_object({}) do |const_name, hsh|
-        hsh[const_name] = const_get(const_name)
-      end
-    end
+    #   @yieldparam key [Symbol] The name of the constant.
+    #   @yieldparam value [Object] The value of the constant.
 
-    # Iterates through the defined constants, yielding the name and value of
-    # each constant to the block.
+    # @!method each_key
+    #   Iterates through the defined constants, yielding the name 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
+    #   @yieldparam key [Symbol] The name of the constant.
+
+    # @!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.
+
+    # @!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.
+
+    # @!method keys
+    #   @return [Array] the names of the defined constants.
+
+    # @!method values
+    #   @return [Array] the values of the defined constants.
+
+    # @return [Hash] The defined constants.
+    attr_reader :to_h
+    alias all to_h
 
     # 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.
+    # using ObjectTools#deep_freeze.
     #
     # @see ObjectTools#deep_freeze
     def freeze
-      constants.each do |const_name|
-        object_tools.deep_freeze const_get(const_name)
-      end
-
       super
+
+      tools.hsh.deep_freeze(@to_h)
+
+      self
     end
 
     private
 
-    def define_reader(const_name, reader_name = nil)
-      reader_name ||= string_tools.underscore(const_name.to_s).intern
+    def define_reader(const_name)
+      reader_name ||= tools.str.underscore(const_name.to_s).intern
 
       define_singleton_method(reader_name) { const_get const_name }
     end
 
-    def object_tools
-      ::SleepingKingStudios::Tools::ObjectTools
-    end
-
-    def string_tools
-      ::SleepingKingStudios::Tools::StringTools
+    def tools
+      ::SleepingKingStudios::Tools::Toolbelt.instance
     end
   end
 end

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

@@ -42,7 +42,7 @@ module SleepingKingStudios::Tools::Toolbox
     #   capitalized. Defaults to true.
     #
     # @return [String] The word in CamelCase.
-    def camelize(word, uppercase_first_letter = true)
+    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 }
@@ -80,15 +80,12 @@ module SleepingKingStudios::Tools::Toolbox
     # 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)
+    def singularize(word) # rubocop:disable Metrics/MethodLength
       return '' if word.nil? || word.empty?
 
       normalized = word.to_s.strip.downcase
@@ -108,12 +105,9 @@ module SleepingKingStudios::Tools::Toolbox
       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.
+    # @param word [String] the word to transform.
     #
     # @return [String] The word in underscored form.
     def underscore(word)

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

@@ -12,7 +12,7 @@ module SleepingKingStudios::Tools::Toolbox
       mod.singleton_class.include?(self)
     end
 
-    # @api private
+    # @private
     def included(other)
       return super unless defined?(self::ClassMethods)
 

data/lib/sleeping_king_studios/tools/version.rb

@@ -10,13 +10,19 @@ module SleepingKingStudios
     module Version
       extend SleepingKingStudios::Tools::Toolbox::SemanticVersion
 
-      MAJOR      = 0
-      MINOR      = 8
-      PATCH      = 0
-      PRERELEASE = nil
-      BUILD      = nil
+      # Major version.
+      MAJOR = 1
+      # Minor version.
+      MINOR = 0
+      # Patch version.
+      PATCH = 0
+      # Prerelease version.
+      PRERELEASE = :rc
+      # Build metadata.
+      BUILD = 0
     end
 
+    # The current version of the gem.
     VERSION = Version.to_gem_version
   end
 end