hashie 5.1.0 → 5.2.0

data/lib/hashie/extensions/strict_key_access.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
     # SRP: This extension will fail an error whenever a key is accessed
@@ -19,11 +21,21 @@ module Hashie
     # NOTE: For googlers coming from Python to Ruby, this extension makes a Hash
     # behave more like a "Dictionary".
     #
+    # @example Raise on missing keys
+    #   hash = { name: 'Ada' }.extend(Hashie::Extensions::StrictKeyAccess)
+    #   hash[:name] # => 'Ada'
+    #   expect { hash[:missing] }.to raise_error(KeyError)
     module StrictKeyAccess
+      # @example Explain why defaults are unsupported
+      #   error = Hashie::Extensions::StrictKeyAccess::DefaultError.new
+      #   error.message # => 'Setting or using a default with Hashie::Extensions::StrictKeyAccess does not make sense'
       class DefaultError < StandardError
+        # @example Construct a default-access error
+        #   error = Hashie::Extensions::StrictKeyAccess::DefaultError.new
+        #   error.message # => 'Setting or using a default with Hashie::Extensions::StrictKeyAccess does not make sense'
         def initialize
-          super('Setting or using a default with Hashie::Extensions::StrictKeyAccess'\
-                ' does not make sense'
+          super('Setting or using a default with Hashie::Extensions::StrictKeyAccess ' \
+                'does not make sense'
           )
         end
       end
@@ -45,31 +57,73 @@ module Hashie
       #     >> a["noes"]
       #       KeyError: key not found: "noes"
       #
+      # @example Fetch an existing value without a default fallback
+      #   hash = { name: 'Ada' }.extend(Hashie::Extensions::StrictKeyAccess)
+      #   hash[:name] # => 'Ada'
+      #   expect { hash[:missing] }.to raise_error(KeyError)
       def [](key)
         fetch(key)
       end
 
+      # @example Reject reading the default value
+      #   hash = {}.extend(Hashie::Extensions::StrictKeyAccess)
+      #   error_class = begin
+      #     hash.default
+      #   rescue Hashie::Extensions::StrictKeyAccess::DefaultError => error
+      #     error.class
+      #   end
+      #   error_class # => Hashie::Extensions::StrictKeyAccess::DefaultError
       def default(_ = nil)
         raise DefaultError
       end
 
+      # @example Reject assigning a default value
+      #   hash = {}.extend(Hashie::Extensions::StrictKeyAccess)
+      #   rejected = begin
+      #     hash.default = 'unknown'
+      #     false
+      #   rescue Hashie::Extensions::StrictKeyAccess::DefaultError
+      #     true
+      #   end
+      #   rejected # => true
       def default=(_)
         raise DefaultError
       end
 
+      # @example Reject reading a default proc
+      #   hash = {}.extend(Hashie::Extensions::StrictKeyAccess)
+      #   rejected = begin
+      #     hash.default_proc
+      #     false
+      #   rescue Hashie::Extensions::StrictKeyAccess::DefaultError
+      #     true
+      #   end
+      #   rejected # => true
       def default_proc
         raise DefaultError
       end
 
+      # @example Reject assigning a default proc
+      #   hash = {}.extend(Hashie::Extensions::StrictKeyAccess)
+      #   rejected = begin
+      #     hash.default_proc = ->(_hash, _key) { 'unknown' }
+      #     false
+      #   rescue Hashie::Extensions::StrictKeyAccess::DefaultError
+      #     true
+      #   end
+      #   rejected # => true
       def default_proc=(_)
         raise DefaultError
       end
 
+      # @example Find an existing key and reject missing values
+      #   hash = { name: 'Ada', nil => false }.extend(Hashie::Extensions::StrictKeyAccess)
+      #   hash.key('Ada') # => :name
+      #   hash.key(false) # => nil
+      #   expect { hash.key('Grace') }.to raise_error(KeyError)
       def key(value)
         super.tap do |result|
-          if result.nil? && (!key?(result) || self[result] != value)
-            raise KeyError, "key not found with value of #{value.inspect}"
-          end
+          raise KeyError, "no key found for value `#{value.inspect}`" if result.nil? && (!key?(result) || self[result] != value)
         end
       end
     end

data/lib/hashie/extensions/stringify_keys.rb

@@ -1,31 +1,75 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
+    # Extends a Hash with the ability to convert its keys to strings.
+    #
+    # @example Extend a pre-existing Hash object
+    #   hash = { test: 'value' }
+    #   hash.extend(Hashie::Extensions::StringifyKeys)
+    #   hash.stringify_keys!
+    #   hash # => { 'test' => 'value' }
+    #
+    # @example Create a Hash class with this capability
+    #   class StringifyingHash < Hash
+    #     include Hashie::Extensions::StringifyKeys
+    #   end
+    #
+    #   hash = StringifyingHash.new
+    #   hash[:test] = 'value'
+    #   hash.stringify_keys!
+    #   hash # => { 'test' => 'value' }
+    #
+    # @example Use the module function to stringify keys in a hash
+    #   hash = { test: 'value' }
+    #   Hashie::Extensions::StringifyKeys.stringify_keys!(hash)
+    #   hash # => { 'test' => 'value' }
     module StringifyKeys
-      # Convert all keys in the hash to strings.
+      # Converts all keys in the hash and nested hashes and arrays to strings.
       #
-      # @example
-      #   test = {:abc => 'def'}
+      # @example Convert keys in place
+      #   test = { abc: [{ def: 'value' }] }
+      #   test.extend(Hashie::Extensions::StringifyKeys)
       #   test.stringify_keys!
-      #   test # => {'abc' => 'def'}
+      #   test # => { 'abc' => [{ 'def' => 'value' }] }
+      #
+      # @api public
+      # @return [Hash] the receiver with its keys converted to strings
       def stringify_keys!
         StringifyKeys.stringify_keys!(self)
         self
       end
 
-      # Return a new hash with all keys converted
-      # to strings.
+      # Returns a shallow copy with all keys recursively converted to strings.
+      # 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::StringifyKeys)
+      #   test.stringify_keys # => { 'abc' => 'def' }
+      #   test # => { abc: 'def' }
+      #
+      # @example Nested values are shared, not deep copied
+      #   test = { abc: [{ def: 'value' }] }
+      #   test.extend(Hashie::Extensions::StringifyKeys)
+      #   test.stringify_keys # => { 'abc' => [{ 'def' => 'value' }] }
+      #   test # => { abc: [{ 'def' => 'value' }] }
+      #
+      # @api public
+      # @return [Hash] a shallow copy with stringified keys
       def stringify_keys
         StringifyKeys.stringify_keys(self)
       end
 
+      # @example Add recursive conversion functions to an object
+      #   converter = Object.new.extend(Hashie::Extensions::StringifyKeys::ClassMethods)
+      #   converter.stringify_keys(user: { name: 'Ada' }) # => { 'user' => { 'name' => 'Ada' } }
       module ClassMethods
         # Stringify all keys recursively within nested
         # hashes and arrays.
         # @api private
         def stringify_keys_recursively!(object)
           case object
-          when self.class
-            stringify_keys!(object)
           when ::Array
             object.each do |i|
               stringify_keys_recursively!(i)
@@ -35,13 +79,16 @@ module Hashie
           end
         end
 
-        # Convert all keys in the hash to strings.
+        # Converts all keys in a hash recursively to strings, in place.
+        #
+        # @example Convert keys through Hashie's module function
+        #   test = { abc: 'def' }
+        #   Hashie.stringify_keys!(test)
+        #   test # => { 'abc' => 'def' }
         #
-        # @param [::Hash] hash
-        # @example
-        #   test = {:abc => 'def'}
-        #   test.stringify_keys!
-        #   test # => {'abc' => 'def'}
+        # @api public
+        # @param [Hash] hash
+        # @return [Hash] the passed hash with stringified keys
         def stringify_keys!(hash)
           hash.extend(Hashie::Extensions::StringifyKeys) unless hash.respond_to?(:stringify_keys!)
           hash.keys.each do |k| # rubocop:disable Performance/HashEachMethods
@@ -51,9 +98,17 @@ module Hashie
           hash
         end
 
-        # Return a copy of hash with all keys converted
-        # to strings.
-        # @param [::Hash] hash
+        # Returns a shallow copy of a hash with recursively stringified 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.stringify_keys(test) # => { 'abc' => 'def' }
+        #   test # => { abc: 'def' }
+        #
+        # @api public
+        # @param [Hash] hash
+        # @return [Hash] a shallow copy with stringified keys
         def stringify_keys(hash)
           copy = hash.dup
           copy.extend(Hashie::Extensions::StringifyKeys) unless copy.respond_to?(:stringify_keys!)

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,13 +80,16 @@ 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
@@ -51,9 +99,17 @@ module Hashie
           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!)

data/lib/hashie/hash.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'hashie/extensions/stringify_keys'
 require 'hashie/extensions/pretty_inspect'
 
@@ -5,16 +7,26 @@ 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|
@@ -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