sleeping_king_studios-tools 1.1.0 → 1.2.0.rc.0

data/lib/sleeping_king_studios/tools/object_tools.rb

@@ -23,38 +23,85 @@ module SleepingKingStudios::Tools
         :try
     end
 
-    # Takes a proc or lambda and invokes it with the given object as
-    # receiver, with any additional arguments or block provided.
+    # Calls a Proc or lambda on the given receiver with the given parameters.
     #
-    # @param [Object] receiver The receiver. The proc will be called in the
+    # Unlike calling #instance_exec with the block, ObjectTools#apply allows you
+    # to specify a block parameter.
+    #
+    # @param receiver [Object] 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
-    #   proc or lambda.
-    # @param [block] block Optional. If present, will be passed in to proc or
+    # @param proc [Proc] the proc or lambda to call.
+    # @param args [Array] optional. Additional arguments to pass in to the proc
+    #   or lambda.
+    # @param kwargs [Hash] optional. Additional keywords to pass in to the proc
+    #   or lambda.
+    # @param block [block] optional. If present, will be passed in to proc or
     #   lambda.
     #
-    # @return The result of calling the proc or lambda with the given
+    # @return the result of calling the proc or lambda with the given
     #   receiver and any additional arguments or block.
-    def apply(receiver, proc, *args, &block)
-      return receiver.instance_exec(*args, &proc) unless block_given?
+    #
+    # @example
+    #   my_object = double('object', :to_s => 'A mock object')
+    #   my_proc   = ->() { puts %{#{self.to_s} says "Greetings, programs!"} }
+    #
+    #   ObjectTools.apply my_object, my_proc
+    #   #=> Writes 'A mock object says "Greetings, programs!"' to STDOUT.
+    def apply(receiver, proc, *args, **kwargs, &block)
+      return receiver.instance_exec(*args, **kwargs, &proc) unless block_given?
 
       method_name =
         Kernel.format(TEMPORARY_METHOD_NAME, Thread.current.object_id)
 
       with_temporary_method(receiver, method_name, proc) do
-        receiver.send(method_name, *args, &block)
+        receiver.send(method_name, *args, **kwargs, &block)
       end
     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,
-    # returns a new Hash with deep copies of each hash key and value. Otherwise,
-    # returns Object#dup.
+    # 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, returns a new Hash with deep copies
+    # of each hash key and value. Otherwise, returns Object#dup.
+    #
+    # @param obj [Object] the object to copy.
+    #
+    # @return the copy of the object.
     #
-    # @param [Object] obj The object to copy.
+    # @see ArrayTools#deep_copy
     #
-    # @return The copy of the object.
+    # @see HashTools#deep_copy
+    #
+    # @example
+    #   data = {
+    #     :songs = [
+    #       {
+    #         :name   => 'Welcome to the Jungle',
+    #         :artist => "Guns N' Roses",
+    #         :album  => 'Appetite for Destruction'
+    #       },
+    #       {
+    #         :name   => 'Hells Bells',
+    #         :artist => 'AC/DC',
+    #         :album  => 'Back in Black'
+    #       },
+    #       {
+    #         :name   => "Knockin' on Heaven's Door",
+    #         :artist => 'Bob Dylan',
+    #         :album  => 'Pat Garrett & Billy The Kid'
+    #       }
+    #     ]
+    #   }
+    #
+    #   copy = ObjectTools.deep_dup data
+    #
+    #   copy[:songs] << { :name => 'Sympathy for the Devil', :artist => 'The Rolling Stones', :album => 'Beggars Banquet' }
+    #   data[:songs].count
+    #   #=> 3
+    #
+    #   copy[:songs][1][:name] = 'Shoot to Thrill'
+    #   data[:songs][1]
+    #   #=> { :name => 'Hells Bells', :artist => 'AC/DC', :album => 'Back in Black' }
     def deep_dup(obj)
       case obj
       when FalseClass, Integer, Float, NilClass, Symbol, TrueClass
@@ -68,12 +115,46 @@ module SleepingKingStudios::Tools
       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
-    # a hash, freezes the hash and performs a deep freeze on each hash key and
-    # value. Otherwise, calls Object#freeze.
+    # 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 a hash, freezes the hash and performs a
+    # deep freeze on each hash key and value. Otherwise, calls Object#freeze.
     #
