hashie 4.1.0 → 5.2.0

data/lib/hashie/extensions/symbolize_keys.rb

@@ -1,31 +1,76 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
+    # Extends a Hash with the ability to convert its keys to symbols.
+    # Keys that do not respond to #to_sym are preserved.
+    #
+    # @example Extend a pre-existing Hash object
+    #   hash = { 'test' => 'value' }
+    #   hash.extend(Hashie::Extensions::SymbolizeKeys)
+    #   hash.symbolize_keys!
+    #   hash # => { test: 'value' }
+    #
+    # @example Create a Hash class with this capability
+    #   class SymbolizableHash < Hash
+    #     include Hashie::Extensions::SymbolizeKeys
+    #   end
+    #
+    #   hash = SymbolizableHash.new
+    #   hash['test'] = 'value'
+    #   hash.symbolize_keys!
+    #   hash # => { test: 'value' }
+    #
+    # @example Use the module function to symbolize keys in a hash
+    #   hash = { 'test' => 'value', 123 => 'number' }
+    #   Hashie::Extensions::SymbolizeKeys.symbolize_keys!(hash)
+    #   hash # => { test: 'value', 123 => 'number' }
     module SymbolizeKeys
-      # Convert all keys in the hash to symbols.
+      # Converts keys in the hash and nested hashes and arrays to symbols.
       #
-      # @example
-      #   test = {'abc' => 'def'}
+      # @example Convert keys in place
+      #   test = { 'abc' => [{ 'def' => 'value' }] }
+      #   test.extend(Hashie::Extensions::SymbolizeKeys)
       #   test.symbolize_keys!
-      #   test # => {:abc => 'def'}
+      #   test # => { abc: [{ def: 'value' }] }
+      #
+      # @api public
+      # @return [Hash] the receiver with its keys symbolized where possible
       def symbolize_keys!
         SymbolizeKeys.symbolize_keys!(self)
         self
       end
 
-      # Return a new hash with all keys converted
-      # to symbols.
+      # Returns a shallow copy with keys recursively converted to symbols.
+      # Nested hashes and arrays are shared with the original and are modified.
+      #
+      # @example Copy a flat hash without modifying the original
+      #   test = { 'abc' => 'def' }
+      #   test.extend(Hashie::Extensions::SymbolizeKeys)
+      #   test.symbolize_keys # => { abc: 'def' }
+      #   test # => { 'abc' => 'def' }
+      #
+      # @example Nested values are shared, not deep copied
+      #   test = { 'abc' => [{ 'def' => 'value' }] }
+      #   test.extend(Hashie::Extensions::SymbolizeKeys)
+      #   test.symbolize_keys # => { abc: [{ def: 'value' }] }
+      #   test # => { 'abc' => [{ def: 'value' }] }
+      #
+      # @api public
+      # @return [Hash] a shallow copy with symbolized keys
       def symbolize_keys
         SymbolizeKeys.symbolize_keys(self)
       end
 
+      # @example Add recursive conversion functions to an object
+      #   converter = Object.new.extend(Hashie::Extensions::SymbolizeKeys::ClassMethods)
+      #   converter.symbolize_keys('user' => { 'name' => 'Ada' }) # => { user: { name: 'Ada' } }
       module ClassMethods
         # Symbolize all keys recursively within nested
         # hashes and arrays.
         # @api private
         def symbolize_keys_recursively!(object)
           case object
-          when self.class
-            symbolize_keys!(object)
           when ::Array
             object.each do |i|
               symbolize_keys_recursively!(i)
@@ -35,25 +80,36 @@ module Hashie
           end
         end
 
-        # Convert all keys in hash to symbols.
+        # Converts keys in a hash recursively to symbols, in place.
         #
+        # @example Convert keys through Hashie's module function
+        #   test = { 'abc' => 'def' }
+        #   Hashie.symbolize_keys!(test)
+        #   test # => { abc: 'def' }
+        #
+        # @api public
         # @param [Hash] hash
-        # @example
-        #   test = {'abc' => 'def'}
-        #   Hashie.symbolize_keys! test
-        #   test # => {:abc => 'def'}
+        # @return [Hash] the passed hash with symbolized keys
         def symbolize_keys!(hash)
           hash.extend(Hashie::Extensions::SymbolizeKeys) unless hash.respond_to?(:symbolize_keys!)
           hash.keys.each do |k| # rubocop:disable Performance/HashEachMethods
             symbolize_keys_recursively!(hash[k])
