sleeping_king_studios-tools 0.4.0 → 0.5.0.rc.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f296e034d67c6ae33d69e7e40ccbdb62eaa65cdf
-  data.tar.gz: 694ed1dc928edc084e9aa54453c8944ab25f8937
+  metadata.gz: 2cae6265d25b7d2972d938909435e59949c77b23
+  data.tar.gz: 3471511cbcdd63bfed0a61eb5681a8b8c0328f71
 SHA512:
-  metadata.gz: 521bc036894b1f5eaaf08a512875f7d4adac55abfc63166a36be39ef3ade2d827fdc48c454fff4385ffda5ae32ed4128cdc86e85ce9496ce727c7c3f6b426f28
-  data.tar.gz: bdec4ed0afeae762c0402507910a80a1e7572c8ee19389a69938393ff935f3c66fa5c7d6ea78ec8aa6d273b03f002a9ef702f82074a62aba1404485d22736304
+  metadata.gz: 4860968042c42af8a2309a5c178fe0885e69efc645fb87880f8fb2266607a14b0b312d71c4993a392f516c1a155acd044d1c23b2344238b9c3b73c0455409a9a
+  data.tar.gz: dc6074d5dac36aeebb47fccd5e904e1e6deac3aa48c07c95217b1f601d2cf4ac83681b0e5b107ea4fa17d36a2e92183cd091479ef3cadc11920aefc248f68707

data/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## Pre-release Versions
 
+### 0.5.0
+
+- Implement CoreTools#require_each.
+- Implement StringTools#camelize.
+- Add an optional block argument to ArrayTools#humanize_list.
+
+#### Toolbox
+
+- Implement Delegator#delegate, Delegator#wrap_delegate.
+- Refactor SemanticVersion to the Toolbox namespace. Accessing SemanticVersion as Tools::SemanticVersion is now deprecated, use Tools::Toolbox::SemanticVersion.
+
+#### Identity Methods
+
+- Implement a set of methods to classify objects by type: ArrayTools#array?, HashTools#hash?, IntegerTools#integer?, ObjectTools#object?, and StringTools#string?.
+
+#### Mutability Methods
+
+Implement #immutable? and #mutable? for ObjectTools, ArrayTools, and HashTools, which indicate whether or not a given object is mutable.
+
+Implement #deep_freeze for ObjectTools, ArrayTools, and HashTools which recursively freezes the object and any children (array items, hash keys, and hash values).
+
+## Current Release
+
 ### 0.4.0
 
 #### CoreTools
@@ -16,8 +39,6 @@ Implement #pluralize.
 
 Implement #pluralize and #singularize. The previous behavior of #pluralize is deprecated; use IntegerTools#pluralize.
 
-## Current Release
-
 ### 0.3.0
 
 Implement ArrayTools#bisect and ArrayTools#splice.

data/DEVELOPMENT.md

@@ -1,30 +1,5 @@
 # Development Notes
 
-## Version 0.5.0 - The Cold Update
-
-- ObjectTools#immutable? - delegates to specific toolset implementations.
-  - 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 all items are immutable.
-  - Hashes are immutable if the hash is frozen and all keys and values are immutable.
-  - All other objects are only immutable if the object is frozen.
-- ObjectTools#freeze - delegates to specific toolset implementation
-  - Arrays freeze the collection and each item
-  - Hashes freeze the collection and each key and value
-- ObjectTools#frozen_copy
-
-## Version 0.6.0 - The Identity Update
-
-### Features
-
-- Identity Methods
-  - ArrayTools#array? - true if object is array-like
-  - HashTools#hash? - true if object is hash-like
-  - IntegerTools#integer? - true if object is integer
-  - ObjectTools#object? - true if object is object-like (not BasicObject!)
-  - StringTools#string? - true if object is string
-  - s/is/is or claims to be a/ - see http://guides.rubyonrails.org/active_support_core_extensions.html#acts-like-questionmark-duck
-- StringTools#humanize_list - accept a block. If block given, yield each item and join the results.
-
 ## Future Tasks
 
 - Remove 'extend self' from Tools modules.
@@ -33,6 +8,11 @@
 
 #### Tools
 
+- StringTools#chain |
+
+  tools.chain(str, :underscore, :pluralize)
+  #=> shorthand for tools.pluralize(tools.underscore str)
+
 - ObjectTools#pretty - returns user-friendly string representation. :multiline option? Delegates to specific toolset implementations.
 - RegexpTools#matching_string - generates a string that matches the regular expression. Does not support advanced Regexp features.
 - RegexpTools#nonmatching_strings - generates a set of strings that do not match the regular expression.

data/README.md

@@ -35,6 +35,17 @@ The tools can be accessed in a convenient form using the Toolbelt class.
 
 Tools for working with array-like enumerable objects.
 
+#### `#array?`
+
+Returns true if the object is or appears to be an Array.
+
+    ArrayTools.array?(nil)
+    #=> false
+    ArrayTools.array?([])
+    #=> true
+    ArrayTools.array?({})
+    #=> false
+
 #### `#bisect`
 
 Separates the array into two arrays, the first containing all items in the original array that matches the provided block, and the second containing all items in the original array that do not match the provided block.
@@ -76,6 +87,18 @@ Creates a deep copy of the object by returning a new Array with deep copies of e
     ary
     #=> ['one', 'two', 'three']
 