-    # @param [Object] obj The object to freeze.
+    # @param obj [Object] The object to freeze.
+    #
+    # @return [Object] the frozen object.
+    #
+    # @example
+    #   data = {
+    #     :songs = [
+    #       {
+    #         :name   => 'Welcome to the Jungle',
+    #         :artist => "Guns N' Roses",
+    #         :album  => 'Appetite for Destruction'
+    #       },
+    #       {
+    #         :name   => 'Hells Bells',
+    #         :artist => 'AC/DC',
+    #         :album  => 'Back in Black'
+    #       },
+    #       {
+    #         :name   => "Knockin' on Heaven's Door",
+    #         :artist => 'Bob Dylan',
+    #         :album  => 'Pat Garrett & Billy The Kid'
+    #       }
+    #     ]
+    #   }
+    #   ObjectTools.deep_freeze(data)
+    #
+    #   data.frozen?
+    #   #=> true
+    #   data[:songs].frozen?
+    #   #=> true
+    #   data[:songs][0].frozen?
+    #   #=> true
+    #   data[:songs][0].name.frozen?
+    #   #=> true
     def deep_freeze(obj)
       case obj
       when FalseClass, Integer, Float, NilClass, Symbol, TrueClass
@@ -87,96 +168,160 @@ module SleepingKingStudios::Tools
       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.
+    # Accesses deeply nested attributes on an object.
+    #
+    # This method calls the first named method on the given object, and then
+    # 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 obj [Object] the object to dig.
+    # @param method_names [Array] the names of the methods to call.
     #
-    # @param [Object] object The object to dig.
-    # @param [Array] method_names The names of the methods to call.
+    # @return [Object, nil] the result of the last method call, or nil if the
+    #   last object does not respond to the last method.
     #
-    # @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)
-      method_names.reduce(object) do |memo, method_name|
+    # @example
+    #   ObjectTools.dig my_object, :first_method, :second_method, :third_method
+    #   #=> my_object.first_method.second_method.third_method
+    def dig(obj, *method_names)
+      method_names.reduce(obj) do |memo, method_name|
         memo.respond_to?(method_name) ? memo.send(method_name) : nil
       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.
+    # @param obj [Object] the object for which an eigenclass is required.
     #
-    # @return [Class] The object's singleton class.
-    def eigenclass(object)
-      object.singleton_class
+    # @return [Class] the object's singleton class.
+    def eigenclass(obj)
+      obj.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
-    # immutable if the array is frozen and each array item is immutable. Hashes
-    # are immutable if the hash is frozen and each hash key and hash value are
-    # immutable. Otherwise, objects are immutable if they are frozen.
+    # Checks if the object is immutable.
+    #
+    # - nil, false, and true are always immutable, as are instances of Numeric
+    #   and Symbol.
+    # - Strings are immutable if frozen, such as strings defined in a file with
+    #   a frozen_string_literal pragma.
+    # - Arrays are immutable if the array is frozen and each array item is
+    #   immutable.
+    # - Hashes are immutable if the hash is frozen and each hash key and hash
+    #   value are immutable.
+    # - Otherwise, objects are immutable if they are frozen.
+    #
+    # @param obj [Object] the object to test.
     #
-    # @param obj [Object] The object to test.
+    # @return [Boolean] true if the object is immutable, otherwise false.
     #
-    # @return [Boolean] True if the object is immutable, otherwise false.
+    # @example
+    #   ObjectTools.immutable?(nil)
+    #   #=> true
+    #
+    #   ObjectTools.immutable?(false)
+    #   #=> true
+    #
+    #   ObjectTools.immutable?(0)
+    #   #=> true
+    #
+    #   ObjectTools.immutable?(:hello)
+    #   #=> true
+    #
+    #   ObjectTools.immutable?('Greetings, programs!')
+    #   #=> true
+    #
+    #   ObjectTools.immutable?(+'Greetings, programs!')
+    #   #=> false
+    #
+    #   ObjectTools.immutable?([1, 2, 3])
+    #   #=> false
+    #
+    #   ObjectTools.immutable?([1, 2, 3].freeze)
+    #   #=> false
+    #
+    # @see #mutable?
+    #
+    # @see ArrayTools#immutable?
+    #
+    # @see HashTools#immutable?
     def immutable?(obj)
       case obj
       when NilClass, FalseClass, TrueClass, Numeric, Symbol
         true
       when ->(_) { ArrayTools.array?(obj) }
