hashie 5.1.0 → 5.2.0

data/lib/hashie/extensions/deep_grep.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Hashie
+  module Extensions
+    # Searches nested hashes and arrays for matching string and symbol keys or values.
+    #
+    # @example Search a nested collection
+    #   hash = { people: [{ name: 'Ada' }] }.extend(Hashie::Extensions::DeepGrep)
+    #   hash.deep_grep(/Ada/) # => [{ name: 'Ada' }]
+    module DeepGrep
+      # @example Match a key and return its subtree
+      #   hash = { user: { name: 'Ada' } }.extend(Hashie::Extensions::DeepGrep)
+      #   hash.deep_grep(/user/) # => [{ user: { name: 'Ada' } }]
+      def deep_grep(pattern)
+        DeepGrep.deep_grep(pattern, self)
+      end
+
+      # Returns key/subtree pairs for matching keys, containing hashes for matching
+      # scalar values, and matching scalar array elements. Matching keys stop descent.
+      #
+      # @example Search an array without extending it
+      #   Hashie::Extensions::DeepGrep.deep_grep(/Ada/, ['Ada', 'Grace']) # => ['Ada']
+      def self.deep_grep(pattern, object)
+        raise ArgumentError, 'pattern must be a Regexp' unless pattern.is_a?(Regexp)
+
+        search(pattern, object, [], {}.compare_by_identity)
+      end
+
+      def self.search(pattern, object, results, ancestors)
+        return results if ancestors.key?(object) ||
+                          !(object.is_a?(::Hash) || object.is_a?(::Array))
+
+        ancestors[object] = true
+        if object.is_a?(::Hash)
+          search_hash(pattern, object, results, ancestors)
+        else
+          search_array(pattern, object, results, ancestors)
+        end
+        ancestors.delete(object)
+        results
+      end
+      private_class_method :search
+
+      def self.search_hash(pattern, object, results, ancestors)
+        results << object if object.any? { |key, value| !matches?(pattern, key) && matches?(pattern, value) }
+        object.each do |key, value|
+          if matches?(pattern, key)
+            results << { key => value }
+          else
+            search(pattern, value, results, ancestors)
+          end
+        end
+      end
+      private_class_method :search_hash
+
+      def self.search_array(pattern, object, results, ancestors)
+        object.each do |value|
+          matches?(pattern, value) ? results << value : search(pattern, value, results, ancestors)
+        end
+      end
+      private_class_method :search_array
+
+      def self.matches?(pattern, value)
+        (value.is_a?(String) || value.is_a?(Symbol)) && pattern.match?(value.to_s)
+      end
+      private_class_method :matches?
+    end
+  end
+end

data/lib/hashie/extensions/deep_locate.rb

@@ -1,25 +1,20 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
+    # @example Locate the hash containing a key
+    #   Hashie::Extensions::DeepLocate.deep_locate(:name, { user: { name: 'Ada' } }) # => [{ name: 'Ada' }]
     module DeepLocate
       # The module level implementation of #deep_locate, in case you do not want
-      # to include/extend the base datastructure. For further examples please
+      # to include/extend the base data structure. For further examples please
       # see #deep_locate.
       #
       # @example
-      #   books = [
-      #     {
-      #       title: "Ruby for beginners",
-      #       pages: 120
-      #     },
-      #     ...
-      #   ]
-      #
-      #   DeepLocate.deep_locate -> (key, value, object) { key == :title }, books
-      #   # => [{:title=>"Ruby for beginners", :pages=>120}, ...]
+      #   books = [{ title: 'Ruby for beginners', pages: 120 }, { pages: 80 }]
+      #   comparator = ->(key, _value, _object) { key == :title }
+      #   Hashie::Extensions::DeepLocate.deep_locate(comparator, books) # => [{ title: 'Ruby for beginners', pages: 120 }]
       def self.deep_locate(comparator, object)
-        unless comparator.respond_to?(:call)
-          comparator = _construct_key_comparator(comparator, object)
-        end
+        comparator = _construct_key_comparator(comparator, object) unless comparator.respond_to?(:call)
 
         _deep_locate(comparator, object)
       end
@@ -51,22 +46,16 @@ module Hashie
       #
       #   books.extend(Hashie::Extensions::DeepLocate)
       #