+#### `#deep_freeze`
+
+Freezes the array and performs a deep freeze on each array item. See also ObjectTools#deep_freeze[#label-Object+Tools].
+
+    ary = ['one', 'two', 'three']
+    ArrayTools.deep_freeze ary
+
+    ary.frozen?
+    #=> true
+    ary.first.frozen?
+    #=> true
+
 #### `#humanize_list`
 
 Accepts a list of values and returns a human-readable string of the values, with the format based on the number of items.
@@ -92,6 +115,33 @@ Accepts a list of values and returns a human-readable string of the values, with
     ArrayTools.humanize_list(['spam', 'eggs', 'bacon', 'spam'])
     #=> 'spam, eggs, bacon, and spam'
 
+    # With A Block
+    ArrayTools.humanize_list(['bronze', 'silver', 'gold'], { |str| str.capitalize })
+    #=> 'Bronze, Silver, and Gold'
+
+#### `#immutable?`
+
+Returns true if the array is immutable, i.e. the array is frozen and each array item is immutable.
+
+    ArrayTools.immutable?([1, 2, 3])
+    #=> false
+
+    ArrayTools.immutable?([1, 2, 3].freeze)
+    #=> true
+
+    ArrayTools.immutable?(['ichi', 'ni', 'san'])
+    #=> false
+
+    ArrayTools.immutable?(['ichi', 'ni', 'san'].freeze)
+    #=> false
+
+    ArrayTools.immutable?(['ichi'.freeze, 'ni'.freeze, 'san'.freeze].freeze)
+    #=> true
+
+#### `#mutable?`
+
+Returns true if the array is mutable (see `#immutable?`, above).
+
 #### `#splice`
 
 Accepts an array, a start value, a number of items to delete, and zero or more items to insert at that index. Deletes the specified number of items, then inserts the given items at the index and returns the array of deleted items.
@@ -121,7 +171,7 @@ Accepts an array, a start value, a number of items to delete, and zero or more i
 
 Tools for working with an application or working environment.
 
-#### '#deprecate'
+#### `#deprecate`
 
 Prints a deprecation warning.
 
@@ -137,6 +187,16 @@ Prints a deprecation warning.
     ObjectTools#old_method was deprecated in version 0.1.0.
       called from /path/to/file.rb:4: in something_or_other
 
+#### `#require_each`
+
+Takes a file pattern or a list of file names and requires each file.
+
+    CoreTools.require_each '/path/to/one', '/path/to/two', '/path/to/three'
+    #=> Requires each file.
+
+    CoreTools.require_each '/path/to/directory/**/*.rb'
+    #=> Requires each file matching the pattern.
+
 ### Hash Tools
 
 Tools for working with array-like enumerable objects.
@@ -158,6 +218,46 @@ Creates a deep copy of the object by returning a new Hash with deep copies of ea
     hsh
     #=> { :one => 'one', :two => 'two', :three => 'three' }
 
+#### `#deep_freeze`
+
+Freezes the hash and performs a deep freeze on each hash key and value.
+
+    hsh = { :one => 'one', :two => 'two', :three => 'three' }
+    HashTools.deep_freeze hsh
+
+    hsh.frozen?
+    #=> true
+    hsh[:one].frozen?
+    #=> true
+
+#### `#hash?`
+
+Returns true if the object is or appears to be a Hash.
+
+    HashTools.hash?(nil)
+    #=> false
+    HashTools.hash?([])
+    #=> false
+    HashTools.hash?({})
+    #=> true
+
+#### `#immutable?`
+
+Returns true if the hash is immutable, i.e. if the hash is frozen and each hash key and hash value are immutable.
+
+    HashTools.immutable?({ :id => 0, :title => 'The Ramayana' })
+    #=> false
+
+    HashTools.immutable?({ :id => 0, :title => 'The Ramayana' }.freeze)
+    #=> false
+
+    HashTools.immutable?({ :id => 0, :title => 'The Ramayana'.freeze }.freeze)
+    #=> true
+
+#### `#mutable?`
+
+Returns true if the hash is mutable (see `#immutable?`, above).
+
 ### Integer Tools
 
 Tools for working with integers and fixnums.
@@ -198,6 +298,19 @@ Decomposes the given integer into its digits when represented in the given base.
     IntegerTools.digits(16724838)
     #=> ['f', 'f', '3', '3', '6', '6']
 
+#### `#integer?`
+
+Returns true if the object is an Integer.
+
+    IntegerTools.integer?(nil)
+    #=> false
+    IntegerTools.integer?([])
+    #=> false
+    IntegerTools.integer?({})
+    #=> false
+    IntegerTools.integer?(1)
+    #=> true
+
 #### `#pluralize`
 
 Returns the singular or the plural value, depending on the provided item count.
@@ -262,6 +375,40 @@ Creates a deep copy of the object. If the object is an Array, returns a new Arra
     data[:songs][1]
     #=> { :name => 'Hells Bells', :artist => 'AC/DC', :album => 'Back in Black' }
 
+#### `#deep_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 (see ArrayTools#deep_dup[#label-Array+Tools]). If the object is a hash, freezes the hash and performs a deep freeze on each hash key and value (see HashTools#deep_dup[#label-Hash+Tools]). Otherwise, calls Object#freeze unless the object is already immutable.
+
+    data = {
+      :songs = [
+        {
+          :name   => 'Welcome to the Jungle',
+          :artist => "Guns N' Roses",
+          :album  => 'Appetite for Destruction'
+        }, # end hash
+        {
+          :name   => 'Hells Bells',
+          :artist => 'AC/DC',
+          :album  => 'Back in Black'
+        }, # end hash
+        {
+          :name   => "Knockin' on Heaven's Door",
+          :artist => 'Bob Dylan',
+          :album  => 'Pat Garrett & Billy The Kid'
+        } # end hash
+      ] # end array
+    } # end hash
+    ObjectTools.deep_freeze(data)
+
+    data.frozen?
+    #=> true
+    data[:songs].frozen?
+    #=> true
+    data[:songs][0].frozen?
+    #=> true
+    data[:songs][0].name.frozen?
+    #=> true
+
 #### `#eigenclass`, `#metaclass`
 
 Returns the object's eigenclass.