-        ArrayTools.immutable? obj
+        ArrayTools.immutable?(obj)
       when ->(_) { HashTools.hash?(obj) }
-        HashTools.immutable? obj
+        HashTools.immutable?(obj)
       else
         obj.frozen?
       end
     end
 
-    # Returns true if the object is mutable.
+    # Checks if the object is mutable.
     #
-    # @param obj [Object] The object to test.
+    # @param obj [Object] the object to test.
     #
-    # @return [Boolean] True if the object is mutable, otherwise false.
+    # @return [Boolean] true if the object is mutable, otherwise false.
     #
     # @see #immutable?
     def mutable?(obj)
       !immutable?(obj)
     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
-    # a Proxy.
+    # Returns true if the object is an Object.
     #
-    # @param obj [Object] The object to test.
+    # This should return false only for objects that have an alternate
+    # inheritance chain from BasicObject, such as a Proxy.
     #
-    # @return [Boolean] True if the object is an Object, otherwise false.
+    # @param obj [Object] the object to test.
+    #
+    # @return [Boolean] true if the object is an Object, otherwise false.
+    #
+    # @example
+    #   ObjectTools.object?(nil)
+    #   #=> true
+    #
+    #   ObjectTools.object?([])
+    #   #=> true
+    #
+    #   ObjectTools.object?({})
+    #   #=> true
+    #
+    #   ObjectTools.object?(1)
+    #   #=> true
+    #
+    #   ObjectTools.object?(BasicObject.new)
+    #   #=> false
     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.
     #
-    # @param [Object] object The receiver of the message.
-    # @param [String, Symbol] method_name The name of the method to call.
-    # @param [Array] args The arguments to the message.
+    # This method relies on #respond_to?, so methods defined with method_missing
+    # will not be called.
+    #
+    # @param obj [Object] the receiver of the message.
+    # @param method_name [String, Symbol] the name of the method to call.
+    # @param args [Array] the arguments to the message.
+    #
+    # @return [Object, nil] the return value of the called method, or nil if the
+    #   object does not respond to the method.
     #
-    # @see ActiveSupport::CoreExt::Object#try.
-    def try(object, method_name, *args)
-      return object.try(method_name, *args) if object.respond_to?(:try)
+    # @example
+    #   ObjectTools.try(%w(ichi ni san), :count)
+    #   #=> 3
+    #
+    #   ObjectTools.try(nil, :count)
+    #   #=> nil
+    def try(obj, method_name, *args)
+      return obj.try(method_name, *args) if obj.respond_to?(:try)
 
-      return nil unless object.respond_to?(method_name)
+      return nil unless obj.respond_to?(method_name)
 
-      object.send method_name, *args
+      obj.send(method_name, *args)
     end
 
     private
@@ -191,6 +336,3 @@ module SleepingKingStudios::Tools
     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

@@ -10,10 +10,6 @@ module SleepingKingStudios::Tools
       def_delegators :instance,
         :camelize,
         :chain,
-        :define_irregular_word,
-        :define_plural_rule,
-        :define_singular_rule,
-        :define_uncountable_word,
         :indent,
         :map_lines,
         :plural?,
@@ -24,9 +20,10 @@ 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 .
+    # @param inflector [Object] service object for inflecting strings. The
+    #   inflector must be an object that conforms to the interface used by
+    #   by SleepingKingStudios::Tools::Toolbox::Inflector, such as an instance
+    #   of ActiveSupport::Inflector .
     def initialize(inflector: nil)
       super()
 
@@ -34,69 +31,131 @@ module SleepingKingStudios::Tools
         inflector || SleepingKingStudios::Tools::Toolbox::Inflector.new
     end
 
+    # @return [Object] service object for inflecting strings.
     attr_reader :inflector
 
     # Converts a lowercase, underscore-separated string to CamelCase.
     #
-    # @param str [String] The string to convert.
+    # @param str [String] the string to convert.
     #
-    # @return [String] The converted string.
+    # @return [String] the converted string.
     #
