hashie 4.1.0 → 5.2.0

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,6 +25,13 @@ module Hashie
     #   h['baz'] # => 'blip'
     #
     module IndifferentAccess
+      # @api private
+      def self.convert_key(key)
+        return key.name if key.is_a?(Symbol)
+
+        key.to_s
+      end
+
       def self.included(base)
         Hashie::Extensions::Dash::IndifferentAccess.maybe_extend(base)
 
@@ -54,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!
@@ -61,24 +76,44 @@ 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)
-        key.to_s
+        IndifferentAccess.convert_key(key)
       end
 
       # 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
-          regular_writer convert_key(k), indifferent_value(regular_delete(k))
+          indifferent_writer k, regular_delete(k)
         end
         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)
@@ -89,58 +124,142 @@ 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
-        IndifferentAccess.inject!(result) if hash_lacking_indifference?(result)
+        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 }
+
+          if default_proc
+            result.default_proc = default_proc
+          else
+            result.default = default
+          end
+        end
+      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
+
+      # @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
 
       def hash_lacking_indifference?(other)

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

data/lib/hashie/extensions/mash/define_accessors.rb

@@ -1,7 +1,20 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
     module Mash
+      # Generates reusable methods as Mash properties are accessed.
+      #
+      # @example
+      #   klass = Class.new(Hashie::Mash) do
+      #     include Hashie::Extensions::Mash::DefineAccessors
+      #   end
+      #   klass.new(name: 'Ada').name # => 'Ada'
       module DefineAccessors
+        # @example Install generated accessors on a subclass
+        #   klass = Class.new(Hashie::Mash)
+        #   klass.include(Hashie::Extensions::Mash::DefineAccessors)
+        #   klass.new(quantity: 2).quantity # => 2
         def self.included(klass)
           klass.class_eval do
             mod = Ext.new
@@ -9,23 +22,40 @@ module Hashie
           end
         end
 
+        # @example Install generated accessors on one Mash
+        #   mash = Hashie::Mash.new(quantity: 2)
+        #   mash.extend(Hashie::Extensions::Mash::DefineAccessors)
+        #   mash.quantity # => 2
         def self.extended(obj)
           included(obj.singleton_class)
         end
 
+        # A module of lazily generated accessors for a Mash class.
+        #
+        # @example
+        #   accessors = Hashie::Extensions::Mash::DefineAccessors::Ext.new
+        #   klass = Class.new(Hashie::Mash) { include accessors }
+        #   mash = klass.new(name: 'Ada')
+        #   accessors.define_reader('name', :name)
+        #   mash.name # => 'Ada'
         class Ext < Module
+          # @example Generate a method on first access
+          #   accessors = Hashie::Extensions::Mash::DefineAccessors::Ext.new
+          #   klass = Class.new(Hashie::Mash) { include accessors }
+          #   klass.new(name: 'Ada').name # => 'Ada'
+          #   accessors.instance_methods(false).include?(:name) # => true
           def initialize
             mod = self
             define_method(:method_missing) do |method_name, *args, &block|
               key, suffix = method_name_and_suffix(method_name)
               case suffix
-              when '='.freeze
+              when '='
                 mod.define_writer(key, method_name)
-              when '?'.freeze
+              when '?'
                 mod.define_predicate(key, method_name)
-              when '!'.freeze
+              when '!'
                 mod.define_initializing_reader(key, method_name)
-              when '_'.freeze
+              when '_'
                 mod.define_underbang_reader(key, method_name)
               else
                 mod.define_reader(key, method_name)
@@ -34,6 +64,12 @@ module Hashie
             end
           end
 
+          # @example
+          #   accessors = Hashie::Extensions::Mash::DefineAccessors::Ext.new
+          #   klass = Class.new(Hashie::Mash) { include accessors }
+          #   mash = klass.new(name: 'Ada')
+          #   accessors.define_reader('name', :name)
+          #   mash.name # => 'Ada'
           def define_reader(key, method_name)
             define_method(method_name) do |&block|
               if key? method_name