@@ -269,12 +416,75 @@ Returns the object's eigenclass.
     ObjectTools.eigenclass my_object
     #=> Shortcut for class << self; self; end.
 
+#### `#immutable?`
+
+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.
+
+    ObjectTools.immutable?(nil)
+    #=> true
+
+    ObjectTools.immutable?(false)
+    #=> true
+
+    ObjectTools.immutable?(0)
+    #=> true
+
+    ObjectTools.immutable?(:hello)
+    #=> true
+
+    ObjectTools.immutable?("Greetings, programs!")
+    #=> false
+
+    ObjectTools.immutable?([1, 2, 3])
+    #=> false
+
+    ObjectTools.immutable?([1, 2, 3].freeze)
+    #=> false
+
+#### `#mutable?`
+
+Returns true if the object is mutable (see `#immutable?`, above).
+
+#### `#object?`
+
+Returns true if the object is an Object.
+
+    ObjectTools.object?(nil)
+    #=> true
+    ObjectTools.object?([])
+    #=> true
+    ObjectTools.object?({})
+    #=> true
+    ObjectTools.object?(1)
+    #=> true
+    ObjectTools.object?(BasicObject.new)
+    #=> false
+
+#### `#try`
+
+As #send, but returns nil if the object does not respond to the method.
+
+    ObjectTools.try(%w(ichi ni san), :count)
+    #=> 3
+    ObjectTools.try(nil, :count)
+    #=> nil
+
 ### String Tools
 
     require 'sleeping_king_studios/tools/string_tools'
 
 Tools for working with strings.
 
+#### `#camelize`
+
+Converts a lowercase, underscore separated string to a mixed-case string expression, as per ActiveSupport::Inflector#camelize.
+
+    StringTools#camelize 'valhalla'
+    #=> 'Valhalla'
+
+    StringTools#camelize 'muspelheimr_and_niflheimr'
+    #=> 'MuspelheimrAndNiflheimr'
+
 #### `#pluralize`
 
 Takes a word in singular form and returns the plural form, based on the defined rules and known irregular/uncountable words.
@@ -316,20 +526,113 @@ Takes a word in plural form and returns the singular form, based on the defined
     StringTools.singularize 'elves'
     #=> 'elf'
 
+#### `#string?`
+
+Returns true if the object is a String.
+
+    StringTools.string?(nil)
+    #=> false
+    StringTools.string?([])
+    #=> false
+    StringTools.string?('Greetings, programs!')
+    #=> true
+    StringTools.string?(:greetings_starfighter)
+    #=> false
+
 #### `#underscore`
 
 Converts a mixed-case string expression to a lowercase, underscore separated string, as per ActiveSupport::Inflector#underscore.
 
-## Additional Features
+    StringTools#underscore 'Bifrost'
+    #=> 'bifrost'
+
+    StringTools#underscore 'FenrisWolf'
+    #=> 'fenris_wolf'
+
+## Toolbox
+
+Common objects or patterns that are useful across projects but are larger than or do not fit the functional paradigm of the tools.* pattern.
+
+### Delegator
+
+    require 'sleeping_king_studios/tools/delegator'
+
+    require 'sleeping_king_studios/tools/toolbox/delegator'
+
+    class MyClass
+      extend SleepingKingStudios::Tools::Delegator
+
+      delegate :my_method, :to => MyService
+    end # class
+
+Module for extending classes with basic delegation.
+
+#### `::delegate`
+
+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.
+
+    # Delegate to an object
+    class MyModule
+      extend SleepingKingStudios::Tools::Delegator
+
+      delegate :my_method, :to => MyService
+    end class
+
+    # Delegate to a method
+    class MyModule
+      extend SleepingKingStudios::Tools::Delegator
+
+      def my_service
+        MyService.new
+      end method my_service
+
+      delegate :my_method, :to => :my_service
+    end class
+
+    # Delegate to an instance variable
+    class MyModule
+      extend SleepingKingStudios::Tools::Delegator
+
+      def initialize
+        @my_service = MyService.new
+      end constructor
+
+      delegate :my_method, :to => :@my_service
+    end class
+
+Expects one or more method names and a delegation target, which can be an object literal, or the name of an method or instance variable as a String or Symbol. Defines a wrapper method to delegate implementation of the specified method or methods to an object, to the object at the another specified method, or to the object at the specified instance variable.
+
+#### `::wrap_delegate`
+
+Wraps a delegate object by automatically delegating each method that is defined on the delegate class from the instance to the delegate. The
+delegate can be specified with an object literal or with the name of an instance method or instance variable.
+
+Only methods that are defined at the time #wrap_delegate is called will be delegated, so make sure to call #wrap_delegate after loading any gems or libraries that extend your delegate class, such as ActiveSupport.
+
+    # Create a class that wraps a Hash
+    class Errors
+      extend SleepingKingStudios::Tools::Delegator
+
+      wrap_delegate Hash.new { |hsh, key| hsh[key] = Errors.new }, :klass => Hash
+
+      def messages
+        @messages ||= []
+      end # method messages
+    end # class
+
+    errors = Errors.new
+    errors[:post].messages << "title can't be blank"
+
+Expects a delegation target and optionally a class or module (to determine which methods to delegate), as well as optional :except and :only arrays to limit which methods are delegated. The delegation target can be an object literal, or the name of an method or instance variable as a String or Symbol (in which case a class or module must be specified in :klass or an ArgumentError will be raised).
 
 ### Semantic Version
 