-    # @see ActiveSupport::Inflector#camelize.
+    # @see SleepingKingStudios::Tools::Toolbox::Inflector#camelize.
+    #
+    # @example
+    #   StringTools#camelize 'valhalla'
+    #   #=> 'Valhalla'
+    #
+    #   StringTools#camelize 'muspelheimr_and_niflheimr'
+    #   #=> 'MuspelheimrAndNiflheimr'
     def camelize(str)
-      str = require_string! str
+      str = require_string!(str)
 
       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.
+    # Performs a series of operations on the string.
+    #
+    # Use #chain to call each specified method in the chain in sequence, passing
+    # the output of each method to the next method.
+    #
+    # @param str [String] the string to process.
+    # @param commands [Array<String, Symbol>] the string operations to apply.
     #
-    # @param str [String] The string to process.
-    # @param commands [Array<String, Symbol>] The string operations to apply.
+    # @return [String] the processed string.
     #
-    # @return [String] The processed string.
+    # @example
+    #   # Equivalent to `StringTools.underscore(StringTools.pluralize str)`.
+    #   StringTools#chain 'ArchivedPeriodical', :underscore, :pluralize
+    #   # => 'archived_periodicals'
     def chain(str, *commands)
-      str = require_string! str
+      str = require_string!(str)
 
       commands.reduce(str) { |memo, command| send(command, memo) }
     end
 
-    # Adds the specified number of spaces to the start of each line of the
-    # string. Defaults to 2 spaces.
+    # Adds the specified number of spaces to the start of each line.
     #
-    # @param str [String] The string to indent.
-    # @param count [Integer] The number of spaces to add.
+    # @param str [String] the string to indent.
+    # @param count [Integer] the number of spaces to add. Defaults to 2.
     #
-    # @return [String] The indented string.
+    # @return [String] the indented string.
+    #
+    # @example
+    #   string = 'The Hobbit'
+    #   StringTools.indent(string)
+    #   #=> '  The Hobbit'
+    #
+    #   titles = [
+    #     "The Fellowship of the Ring",
+    #     "The Two Towers",
+    #     "The Return of the King"
+    #   ]
+    #   string = titles.join "\n"
+    #   StringTools.indent(string, 4)
+    #   #=> "    The Fellowship of the Ring\n"\
+    #       "    The Two Towers\n"\
+    #       "    The Return of the King"
     def indent(str, count = 2)
-      str = require_string! str
+      str = require_string!(str)
       pre = ' ' * count
 
       map_lines(str) { |line| "#{pre}#{line}" }
     end
 
-    # Yields each line of the string to the provided block and combines the
-    # results into a new multiline string.
+    # Yields each line to the provided block and combines the results.
+    #
+    # The results of each line are combined back into a new multi-line string.
+    #
+    # @param str [String] the string to map.
     #
-    # @param str [String] The string to map.
+    # @yieldparam line [String] the current line.
+    # @yieldparam index [Integer] the index of the current line.
     #
-    # @yieldparam line [String] The current line.
-    # @yieldparam index [Integer] The index of the current line.
+    # @yieldreturn [String] the modified line.
     #
-    # @return [String] The mapped string.
+    # @return [String] the mapped and recombined string.
+    #
+    # @example
+    #   string = 'The Hobbit'
+    #   StringTools.map_lines(string) { |line| "  #{line}" }
+    #   #=> '- The Hobbit'
+    #
+    #   titles = [
+    #     "The Fellowship of the Ring",
+    #     "The Two Towers",
+    #     "The Return of the King"
+    #   ]
+    #   string = titles.join "\n"
+    #   StringTools.map_lines(string) { |line, index| "#{index}. #{line}" }
+    #   #=> "0. The Fellowship of the Ring\n"\
+    #       "1. The Two Towers\n"\
+    #       "2. The Return of the King"
     def map_lines(str)
-      str = require_string! str
+      str = require_string!(str)
 
       str.each_line.with_index.reduce(+'') do |memo, (line, index)|
         memo << yield(line, index)
       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.