-      #   # for ruby 1.9 leave *no* space between the lambda rocket and the braces
-      #   # http://ruby-journal.com/becareful-with-space-in-lambda-hash-rocket-syntax-between-ruby-1-dot-9-and-2-dot-0/
-      #
-      #   books.deep_locate -> (key, value, object) { key == :title && value.include?("Ruby") }
-      #   # => [{:title=>"Ruby for beginners", :pages=>120},
-      #   #     {:title=>"Ruby for the rest of us", :pages=>576}]
-      #
-      #   books.deep_locate -> (key, value, object) { key == :pages && value <= 120 }
-      #   # => [{:title=>"Ruby for beginners", :pages=>120},
-      #   #     {:title=>"CSS for intermediates", :pages=>80}]
+      #   ruby_titles = ->(key, value, _object) { key == :title && value.include?("Ruby") }
+      #   books.deep_locate(ruby_titles) # => [{ title: 'Ruby for beginners', pages: 120 }, { title: 'Ruby for the rest of us', pages: 576 }]
+      #   short_books = ->(key, value, _object) { key == :pages && value <= 120 }
+      #   books.deep_locate(short_books) # => [{ title: 'Ruby for beginners', pages: 120 }, { title: 'CSS for intermediates', pages: 80 }]
       def deep_locate(comparator)
         Hashie::Extensions::DeepLocate.deep_locate(comparator, self)
       end
 
       def self._construct_key_comparator(search_key, object)
-        if object.respond_to?(:indifferent_access?) && object.indifferent_access? ||
+        if (object.respond_to?(:indifferent_access?) && object.indifferent_access?) ||
            activesupport_indifferent?(object)
           search_key = search_key.to_s
         end
@@ -79,9 +68,7 @@ module Hashie
 
       def self._deep_locate(comparator, object, result = [])
         if object.is_a?(::Enumerable)
-          if object.any? { |value| _match_comparator?(value, comparator, object) }
-            result.push object
-          end
+          result.push object if object.any? { |value| _match_comparator?(value, comparator, object) }
 
           (object.respond_to?(:values) ? object.values : object.entries).each do |value|
             _deep_locate(comparator, value, result)

data/lib/hashie/extensions/deep_merge.rb

@@ -1,7 +1,17 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
+    # @example Merge nested hashes
+    #   hash = { user: { name: 'Ada' } }.extend(Hashie::Extensions::DeepMerge)
+    #   hash.deep_merge(user: { active: true }) # => { user: { name: 'Ada', active: true } }
     module DeepMerge
       # Returns a new hash with +self+ and +other_hash+ merged recursively.
+      #
+      # @example Merge without changing the receiver
+      #   hash = { settings: { count: 1 } }.extend(Hashie::Extensions::DeepMerge)
+      #   hash.deep_merge(settings: { count: 2 }) # => { settings: { count: 2 } }
+      #   hash # => { settings: { count: 1 } }
       def deep_merge(other_hash, &block)
         copy = _deep_dup(self)
         copy.extend(Hashie::Extensions::DeepMerge) unless copy.respond_to?(:deep_merge!)
@@ -10,8 +20,14 @@ module Hashie
 
       # Returns a new hash with +self+ and +other_hash+ merged recursively.
       # Modifies the receiver in place.
+      #
+      # @example Resolve a nested conflict with a block
+      #   hash = { settings: { count: 1 } }.extend(Hashie::Extensions::DeepMerge)
+      #   hash.deep_merge!({ settings: { count: 2 } }) { |_key, old, new| old + new }
+      #   hash # => { settings: { count: 3 } }
       def deep_merge!(other_hash, &block)
         return self unless other_hash.is_a?(::Hash)
+
         _recursive_merge(self, other_hash, &block)
         self
       end