-    require 'sleeping_king_studios/tools/semantic_version'
+    require 'sleeping_king_studios/tools/toolbox/semantic_version'
 
 Module mixin for using semantic versioning (see http://semver.org) with helper methods for generating strict and gem-compatible version strings.
 
     module Version
-      extend SleepingKingStudios::Tools::SemanticVersion
+      extend SleepingKingStudios::Tools::Toolbox::SemanticVersion
 
       MAJOR = 3
       MINOR = 1

data/lib/sleeping_king_studios/tools/array_tools.rb

@@ -8,6 +8,28 @@ module SleepingKingStudios::Tools
   module ArrayTools
     extend self
 
+    ARRAY_METHODS = [:[], :count, :each].freeze
+    OTHER_METHODS = [:each_key, :each_pair].freeze
+
+    # Returns true if the object is or appears to be an Array.
+    #
+    # @param ary [Object] The object to test.
+    #
+    # @return [Boolean] True if the object is an Array, otherwise false.
+    def array? ary
+      return true if Array === ary
+
+      ARRAY_METHODS.each do |method_name|
+        return false unless ary.respond_to?(method_name)
+      end # each
+
+      OTHER_METHODS.each do |method_name|
+        return false if ary.respond_to?(method_name)
+      end # each
+
+      true
+    end # method array?
+
     # Separates the array into two arrays, the first containing all items in the
     # original array that matches the provided block, and the second containing
     # all items in the original array that do not match the provided block.
@@ -96,6 +118,17 @@ module SleepingKingStudios::Tools
       ary.map { |obj| ObjectTools.deep_dup obj }
     end # method deep_dup
 
+    # Freezes the array and performs a deep freeze on each array item.
+    #
+    # @param [Array] ary The object to freeze.
+    def deep_freeze ary
+      require_array! ary
+
+      ary.freeze
+
+      ary.each { |obj| ObjectTools.deep_freeze obj }
+    end # method deep_freeze
+
     # Accepts a list of values and returns a human-readable string of the
     # values, with the format based on the number of items.
     #
@@ -133,9 +166,11 @@ module SleepingKingStudios::Tools
     # @raise ArgumentError If the first argument is not an Array-like object.
     #
     # @return [String] The formatted string.
-    def humanize_list ary, options = {}
+    def humanize_list ary, options = {}, &block
       require_array! ary
 
+      ary = ary.map(&block) if block_given?
+
       separator = options.fetch(:separator, ', ')
       last_separator = options.fetch(:last_separator, ' and ')
 
@@ -157,6 +192,35 @@ module SleepingKingStudios::Tools
       end # case
     end # method humanize_list
 
+    # Returns true if the array is immutable, i.e. the array is frozen and each
+    # array item is immutable.
+    #
+    # @param ary [Array] The array to test.
+    #
+    # @return [Boolean] True if the array is immutable, otherwise false.
+    #
+    # @see ObjectTools#immutable?
+    def immutable? ary
+      require_array! ary
+
+      return false unless ary.frozen?
+
+      ary.each { |item| return false unless ObjectTools.immutable?(item) }
+
+      true
+    end # method immutable?
+
+    # Returns true if the array is mutable.
+    #
+    # @param ary [Array] The array to test.
+    #
+    # @return [Boolean] True if the array is mutable, otherwise false.
+    #
+    # @see #immutable?
+    def mutable? ary
+      !immutable?(ary)
+    end # method mutable?
+
     # Accepts an array, a start value, a number of items to delete, and zero or
     # more items to insert at that index. Deletes the specified number of items,
     # then inserts the given items at the index and returns the array of deleted
@@ -208,9 +272,9 @@ module SleepingKingStudios::Tools
     private
 
     def require_array! value
-      methods = %i([] count each)
+      return if array?(value)
 
-      raise ArgumentError.new('argument must be an array') unless methods.reduce(true) { |memo, method_name| memo && value.respond_to?(method_name) }
+      raise ArgumentError, 'argument must be an array', caller[1..-1]
     end # method require_array
   end # module
 end # module

data/lib/sleeping_king_studios/tools/core_tools.rb

@@ -32,5 +32,18 @@ module SleepingKingStudios::Tools
 
       Kernel.warn str
     end # method deprecate
+
+    # Expands each file pattern and requires each file.
+    def require_each *file_patterns
+      file_patterns.each do |file_pattern|
+        if file_pattern.include?('*')
+          Dir[file_pattern].each do |file_name|
+            Kernel.require file_name
+          end # each
+        else
+          Kernel.require file_pattern
+        end # unless
+      end # each
+    end # method require_each
   end # module
 end # module

data/lib/sleeping_king_studios/tools/hash_tools.rb

@@ -8,6 +8,8 @@ module SleepingKingStudios::Tools
   module HashTools
     extend self
 
+    HASH_METHODS = [:[], :count, :each, :each_key, :each_pair].freeze
+
     # Creates a deep copy of the object by returning a new Hash with deep
     # copies of each key and value.
     #
@@ -19,5 +21,60 @@ module SleepingKingStudios::Tools
         copy[ObjectTools.deep_dup key] = ObjectTools.deep_dup(value)
       end # each
     end # method deep_dup
+
+    # Freezes the hash and performs a deep freeze on each hash key and
+    # value.
+    #
+    # @param [Hash] hsh The object to freeze.
+    def deep_freeze hsh
+      hsh.freeze
+
+      hsh.each do |key, value|
+        ObjectTools.deep_freeze key
+        ObjectTools.deep_freeze value
+      end # each
+    end # method deep_freeze
+
+    # Returns true if the object is or appears to be a Hash.
+    #
+    # @param hsh [Object] The object to test.
+    #
+    # @return [Boolean] True if the object is a Hash, otherwise false.
+    def hash? hsh
+      return true if Hash === hsh
+
+      HASH_METHODS.each do |method_name|
+        return false unless hsh.respond_to?(method_name)
+      end # each
+
+      true
+    end # method hash?
+
+    # Returns true if the hash is immutable, i.e. if the hash is frozen and each
+    # hash key and hash value are immutable.
+    #
+    # @param hsh [Hash] The hash to test.
+    #
+    # @return [Boolean] True if the hash is immutable, otherwise false.
+    def immutable? hsh
+      return false unless hsh.frozen?
+
+      hsh.each do |key, value|
+        return false unless ObjectTools.immutable?(key) && ObjectTools.immutable?(value)
+      end # each
+
+      true
+    end # method immutable
+
+    # Returns true if the hash is mutable.
+    #
+    # @param hsh [Array] The hash to test.
+    #
+    # @return [Boolean] True if the hash is mutable, otherwise false.
+    #
+    # @see #immutable?
+    def mutable? hsh
+      !immutable?(hsh)
+    end # method mutable?
   end # module
 end # module

data/lib/sleeping_king_studios/tools/integer_tools.rb

@@ -66,6 +66,15 @@ module SleepingKingStudios::Tools
       integer.to_s(base).split('')
     end # method digits
 
+    # 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?
+
     # Returns the singular or the plural value, depending on the provided
     # item count.
     #

data/lib/sleeping_king_studios/tools/object_tools.rb

@@ -21,6 +21,14 @@ 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, **kwargs, &block
+      unless block_given?
+        if kwargs.empty?
+          return base.instance_exec *args, &proc
+        else
+          return base.instance_exec *args, **kwargs, &proc
+        end # if-else
+      end # unless
+
       temporary_method_name = :__sleeping_king_studios_tools_object_tools_temporary_method_for_applying_proc__
 
       metaclass = class << base; self; end
@@ -49,15 +57,34 @@ module SleepingKingStudios::Tools
       case obj
       when FalseClass, Fixnum, Float, NilClass, Symbol, TrueClass
         obj
-      when Array
+      when ->(_) { ArrayTools.array?(obj) }
         ArrayTools.deep_dup obj
-      when Hash
+      when ->(_) { HashTools.hash?(obj) }
         HashTools.deep_dup obj
       else
         obj.respond_to?(:deep_dup) ? obj.deep_dup : obj.dup
       end # case
     end # method deep_dup
 
+    # 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.
+    def deep_freeze obj
+      case obj
+      when FalseClass, Fixnum, Float, NilClass, Symbol, TrueClass
+        # Object is inherently immutable; do nothing here.
+      when ->(_) { ArrayTools.array?(obj) }
+        ArrayTools.deep_freeze(obj)
+      when ->(_) { HashTools.hash?(obj) }
+        HashTools.deep_freeze obj
+      else
+        obj.respond_to?(:deep_freeze) ? obj.deep_freeze : obj.freeze
+      end # case
+    end # method deep_freeze
+
     # Returns the object's eigenclass.
     #
     # @param [Object] object The object for which an eigenclass is required.
@@ -68,6 +95,50 @@ module SleepingKingStudios::Tools
     end # method eigenclass
     alias_method :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.
+    #
+    # @param obj [Object] The object to test.
+    #
+    # @return [Boolean] True if the object is immutable, otherwise false.
+    def immutable? obj
+      case obj
+      when NilClass, FalseClass, TrueClass, Numeric, Symbol
+        true
+      when ->(_) { ArrayTools.array?(obj) }
+        ArrayTools.immutable? obj
+      when ->(_) { HashTools.hash?(obj) }
+        HashTools.immutable? obj
+      else
+        obj.frozen?
+      end # case
+    end # method immutable?
+
+    # Returns true if the object is mutable.
+    #
+    # @param obj [Object] The object to test.
+    #
+    # @return [Boolean] True if the object is mutable, otherwise false.
+    #
+    # @see #immutable?
+    def mutable? obj
+      !immutable?(obj)
+    end # method mutable?
+
+    # 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.
+    #
+    # @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?
+
     # As #send, but returns nil if the object does not respond to the method.
     #
     # @param [Object] object The receiver of the message.

data/lib/sleeping_king_studios/tools/semantic_version.rb

@@ -1,108 +1,15 @@
 # lib/sleeping_king_studios/tools/semantic_version.rb
 
-module SleepingKingStudios
-  module Tools
-    # Helper for generating semantic version strings with optional prerelease and
-    # build parameters.
-    #
-    # @example
-    #   module Version
-    #     extend SleepingKingStudios::Tools::SemanticVersion
-    #
-    #     MAJOR = 3
-    #     MINOR = 1
-    #     PATCH = 4
-    #     PRERELEASE = 'beta'
-    #     BUILD = 1
-    #   end # module
-    #
-    #   VERSION = Version.to_gem_version
-    #
-    # @see http://semver.org
-    module SemanticVersion
-      # Error class for handling missing constants in a version definition.
-      class InvalidVersionError < StandardError; end
+require 'sleeping_king_studios/tools/core_tools'
 
-      # Concatenates the MAJOR, MINOR, and PATCH constant values with PRERELEASE
-      # and BUILD (if available) to generate a modified semantic version string
-      # compatible with Rubygems. The major, minor, patch, prerelease, and build
-      # values (if available) are separated by dots (.).
-      #
-      # @example
-      #   module Version
-      #     extend SleepingKingStudios::Tools::SemanticVersion
-      #
-      #     MAJOR = 3
-      #     MINOR = 1
-      #     PATCH = 4
-      #     PRERELEASE = 'beta'
-      #     BUILD = 1
-      #   end # module
-      #
-      #   VERSION = Version.to_gem_version
-      #   #=> '3.1.4.beta.1'
-      #
-      # @return [String] The modified semantic version string.
-      #
-      # @raise InvalidVersionError If MAJOR, MINOR, or PATCH is undefined.
-      def to_gem_version
-        str = "#{const_fetch :MAJOR}.#{const_fetch :MINOR}.#{const_fetch :PATCH}"
+SleepingKingStudios::Tools::CoreTools.deprecate(
+  'SleepingKingStudios::Tools::SemanticVersion',
+  :message => 'Use SleepingKingStudios::Tools::Toolbox::SemanticVersion instead.'
+) # end deprecate
 
-        prerelease = const_fetch(:PRERELEASE, nil)
-        str << ".#{prerelease}" unless prerelease.nil? || prerelease.empty?
+require 'sleeping_king_studios/tools/toolbox/semantic_version'
 
-        build = const_fetch(:BUILD, nil)
-        str << ".#{build}" unless build.nil? || build.empty?
-
-        str
-      end # method to_version
-
-      # Concatenates the MAJOR, MINOR, and PATCH constant values with PRERELEASE
-      # and BUILD (if available) to generate a semantic version string. The
-      # major, minor, and patch values are separated by dots (.), then the
-      # prerelease (if available) preceded by a hyphen (-), and the build (if
-      # available) preceded by a plus (+).
-      #
-      # @example
-      #   module Version
-      #     extend SleepingKingStudios::Tools::SemanticVersion
-      #
-      #     MAJOR = 3
-      #     MINOR = 1
-      #     PATCH = 4
-      #     PRERELEASE = 'beta'
-      #     BUILD = 1
-      #   end # module
-      #
-      #   VERSION = Version.to_version
-      #   #=> '3.1.4-beta+1'
-      #
-      # @return [String] The semantic version string.
-      #
-      # @raise InvalidVersionError If MAJOR, MINOR, or PATCH is undefined.
-      def to_version
-        str = "#{const_fetch :MAJOR}.#{const_fetch :MINOR}.#{const_fetch :PATCH}"
-
-        prerelease = const_fetch(:PRERELEASE, nil)
-        str << "-#{prerelease}" unless prerelease.nil? || prerelease.empty?
-
-        build = const_fetch(:BUILD, nil)
-        str << "+#{build}" unless build.nil? || build.empty?
-
-        str
-      end # method to_version
-
-      private
-
-      FETCH_DEFAULT = Object.new.freeze
-
-      def const_fetch name, default = FETCH_DEFAULT
-        if self.const_defined?(name)
-          return self.const_get(name).to_s
-        elsif default == FETCH_DEFAULT
-          raise InvalidVersionError.new "undefined constant for #{name.downcase} version"
-        end # if-else
-      end # method const_fetch
-    end # module
-  end # module
+module SleepingKingStudios::Tools
+  # (see SleepingKingStudios::Tools::Toolbox::SemanticVersion)
+  SemanticVersion = Toolbox::SemanticVersion
 end # module

data/lib/sleeping_king_studios/tools/string_tools.rb

@@ -10,6 +10,21 @@ module SleepingKingStudios::Tools
 
     autoload :PluralInflector, 'sleeping_king_studios/tools/string_tools/plural_inflector'
 
+    # Converts a lowercase, underscore-separated string to CamelCase.
+    #
+    # @param str [String] The string to convert.
+    #
+    # @return [String] The converted string.
+    #
+    # @see ActiveSupport::Inflector#camelize.
+    def camelize str
+      require_string! str
+
+      str = str.dup
+      str.gsub!(/(\b|[_-])([a-z])/) { |match| $2.upcase }
+      str
+    end # method camelize
+
     # (see PluralInflector#define_irregular_word)
     def define_irregular_word singular, plural
       plural_inflector.define_irregular_word singular, plural
@@ -76,6 +91,15 @@ module SleepingKingStudios::Tools
       plural_inflector.singularize str
     end # method singularize
 
+    # 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?
+
     # Converts a mixed-case string expression to a lowercase, underscore
     # separated string.
     #
@@ -102,7 +126,9 @@ module SleepingKingStudios::Tools
     end # method plural_inflector
 
     def require_string! value
-      raise ArgumentError.new('argument must be a string') unless value.is_a?(String)
+      return if string?(value)
+
+      raise ArgumentError, 'argument must be a string', caller[1..-1]
     end # method require_array
   end # module
 end # module

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

@@ -0,0 +1,175 @@
+# lib/sleeping_king_studios/tools/toolbox/delegator.rb
+
+require 'sleeping_king_studios/tools/toolbox'
+
+module SleepingKingStudios::Tools::Toolbox
+  # Module for extending classes with basic delegation. Supports passing
+  # arguments, keywords, and blocks to the delegated method.
+  #
+  # @example
+  #   class MyClass
+  #     extend SleepingKingStudios::Tools::Delegator
+  #
+  #     delegate :my_method, :to => MyService
+  #   end # class
+  module Delegator
+    # 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.
+    #
+    # @example Delegate to an object
+    #   class MyModule
+    #     extend SleepingKingStudios::Tools::Delegator
+    #
+    #     delegate :my_method, :to => MyService
+    #   end # class
+    #
+    # @example Delegate to a method
+    #   class MyModule
+    #     extend SleepingKingStudios::Tools::Delegator
+    #
+    #     def my_service
+    #       MyService.new
+    #     end # method my_service
+    #
+    #     delegate :my_method, :to => :my_service
+    #   end # class
+    #
+    # @example Delegate to an instance variable
+    #   class MyModule
+    #     extend SleepingKingStudios::Tools::Delegator
+    #
+    #     def initialize
+    #       @my_service = MyService.new
+    #     end # constructor
+    #
+    #     delegate :my_method, :to => :@my_service
+    #   end # class
+    #
+    # @param method_names [Array<String, Symbol>] The names of the methods to
+    #   delegate.
+    # @param to [Object, String, Symbol] The object, method, or instance
+    #   variable to delegate to. If the object is not a string or symbol, the
+    #   generated method will call `method_name` on the object. If the object is
+    #   a string or symbol, but does not start with an `@`, the generated method
+    #   will call the method of that name on the instance, and then call
+    #   `method_name` on the result. If the object is a string or symbol and
+    #   does start with an `@`, the generated method will get the instance
+    #   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
+
+      method_names.each do |method_name|
+        delegate_method method_name, to, { :allow_nil => !!allow_nil }
+      end # each
+    end # method delegate
+
+    # Wraps a delegate object by automatically delegating each method that is
+    # defined on the delegate class from the instance to the delegate. The
+    # delegate can be specified with an object literal or with the name of an
+    # instance method or instance variable.
+    #
+    # Only methods that are defined at the time #wrap_delegate is called will be
+    # delegated, so make sure to call #wrap_delegate after loading any gems or
+    # libraries that extend your delegate class, such as ActiveSupport.
+    #
+    # @example Create a class that wraps a Hash
+    #   class Errors
+    #     extend SleepingKingStudios::Tools::Delegator
+    #
+    #     wrap_delegate Hash.new { |hsh, key| hsh[key] = Errors.new }, :klass => Hash
+    #
+    #     def messages
+    #       @messages ||= []
+    #     end # method messages
+    #   end # class
+    #
+    #   errors = Errors.new
+    #   errors[:post].messages << "title can't be blank"
+    #
+    # @param target [Object, String, Symbol] The object, method, or instance
+    #   variable to delegate to. If the object is not a string or symbol, the
+    #   generated method will call each method on the object. If the object is
+    #   a string or symbol, but does not start with an `@`, the generated method
+    #   will call the method of that name on the instance, and then call
+    #   each method on the result. If the object is a string or symbol and
+    #   does start with an `@`, the generated method will get the instance
+    #   variable of that name and call each method on the result.
+    # @param klass [Module] The class or module whose methods are delegated to
+    #   the target. If target is the name of an instance variable or an instance
+    #   method, the klass must be specified. If target is an object literal, the
+    #   klass is optional, in which case all methods from the target will be
+    #   delegated to the target.
+    # @param except [Array<String, Symbol>] An optional list of method names.
+    #   Any names on the list will not be delegated, even if the method is
+    #   defined by the klass or defined on the target literal.
+    # @param only [Array<String, Symbol>] An optional list of method names.
+    #   Only names on the list will be delegated, and only if the method is
+    #   defined by the klass or defined on the target literal.
+    #
+    # @raise ArgumentError if no delegate is specified.
+    # @raise ArgumentError if the target is the name of an instance method or an
+    #   instance variable and no klass is specified.
+    # @raise ArgumentError if the target is an object literal that does not
+    #   belong to the specified klass.
+    #
+    # @see #delegate
+    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
+
+        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'
+      else
+        method_names = target.methods - Object.new.methods
+      end # if-elsif-else
+
+      if except.is_a?(Array) && !except.empty?
+        method_names = method_names - except.map(&:intern)
+      end # if
+
+      if only.is_a?(Array) && !only.empty?
+        method_names = method_names & only.map(&:intern)
+      end # if
+
+      delegate *method_names, :to => target
+    end # method wrap_delegate
+
+    private
+
+    def delegate_method method_name, target, options = {}
+      if target.is_a?(String) || target.is_a?(Symbol)
+        target = target.intern
+
+        if target.to_s =~ /\A@/
+          define_method method_name do |*args, &block|
+            receiver = instance_variable_get(target)
+
+            return nil if receiver.nil? && options[:allow_nil]
+
+            receiver.send(method_name, *args, &block)
+          end # define_method
+        else
+          define_method method_name do |*args, &block|
+            receiver = send(target)
+
+            return nil if receiver.nil? && options[:allow_nil]
+
+            receiver.send(method_name, *args, &block)
+          end # define_method
+        end # if-else
+      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

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

@@ -0,0 +1,108 @@
+# lib/sleeping_king_studios/tools/toolbox/semantic_version.rb
+
+require 'sleeping_king_studios/tools/toolbox'
+
+module SleepingKingStudios::Tools::Toolbox
+  # Helper for generating semantic version strings with optional prerelease and
+  # build parameters.
+  #
+  # @example
+  #   module Version
+  #     extend SleepingKingStudios::Tools::SemanticVersion
+  #
+  #     MAJOR = 3
+  #     MINOR = 1
+  #     PATCH = 4
+  #     PRERELEASE = 'beta'
+  #     BUILD = 1
+  #   end # module
+  #
+  #   VERSION = Version.to_gem_version
+  #
+  # @see http://semver.org
+  module SemanticVersion
+    # Error class for handling missing constants in a version definition.
+    class InvalidVersionError < StandardError; end
+
+    # Concatenates the MAJOR, MINOR, and PATCH constant values with PRERELEASE
+    # and BUILD (if available) to generate a modified semantic version string
+    # compatible with Rubygems. The major, minor, patch, prerelease, and build
+    # values (if available) are separated by dots (.).
+    #
+    # @example
+    #   module Version
+    #     extend SleepingKingStudios::Tools::SemanticVersion
+    #
+    #     MAJOR = 3
+    #     MINOR = 1
+    #     PATCH = 4
+    #     PRERELEASE = 'beta'
+    #     BUILD = 1
+    #   end # module
+    #
+    #   VERSION = Version.to_gem_version
+    #   #=> '3.1.4.beta.1'
+    #
+    # @return [String] The modified semantic version string.
+    #
+    # @raise InvalidVersionError If MAJOR, MINOR, or PATCH is undefined.
+    def to_gem_version
+      str = "#{const_fetch :MAJOR}.#{const_fetch :MINOR}.#{const_fetch :PATCH}"
+
+      prerelease = const_fetch(:PRERELEASE, nil)
+      str << ".#{prerelease}" unless prerelease.nil? || prerelease.empty?
+
+      build = const_fetch(:BUILD, nil)
+      str << ".#{build}" unless build.nil? || build.empty?
+
+      str
+    end # method to_version
+
+    # Concatenates the MAJOR, MINOR, and PATCH constant values with PRERELEASE
+    # and BUILD (if available) to generate a semantic version string. The
+    # major, minor, and patch values are separated by dots (.), then the
+    # prerelease (if available) preceded by a hyphen (-), and the build (if
+    # available) preceded by a plus (+).
+    #
+    # @example
+    #   module Version
+    #     extend SleepingKingStudios::Tools::SemanticVersion
+    #
+    #     MAJOR = 3
+    #     MINOR = 1
+    #     PATCH = 4
+    #     PRERELEASE = 'beta'
+    #     BUILD = 1
+    #   end # module
+    #
+    #   VERSION = Version.to_version
+    #   #=> '3.1.4-beta+1'
+    #
+    # @return [String] The semantic version string.
+    #
+    # @raise InvalidVersionError If MAJOR, MINOR, or PATCH is undefined.
+    def to_version
+      str = "#{const_fetch :MAJOR}.#{const_fetch :MINOR}.#{const_fetch :PATCH}"
+
+      prerelease = const_fetch(:PRERELEASE, nil)
+      str << "-#{prerelease}" unless prerelease.nil? || prerelease.empty?
+
+      build = const_fetch(:BUILD, nil)
+      str << "+#{build}" unless build.nil? || build.empty?
+
+      str
+    end # method to_version
+
+    private
+
+    FETCH_DEFAULT = Object.new.freeze
+
+    def const_fetch name, default = FETCH_DEFAULT
+      if self.const_defined?(name)
+        return self.const_get(name).to_s
+      elsif default == FETCH_DEFAULT
+        raise InvalidVersionError.new "undefined constant for #{name.downcase} version"
+      end # if-else
+    end # method const_fetch
+  end # module
+end # module

data/lib/sleeping_king_studios/tools/toolbox.rb

@@ -0,0 +1,10 @@
+# lib/sleeping_king_studios/tools/toolbox.rb
+
+require 'sleeping_king_studios/tools'
+
+module SleepingKingStudios::Tools
+  # Namespace for common objects or patterns that are useful across projects but
+  # are larger than or do not fit the functional paradigm of the tools.*
+  # pattern.
+  module Toolbox; end
+end # module

data/lib/sleeping_king_studios/tools/version.rb

@@ -1,6 +1,6 @@
 # lib/sleeping_king_studios/tools/version.rb
 
-require 'sleeping_king_studios/tools/semantic_version'
+require 'sleeping_king_studios/tools/toolbox/semantic_version'
 
 module SleepingKingStudios
   module Tools
@@ -8,15 +8,15 @@ module SleepingKingStudios
     #
     # @see http://semver.org
     module Version
-      extend SleepingKingStudios::Tools::SemanticVersion
+      extend SleepingKingStudios::Tools::Toolbox::SemanticVersion
 
       private
 
       MAJOR      = 0
-      MINOR      = 4
+      MINOR      = 5
       PATCH      = 0
-      PRERELEASE = nil
-      BUILD      = nil
+      PRERELEASE = :rc
+      BUILD      = 0
     end # module
 
     VERSION = Version.to_gem_version

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sleeping_king_studios-tools
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0.rc.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-08-22 00:00:00.000000000 Z
+date: 2016-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -103,6 +103,9 @@ files:
 - lib/sleeping_king_studios/tools/string_tools.rb
 - lib/sleeping_king_studios/tools/string_tools/plural_inflector.rb
 - lib/sleeping_king_studios/tools/toolbelt.rb
+- lib/sleeping_king_studios/tools/toolbox.rb
+- lib/sleeping_king_studios/tools/toolbox/delegator.rb
+- lib/sleeping_king_studios/tools/toolbox/semantic_version.rb
 - lib/sleeping_king_studios/tools/version.rb
 homepage: http://sleepingkingstudios.com
 licenses:
@@ -119,9 +122,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.5.1