+    # Determines whether or not the given word is in plural form.
+    #
+    # If calling #pluralize(word) is equal to word, the word is considered
+    # plural.
+    #
+    # @param word [String] the word to check.
+    #
+    # @return [Boolean] true if the word is in plural form, otherwise false.
+    #
+    # @example
+    #   StringTools.plural? 'light'
+    #   #=> false
+    #
+    #   StringTools.plural? 'lights'
+    #   #=> true
     #
-    # @return [Boolean] True if the word is in plural form, otherwise false.
+    # @see #pluralize
     def plural?(word)
       word = require_string!(word)
 
@@ -104,22 +163,44 @@ module SleepingKingStudios::Tools
     end
 
     # @overload pluralize(str)
-    #   Takes a word in singular form and returns the plural form, based on the
-    #   defined rules and known irregular/uncountable words.
+    #   Takes a word in singular form and returns the plural form.
     #
-    #   @param str [String] The word to pluralize.
+    #   This method delegates to the configured inflector, which converts the
+    #   given word based on the defined rules and known irregular/uncountable
+    #   words.
     #
-    #   @return [String] The pluralized word.
+    #   @param str [String] the word to pluralize.
+    #
+    #   @return [String] the pluralized word.
+    #
+    #   @example
+    #     StringTools.pluralize 'light'
+    #     #=> 'lights'
+    #
+    #   @see SleepingKingStudios::Tools::Toolbox::Inflector#pluralize.
     def pluralize(*args)
-      str = require_string! args.first
+      str = require_string!(args.first)
 
-      inflector.pluralize str
+      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.
+    # Determines whether or not the given word is in singular form.
+    #
+    # If calling #singularize(word) is equal to word, the word is considered
+    # singular.
+    #
+    # @param word [String] the word to check.
+    #
+    # @return [Boolean] true if the word is in singular form, otherwise false.
+    #
+    # @see #singularize
     #
-    # @return [Boolean] True if the word is in singular form, otherwise false.
+    # @example
+    #   StringTools.singular? 'light'
+    #   #=> true
+    #
+    #   StringTools.singular? 'lights'
+    #   #=> false
     def singular?(word)
       word = require_string!(word)
 
@@ -128,34 +209,60 @@ module SleepingKingStudios::Tools
 
     # Transforms the word to a singular, lowercase form.
     #
-    # @param str [String] The word to transform.
+    # This method delegates to the configured inflector, which converts the
+    # given word based on the defined rules and known irregular/uncountable
+    # words.
+    #
+    # @param str [String] the word to transform.
+    #
+    # @return [String] the word in singular form.
+    #
+    #   @see SleepingKingStudios::Tools::Toolbox::Inflector#singularize.
     #
-    # @return [String] The word in singular form.
+    # @example
+    #   StringTools.singularize 'lights'
+    #   #=> 'light'
     def singularize(str)
-      require_string! str
+      require_string!(str)
 
-      inflector.singularize str
+      inflector.singularize(str)
     end
 
     # Returns true if the object is a String.
     #
-    # @param str [Object] The object to test.
+    # @param str [Object] the object to test.
     #
-    # @return [Boolean] True if the object is a String, otherwise false.
+    # @return [Boolean] true if the object is a String, otherwise false.
+    #
+    # @example
+    #   StringTools.string?(nil)
+    #   #=> false
+    #   StringTools.string?([])
+    #   #=> false
+    #   StringTools.string?('Greetings, programs!')
+    #   #=> true
+    #   StringTools.string?(:greetings_starfighter)
+    #   #=> false
     def string?(str)
       str.is_a?(String)
     end
 
-    # Converts a mixed-case string expression to a lowercase, underscore
-    # separated string.
+    # Converts a mixed-case string to a lowercase, underscore separated string.
+    #
+    # @param str [String] the string to convert.
+    #
+    # @return [String] the converted string.
     #
-    # @param str [String] The string to convert.
+    # @see SleepingKingStudios::Tools::Toolbox::Inflector#underscore.
     #
-    # @return [String] The converted string.
+    # @example
+    #   StringTools#underscore 'Bifrost'
+    #   #=> 'bifrost'
     #
-    # @see ActiveSupport::Inflector#underscore.
+    #   StringTools#underscore 'FenrisWolf'
+    #   #=> 'fenris_wolf'
     def underscore(str)
-      str = require_string! str
+      str = require_string!(str)
 
       inflector.underscore(str)
     end