data/lib/hashie/extensions/deep_merge_initializer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Hashie
+  module Extensions
+    # Initializes a Hash subclass, converting nested hashes to the same class.
+    #
+    # @example Initialize nested hash instances
+    #   class NestedHash < Hash
+    #     include Hashie::Extensions::DeepMergeInitializer
+    #   end
+    #   hash = NestedHash.new(user: { name: 'Ada' })
+    #   hash[:user].class # => NestedHash
+    module DeepMergeInitializer
+      # @example Convert hashes inside arrays and retain a default
+      #   class NestedHash < Hash
+      #     include Hashie::Extensions::DeepMergeInitializer
+      #   end
+      #   hash = NestedHash.new({ users: [{ name: 'Ada' }] }, false)
+      #   hash[:users].first.class # => NestedHash
+      #   hash[:users].first[:missing] # => false
+      def initialize(hash = {}, default = nil, &block)
+        default.nil? ? super(&block) : super(default)
+        hash.each_pair do |key, value|
+          self[key] = deep_merge_initializer_value(value, default, &block)
+        end
+      end
+
+      private
+
+      def deep_merge_initializer_value(value, default, &block)
+        case value
+        when ::Hash
+          self.class.new(value, default, &block)
+        when ::Array
+          value.map { |item| deep_merge_initializer_value(item, default, &block) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/hashie/extensions/ignore_undeclared.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
     # IgnoreUndeclared is a simple mixin that silently ignores
@@ -10,7 +12,7 @@ module Hashie
     # that property was provided at initialization.
     #
     # @example
-    #   class Person < Trash
+    #   class Person < Hashie::Trash
     #     include Hashie::Extensions::IgnoreUndeclared
     #
     #     property :first_name
@@ -27,17 +29,33 @@ module Hashie
     #
     #   p.first_name # => 'Freddy'
     #   p.last_name  # => 'Nostrils'
-    #   p.email      # => NoMethodError
+    #   expect { p.email }.to raise_error(NoMethodError)
     module IgnoreUndeclared
+      # @example Initialize only declared attributes
+      #   class Person < Hashie::Trash
+      #     include Hashie::Extensions::IgnoreUndeclared
+      #     property :name
+      #   end
+      #   person = Person.new
+      #   person.initialize_attributes(name: 'Ada', email: 'ada@example.com')
+      #   person.to_h # => { name: 'Ada' }
       def initialize_attributes(attributes)
         return unless attributes
 
         klass = self.class
-        translations = klass.respond_to?(:translations) && klass.translations || []
+        translations = (klass.respond_to?(:translations) && klass.translations) || []
 
         super(attributes.select { |attr, _| klass.property?(attr) || translations.include?(attr) })
       end
 
+      # @example Check the declaration rather than the current value
+      #   class Person < Hashie::Trash
+      #     include Hashie::Extensions::IgnoreUndeclared
+      #     property :name
+      #   end
+      #   person = Person.new
+      #   person.property_exists?(:name) # => true
+      #   person.property_exists?(:email) # => false
       def property_exists?(property)
         self.class.property?(property)
       end

data/lib/hashie/extensions/indifferent_access.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
     # IndifferentAccess gives you the ability to not care
@@ -23,10 +25,10 @@ module Hashie
     #   h['baz'] # => 'blip'
     #
     module IndifferentAccess
-      include Hashie::Extensions::RubyVersionCheck
-
       # @api private
       def self.convert_key(key)
+        return key.name if key.is_a?(Symbol)
+
         key.to_s
       end
 
@@ -61,6 +63,12 @@ module Hashie
       # This will inject indifferent access into an instance of
       # a hash without modifying the actual class. This is what
       # allows IndifferentAccess to spread to sub-hashes.
+      #
+      # @example Convert an existing hash in place
+      #   hash = { user: { name: 'Ada' } }
+      #   Hashie::Extensions::IndifferentAccess.inject!(hash)
+      #   hash['user'][:name] # => 'Ada'
+      #   hash.class # => Hash
       def self.inject!(hash)
         (class << hash; self; end).send :include, IndifferentAccess
         hash.convert!
@@ -68,10 +76,19 @@ module Hashie
 
       # Injects indifferent access into a duplicate of the hash
       # provided. See #inject!
+      #
+      # @example Leave the original hash's top-level keys unchanged
+      #   original = { name: 'Ada' }
+      #   hash = Hashie::Extensions::IndifferentAccess.inject(original)
+      #   hash['name'] # => 'Ada'
+      #   original # => { name: 'Ada' }
       def self.inject(hash)
         inject!(hash.dup)
       end
 
+      # @example Normalize symbol keys
+      #   hash = Hashie::Extensions::IndifferentAccess.inject({})
+      #   hash.convert_key(:name) # => 'name'
       def convert_key(key)
         IndifferentAccess.convert_key(key)
       end
@@ -79,6 +96,13 @@ module Hashie
       # Iterates through the keys and values, reconverting them to
       # their proper indifferent state. Used when IndifferentAccess
       # is injecting itself into member hashes.
+      #
+      # @example Normalize keys inserted through the original writer
+      #   hash = Hashie::Extensions::IndifferentAccess.inject({})
+      #   hash.regular_writer(:name, 'Ada')
+      #   hash.convert!
+      #   hash.keys # => ['name']
+      #   hash[:name] # => 'Ada'
       def convert!
         keys.each do |k| # rubocop:disable Performance/HashEachMethods
           indifferent_writer k, regular_delete(k)
@@ -86,6 +110,10 @@ module Hashie
         self
       end
 
+      # @example Make hashes nested in arrays indifferent
+      #   hash = Hashie::Extensions::IndifferentAccess.inject({})
+      #   value = hash.indifferent_value([{ name: 'Ada' }])
+      #   value.first['name'] # => 'Ada'
       def indifferent_value(value)
         if hash_lacking_indifference?(value)
           IndifferentAccess.inject!(value)
@@ -96,58 +124,114 @@ module Hashie
         end
       end
 
+      # @example Return an existing value or the configured default
+      #   hash = Hashie::Extensions::IndifferentAccess.inject({ name: 'Ada' })
+      #   hash.default = 'unknown'
+      #   hash.indifferent_default(:name) # => 'Ada'
+      #   hash.indifferent_default(:missing) # => 'unknown'
       def indifferent_default(key = nil)
         return self[convert_key(key)] if key?(key)
+
         regular_default(key)
       end
 
+      # @example Normalize incoming keys and nested values
+      #   hash = Hashie::Extensions::IndifferentAccess.inject({})
+      #   hash.indifferent_update(user: { name: 'Ada' })
+      #   hash['user']['name'] # => 'Ada'
       def indifferent_update(other_hash)
         return regular_update(other_hash) if hash_with_indifference?(other_hash)
+
         other_hash.each_pair do |k, v|
           self[k] = v
         end
       end
 
+      # @example Store a symbol key as a string
+      #   hash = Hashie::Extensions::IndifferentAccess.inject({})
+      #   hash.indifferent_writer(:name, 'Ada')
+      #   hash # => { 'name' => 'Ada' }
       def indifferent_writer(key, value)
         regular_writer convert_key(key), indifferent_value(value)
       end
 
-      def indifferent_fetch(key, *args, &block)
-        regular_fetch convert_key(key), *args, &block
+      # @example Fetch with either key type and support fallbacks
+      #   hash = Hashie::Extensions::IndifferentAccess.inject({ name: 'Ada' })
+      #   hash.indifferent_fetch(:name) # => 'Ada'
+      #   hash.indifferent_fetch(:missing, 'unknown') # => 'unknown'
+      def indifferent_fetch(key, ...)
+        regular_fetch(convert_key(key), ...)
       end
 
+      # @example Delete a string key through a symbol
+      #   hash = Hashie::Extensions::IndifferentAccess.inject({ name: 'Ada' })
+      #   hash.indifferent_delete(:name) # => 'Ada'
+      #   hash # => {}
       def indifferent_delete(key)
         regular_delete convert_key(key)
       end
 
+      # @example Recognize both key representations
+      #   hash = Hashie::Extensions::IndifferentAccess.inject({ name: 'Ada' })
+      #   hash.indifferent_key?(:name) # => true
+      #   hash.indifferent_key?('name') # => true
       def indifferent_key?(key)
         regular_key? convert_key(key)
       end
 
+      # @example Retrieve values using mixed key types
+      #   hash = Hashie::Extensions::IndifferentAccess.inject({ name: 'Ada', age: 42 })
+      #   hash.indifferent_values_at(:name, 'age', :missing) # => ['Ada', 42, nil]
       def indifferent_values_at(*indices)
         indices.map { |i| self[i] }
       end
 
+      # @example Identify an indifferent hash
+      #   hash = Hashie::Extensions::IndifferentAccess.inject({})
+      #   hash.indifferent_access? # => true
       def indifferent_access?
         true
       end
 
+      # @example Replace existing data and convert incoming keys
+      #   hash = Hashie::Extensions::IndifferentAccess.inject({ old: true })
+      #   hash.indifferent_replace(name: 'Ada')
+      #   hash # => { 'name' => 'Ada' }
       def indifferent_replace(other_hash)
         (keys - other_hash.keys).each { |key| delete(key) }
         other_hash.each { |key, value| self[key] = value }
         self
       end
 
+      # @example Merge without changing the original
+      #   hash = Hashie::Extensions::IndifferentAccess.inject({ name: 'Ada' })
+      #   merged = hash.merge(age: 42)
+      #   merged[:age] # => 42
+      #   merged.indifferent_access? # => true
+      #   hash.key?(:age) # => false
       def merge(*args)
         result = super
         return IndifferentAccess.inject!(result) if hash_lacking_indifference?(result)
+
         result.convert!
       end
 
+      # @example Merge and normalize in place
+      #   hash = Hashie::Extensions::IndifferentAccess.inject({ name: 'Ada' })
+      #   hash.merge!(age: 42)
+      #   hash['age'] # => 42
+      #   hash.keys.sort # => ['age', 'name']
       def merge!(*)
         super.convert!
       end
 
+      # @example Export a regular hash, preserving its default
+      #   hash = Hashie::Extensions::IndifferentAccess.inject({ name: 'Ada' })
+      #   hash.default = 'unknown'
+      #   plain = hash.to_hash
+      #   plain # => { 'name' => 'Ada' }
+      #   plain[:name] # => 'unknown'
+      #   plain.respond_to?(:indifferent_access?) # => false
       def to_hash
         {}.tap do |result|
           each_pair { |key, value| result[key] = value }
@@ -160,18 +244,20 @@ module Hashie
         end
       end
 
-      with_minimum_ruby('2.5.0') do
-        def slice(*keys)
-          string_keys = keys.map { |key| convert_key(key) }
-          super(*string_keys)
-        end
+      # @example Select keys using either representation
+      #   hash = Hashie::Extensions::IndifferentAccess.inject({ name: 'Ada', age: 42 })
+      #   hash.slice(:name) # => { 'name' => 'Ada' }
+      def slice(*keys)
+        string_keys = keys.map { |key| convert_key(key) }
+        super(*string_keys)
       end
 
-      with_minimum_ruby('3.0.0') do
-        def except(*keys)
-          string_keys = keys.map { |key| convert_key(key) }
-          super(*string_keys)
-        end
+      # @example Exclude keys using either representation
+      #   hash = Hashie::Extensions::IndifferentAccess.inject({ name: 'Ada', age: 42 })
+      #   hash.except(:age) # => { 'name' => 'Ada' }
+      def except(*keys)
+        string_keys = keys.map { |key| convert_key(key) }
+        super(*string_keys)
       end
 
       protected

data/lib/hashie/extensions/kernel_coercion.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Hashie
+  module Extensions
+    # @example Opt in to strict numeric coercion
+    #   klass = Class.new(Hash) do
+    #     include Hashie::Extensions::Coercion
+    #     extend Hashie::Extensions::KernelCoercion
+    #     coerce_key :age, Integer
+    #   end
+    #   hash = klass.new
+    #   hash[:age] = '42'
+    #   hash[:age] # => 42
+    #   expect { hash[:age] = 'bad' }.to raise_error(Hashie::CoercionError)
+    module KernelCoercion
+      # Core types whose values can be coerced with a stricter
+      # +Kernel+ method (e.g. +Kernel#Integer+) instead of the more
+      # lenient +#to_i+-style conversion methods used by default.
+      #
+      # NOTE: There is no strict Kernel method equivalent for +Symbol+, so
+      # +Symbol+ coercion is left to the default, lenient +#to_sym+ behavior.
+      STRICT_CORE_TYPES = {
+        Integer => :Integer,
+        Float => :Float,
+        Complex => :Complex,
+        Rational => :Rational,
+        String => :String
+      }.freeze
+
+      # Overrides Hashie::Extensions::Coercion::ClassMethods#build_core_type_coercion
+      # to use a stricter Kernel method (e.g. Kernel#Integer) for coercing core
+      # types, instead of the default, more lenient conversion method (e.g. #to_i).
+      #
+      #   "abcd".to_i    #=> 0
+      #   Integer("abcd") #=> ArgumentError: invalid value for Integer(): "abcd"
+      #
+      # @example Build a strict conversion and preserve Symbol fallback
+      #   klass = Class.new(Hash) do
+      #     include Hashie::Extensions::Coercion
+      #     extend Hashie::Extensions::KernelCoercion
+      #   end
+      #   conversion = klass.build_core_type_coercion(Integer)
+      #   conversion.call('42') # => 42
+      #   expect { conversion.call('42 items') }.to raise_error(ArgumentError)
+      #   klass.build_core_type_coercion(Symbol).call('name') # => :name
+      def build_core_type_coercion(type)
+        return super unless STRICT_CORE_TYPES.key?(type)
+
+        kernel_method = STRICT_CORE_TYPES[type]
+        lambda do |value|
+          next value if value.is_a?(type)
+
+          Kernel.public_send(kernel_method, value)
+        end
+      end
+    end
+  end
+end

data/lib/hashie/extensions/key_conflict_warning.rb

@@ -1,11 +1,26 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
+    # @example Disable conflict warnings on a Mash subclass
+    #   klass = Class.new(Hashie::Mash)
+    #   klass.disable_warnings(:size)
+    #   klass.disable_warnings?(:size) # => true
+    #   klass.disable_warnings?(:keys) # => false
     module KeyConflictWarning
+      # @example Explain why base Mash warnings cannot be disabled
+      #   require 'hashie/mash'
+      #   error = Hashie::Extensions::KeyConflictWarning::CannotDisableMashWarnings.new
+      #   error.message.include?('please subclass the Mash') # => true
       class CannotDisableMashWarnings < StandardError
+        # @example Construct the warning configuration error
+        #   require 'hashie/mash'
+        #   error = Hashie::Extensions::KeyConflictWarning::CannotDisableMashWarnings.new
+        #   error.message # => 'you cannot disable warnings on the base Mash class; please subclass the Mash and disable it in the subclass'
         def initialize
           super(
-            'You cannot disable warnings on the base Mash class. ' \
-            'Please subclass the Mash and disable it in the subclass.'
+            'you cannot disable warnings on the base Mash class; ' \
+            'please subclass the Mash and disable it in the subclass'
           )
         end
       end
@@ -14,8 +29,13 @@ module Hashie
       #
       # @api semipublic
       # @return [void]
+      # @example Disable warnings for selected methods
+      #   klass = Class.new(Hashie::Mash)
+      #   klass.disable_warnings(:size, :keys)
+      #   klass.disabled_warnings # => [:size, :keys]
       def disable_warnings(*method_keys)
         raise CannotDisableMashWarnings if self == Hashie::Mash
+
         if method_keys.any?
           disabled_warnings.concat(method_keys).tap(&:flatten!).uniq!
         else
@@ -29,23 +49,38 @@ module Hashie
       #
       # @api semipublic
       # @return [Boolean]
+      # @example Disable all warnings when no methods are specified
+      #   klass = Class.new(Hashie::Mash)
+      #   klass.disable_warnings
+      #   klass.disable_warnings?(:size) # => true
       def disable_warnings?(method_key = nil)
         return disabled_warnings.include?(method_key) if disabled_warnings.any? && method_key
+
         @disable_warnings ||= false
       end
 
       # Returns an array of methods that this class disables warnings for.
       #
       # @api semipublic
-      # @return [Boolean]
+      # @return [Array<Symbol>]
+      # @example Inspect selected warning exclusions
+      #   klass = Class.new(Hashie::Mash)
+      #   klass.disable_warnings(:size)
+      #   klass.disabled_warnings # => [:size]
       def disabled_warnings
-        @_disabled_warnings ||= []
+        @disabled_warnings ||= []
       end
 
       # Inheritance hook that sets class configuration when inherited.
       #
       # @api semipublic
       # @return [void]
+      # @example Inherit selected warning settings
+      #   parent = Class.new(Hashie::Mash)
+      #   parent.disable_warnings(:size)
+      #   child = Class.new(parent)
+      #   child.disabled_warnings # => [:size]
+      #   child.disable_warnings?(:keys) # => false
       def inherited(subclass)
         super
         subclass.disable_warnings(disabled_warnings) if disable_warnings?

data/lib/hashie/extensions/key_conversion.rb

@@ -1,5 +1,14 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
+    # @example Include both key conversion extensions
+    #   class ConvertibleHash < Hash
+    #     include Hashie::Extensions::KeyConversion
+    #   end
+    #   hash = ConvertibleHash[:name, 'Ada']
+    #   hash.stringify_keys # => { 'name' => 'Ada' }
+    #   hash.stringify_keys!.symbolize_keys # => { name: 'Ada' }
     module KeyConversion
       def self.included(base)
         base.send :include, SymbolizeKeys