-            hash[k.to_sym] = hash.delete(k)
+            hash[convert_key(k)] = hash.delete(k)
           end
           hash
         end
 
-        # Return a copy of hash with all keys converted
-        # to symbols.
-        # @param [::Hash] hash
+        # Returns a shallow copy of a hash with recursively symbolized keys.
+        # Nested hashes and arrays are shared with the original and are modified.
+        #
+        # @example Copy keys through Hashie's module function
+        #   test = { 'abc' => 'def' }
+        #   Hashie.symbolize_keys(test) # => { abc: 'def' }
+        #   test # => { 'abc' => 'def' }
+        #
+        # @api public
+        # @param [Hash] hash
+        # @return [Hash] a shallow copy with symbolized keys
         def symbolize_keys(hash)
           copy = hash.dup
           copy.extend(Hashie::Extensions::SymbolizeKeys) unless copy.respond_to?(:symbolize_keys!)
@@ -61,6 +117,17 @@ module Hashie
             symbolize_keys!(new_hash)
           end
         end
+
+        private
+
+        # Converts a key to a symbol, if possible
+        #
+        # @api private
+        # @param [<K>] key the key to attempt convert to a symbol
+        # @return [Symbol, K]
+        def convert_key(key)
+          key.respond_to?(:to_sym) ? key.to_sym : key
+        end
       end
 
       class << self

data/lib/hashie/hash.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'hashie/extensions/stringify_keys'
 require 'hashie/extensions/pretty_inspect'
 
@@ -5,24 +7,34 @@ module Hashie
   # A Hashie Hash is simply a Hash that has convenience
   # functions baked in such as stringify_keys that may
   # not be available in all libraries.
+  #
+  # @example Convert keys using the built-in extensions
+  #   Hashie::Hash[name: 'Ada'].stringify_keys # => { 'name' => 'Ada' }
   class Hash < ::Hash
     include Hashie::Extensions::PrettyInspect
     include Hashie::Extensions::StringifyKeys
 
     # Convert this hash into a Mash
+    #
+    # @example Read converted data through methods
+    #   Hashie::Hash[name: 'Ada'].to_mash.name # => 'Ada'
     def to_mash
       ::Hashie::Mash.new(self)
     end
 
     # Converts a mash back to a hash (with stringified or symbolized keys)
+    #
+    # @example Recursively convert nested hashes and their keys
+    #   hash = Hashie::Hash[user: Hashie::Hash[name: 'Ada']]
+    #   hash.to_hash(stringify_keys: true) # => { 'user' => { 'name' => 'Ada' } }
     def to_hash(options = {})
       out = {}
       each_key do |k|
         assignment_key =
           if options[:stringify_keys]
             k.to_s
-          elsif options[:symbolize_keys]
-            k.to_s.to_sym
+          elsif options[:symbolize_keys] && k.respond_to?(:to_sym)
+            k.to_sym
           else
             k
           end
@@ -39,6 +51,10 @@ module Hashie
     end
 
     # The C generator for the json gem doesn't like mashies
+    #
+    # @example Serialize as an ordinary JSON object
+    #   require 'json'
+    #   JSON.parse(Hashie::Hash[name: 'Ada'].to_json) # => { 'name' => 'Ada' }
     def to_json(*args)
       to_hash.to_json(*args)
     end

data/lib/hashie/logger.rb

@@ -1,17 +1,34 @@
+# frozen_string_literal: true
+
 require 'logger'
 
 module Hashie
   # The logger that Hashie uses for reporting errors.
   #
   # @return [Logger]
+  #
+  # @example Obtain the logger used for warnings
+  #   Hashie.logger.respond_to?(:warn) # => true
   def self.logger
-    @logger ||= Logger.new(STDOUT)
+    @logger ||= Logger.new($stdout)
   end
 
   # Sets the logger that Hashie uses for reporting errors.
   #
   # @param logger [Logger] The logger to set as Hashie's logger.
   # @return [void]
+  #
+  # @example Temporarily capture warnings
+  #   require 'stringio'
+  #   original = Hashie.logger
+  #   begin
+  #     output = StringIO.new
+  #     Hashie.logger = Logger.new(output)
+  #     Hashie.logger.warn('example warning')
+  #     output.string.include?('example warning') # => true
+  #   ensure
+  #     Hashie.logger = original
+  #   end
   def self.logger=(logger)
     @logger = logger
   end