@@ -44,40 +80,67 @@ module Hashie
             end
           end
 
+          # @example
+          #   accessors = Hashie::Extensions::Mash::DefineAccessors::Ext.new
+          #   accessors.define_writer('name', :name=)
+          #   klass = Class.new(Hashie::Mash) { include accessors }
+          #   mash = klass.new
+          #   mash.name = 'Ada'
+          #   mash['name'] # => 'Ada'
           def define_writer(key, method_name)
             define_method(method_name) do |value = nil|
               if key? method_name
-                self.[](method_name, &proc)
+                self.[](method_name)
               else
                 assign_property(key, value)
               end
             end
           end
 
+          # @example
+          #   accessors = Hashie::Extensions::Mash::DefineAccessors::Ext.new
+          #   accessors.define_predicate('name', :name?)
+          #   klass = Class.new(Hashie::Mash) { include accessors }
+          #   klass.new(name: 'Ada').name? # => true
+          #   klass.new.name? # => false
           def define_predicate(key, method_name)
             define_method(method_name) do
               if key? method_name
-                self.[](method_name, &proc)
+                self.[](method_name)
               else
                 !!self[key]
               end
             end
           end
 
+          # @example
+          #   accessors = Hashie::Extensions::Mash::DefineAccessors::Ext.new
+          #   accessors.define_initializing_reader('address', :address!)
+          #   klass = Class.new(Hashie::Mash) { include accessors }
+          #   mash = klass.new
+          #   mash.address!.city = 'London'
+          #   mash.address.city # => 'London'
           def define_initializing_reader(key, method_name)
             define_method(method_name) do
               if key? method_name
-                self.[](method_name, &proc)
+                self.[](method_name)
               else
                 initializing_reader(key)
               end
             end
           end
 
+          # @example
+          #   accessors = Hashie::Extensions::Mash::DefineAccessors::Ext.new
+          #   accessors.define_underbang_reader('address', :address_)
+          #   klass = Class.new(Hashie::Mash) { include accessors }
+          #   mash = klass.new
+          #   mash.address_.city = 'London'
+          #   mash.key?('address') # => false
           def define_underbang_reader(key, method_name)
             define_method(method_name) do
               if key? method_name
-                self.[](key, &proc)
+                self.[](key)
               else
                 underbang_reader(key)
               end

data/lib/hashie/extensions/mash/keep_original_keys.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
     module Mash
@@ -14,8 +16,13 @@ module Hashie
       #   mash['string_key'] == mash[:string_key]  #=> true
       #   mash[:symbol_key] == mash['symbol_key']  #=> true
       module KeepOriginalKeys
+        # @example Preserve symbol keys when including the extension
+        #   klass = Class.new(Hashie::Mash) do
+        #     include Hashie::Extensions::Mash::KeepOriginalKeys
+        #   end
+        #   klass.new(name: 'Ada').keys # => [:name]
         def self.included(descendant)
-          error_message = "#{descendant} is not a kind of Hashie::Mash"
+          error_message = "`#{descendant}` is not a kind of Hashie::Mash"
           raise ArgumentError, error_message unless descendant <= Hashie::Mash
         end
 
@@ -26,13 +33,10 @@ module Hashie
         # @param [Object, String, Symbol] key the key to access.
         # @return [Object] the value assigned to the key.
         def convert_key(key)
-          if regular_key?(key)
-            key
-          elsif (converted_key = __convert(key)) && regular_key?(converted_key)
-            converted_key
-          else
-            key
-          end
+          return key if regular_key?(key)
+
+          converted_key = __convert(key)
+          converted_key && regular_key?(converted_key) ? converted_key : key
         end
 
         # Converts symbol/string keys to their alternative formats, but leaves
@@ -42,7 +46,7 @@ module Hashie
         # @return [Object, String, Symbol] the converted key.
         def __convert(key)
           case key
-          when Symbol then key.to_s
+          when Symbol then key.name
           when String then key.to_sym
           else key
           end

data/lib/hashie/extensions/mash/permissive_respond_to.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
     module Mash