hashie 4.1.0 → 5.2.0

data/lib/hashie/extensions/active_support/core_ext/hash.rb

@@ -1,8 +1,46 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
+    # Compatibility extensions for Active Support.
+    #
+    # @example
+    #   require 'active_support/core_ext/hash/except'
+    #   require 'hashie/extensions/active_support/core_ext/hash'
+    #   klass = Class.new(Hashie::Mash) do
+    #     include Hashie::Extensions::ActiveSupport::CoreExt::Hash
+    #   end
+    #   klass.new(name: 'Ada', age: 37).except(:age).to_h # => {'name' => 'Ada'}
     module ActiveSupport
+      # Adapts Active Support core extensions for Hashie objects.
+      #
+      # @example
+      #   require 'active_support/core_ext/hash/except'
+      #   require 'hashie/extensions/active_support/core_ext/hash'
+      #   klass = Class.new(Hashie::Mash) do
+      #     include Hashie::Extensions::ActiveSupport::CoreExt::Hash
+      #   end
+      #   klass.new(name: 'Ada').except(:name).to_h # => {}
       module CoreExt
+        # Converts excluded keys using Mash's key normalization.
+        #
+        # @example
+        #   require 'active_support/core_ext/hash/except'
+        #   require 'hashie/extensions/active_support/core_ext/hash'
+        #   klass = Class.new(Hashie::Mash) do
+        #     include Hashie::Extensions::ActiveSupport::CoreExt::Hash
+        #   end
+        #   klass.new(name: 'Ada', age: 37).except(:age).to_h # => {'name' => 'Ada'}
         module Hash
+          # @example Exclude symbol keys from a string-keyed Mash
+          #   require 'active_support/core_ext/hash/except'
+          #   require 'hashie/extensions/active_support/core_ext/hash'
+          #   klass = Class.new(Hashie::Mash) do
+          #     include Hashie::Extensions::ActiveSupport::CoreExt::Hash
+          #   end
+          #   mash = klass.new(name: 'Ada', age: 37)
+          #   mash.except(:age).to_h # => {'name' => 'Ada'}
+          #   mash.keys # => ['name', 'age']
           def except(*keys)
             string_keys = keys.map { |key| convert_key(key) }
             super(*string_keys)

data/lib/hashie/extensions/array/pretty_inspect.rb

@@ -1,12 +1,32 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
     module Array
+      # Formats array inspection with the concrete class name.
+      #
+      # @example
+      #   klass = Class.new(Array) do
+      #     include Hashie::Extensions::Array::PrettyInspect
+      #   end
+      #   array = klass.new([1, 'two'])
+      #   array.inspect # => "#<#{klass} [1, \"two\"]>"
       module PrettyInspect
+        # @example Retain the original inspection as array_inspect
+        #   klass = Class.new(Array) do
+        #     include Hashie::Extensions::Array::PrettyInspect
+        #   end
+        #   klass.new([1, 2]).array_inspect # => '[1, 2]'
         def self.included(base)
           base.send :alias_method, :array_inspect, :inspect
           base.send :alias_method, :inspect, :hashie_inspect
         end
 
+        # @example
+        #   klass = Class.new(Array) do
+        #     include Hashie::Extensions::Array::PrettyInspect
+        #   end
+        #   klass.new([1, 2]).hashie_inspect # => "#<#{klass} [1, 2]>"
         def hashie_inspect
           ret = "#<#{self.class} ["
           ret << to_a.map(&:inspect).join(', ')

data/lib/hashie/extensions/block_access.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Hashie
+  module Extensions
+    # Builds nested hashes through blocks without changing ordinary method access.
+    # Include after MethodAccess when using a Hash subclass.
+    #
+    #   class Configuration < Hashie::Mash
+    #     include Hashie::Extensions::BlockAccess
+    #   end
+    #
+    #   config = Configuration.new
+    #   config.author { |author| author.name = 'Michael Bleigh' }
+    #   config.author.name # => 'Michael Bleigh'
+    #
+    # @example Build a nested configuration
+    #   class Configuration < Hashie::Mash
+    #     include Hashie::Extensions::BlockAccess
+    #   end
+    #   config = Configuration.new
+    #   config.author { |author| author.name = 'Michael' }
+    #   config.author.name # => 'Michael'
+    module BlockAccess
+      # @example Build a child through bracket access
+      #   hash = {}.extend(Hashie::Extensions::BlockAccess)
+      #   hash.[](:author) { |author| author[:name] = 'Michael' }
+      #   hash # => { author: { name: 'Michael' } }
+      def [](key)
+        return super unless block_given?
+
+        value = block_access_child(self, key)
+        yield value
+        value
+      end
+
+      # A block-only builder does not make a missing reader available to respond_to?.
+      #
+      # @example Build a child through a missing method
+      #   hash = {}.extend(Hashie::Extensions::BlockAccess)
+      #   hash.author { |author| author[:name] = 'Michael' }
+      #   hash['author'] # => { name: 'Michael' }
+      def method_missing(name, *args, &block) # rubocop:disable Style/MissingRespondToMissing
+        return super unless block && !name.to_s.end_with?('=', '?', '!', '_')
+
+        raise ArgumentError, "wrong number of arguments (given `#{args.size}`, expected 0..1)" if args.size > 1
+
+        child = block_access_child(self, block_access_key(name))
+        child = block_access_child(child, args.first) unless args.empty?
+        block.call(child)
+        child
+      end
+
+      private
+
+      def block_access_key(name)
+        return name if key?(name)
+        return name.to_s if key?(name.to_s)
+
+        respond_to?(:convert_key, true) ? convert_key(name.to_s) : name.to_s
+      end
+
+      def block_access_child(parent, key)
+        parent[key] = parent.class.new unless parent.key?(key)
+        child = parent[key]
+        return child if child.is_a?(::Hash)
+
+        raise TypeError, "key `#{key}` already contains a `#{child.class}`"
+      end
+    end
+  end
+end

data/lib/hashie/extensions/coercion.rb

@@ -1,48 +1,73 @@
+# frozen_string_literal: true
+
 module Hashie
+  # @example Describe a failed conversion
+  #   require 'hashie/extensions/coercion'
+  #   error = Hashie::CoercionError.new(:age, 'bad', Integer, 'invalid number')
+  #   error.message # => 'cannot coerce property `:age` from `String` to `Integer`: invalid number'
   class CoercionError < StandardError
+    # @example Include the key, source class, and destination in the message
+    #   require 'hashie/extensions/coercion'
+    #   error = Hashie::CoercionError.new(:age, 'bad', Integer, 'invalid number')
+    #   error.message # => 'cannot coerce property `:age` from `String` to `Integer`: invalid number'
     def initialize(key, value, into, message)
-      super("Cannot coerce property #{key.inspect} from #{value.class} to #{into}: #{message}")
+      super("cannot coerce property `#{key.inspect}` from `#{value.class}` to `#{into}`: #{message}")
     end
   end
 
   module Extensions
+    # @example Coerce assigned values
+    #   class Person < Hash
+    #     include Hashie::Extensions::Coercion
+    #     coerce_key :age, Integer
+    #   end
+    #   person = Person.new
+    #   person[:age] = '42'
+    #   person[:age] # => 42
     module Coercion
       CORE_TYPES = {
-        Integer    => :to_i,
-        Float      => :to_f,
-        Complex    => :to_c,
-        Rational   => :to_r,
-        String     => :to_s,
-        Symbol     => :to_sym
+        Integer => :to_i,
+        Float => :to_f,
+        Complex => :to_c,
+        Rational => :to_r,
+        String => :to_s,
+        Symbol => :to_sym
       }.freeze
 
       ABSTRACT_CORE_TYPES =
-        if RubyVersion.new(RUBY_VERSION) >= RubyVersion.new('2.4.0')
-          { Numeric => [Integer, Float, Complex, Rational] }
-        else
-          {
-            Integer => [Fixnum, Bignum],
-            Numeric => [Fixnum, Bignum, Float, Complex, Rational]
-          }
-        end
+        { Numeric => [Integer, Float, Complex, Rational] }.freeze
 
       def self.included(base)
         base.send :include, InstanceMethods
         base.extend ClassMethods
-        unless base.method_defined?(:set_value_without_coercion)
-          base.send :alias_method, :set_value_without_coercion, :[]=
-        end
+        base.send :alias_method, :set_value_without_coercion, :[]= unless base.method_defined?(:set_value_without_coercion)
         base.send :alias_method, :[]=, :set_value_with_coercion
       end
 
+      # @example Add coercing instance writers through the extension
+      #   class Record < Hash
+      #     include Hashie::Extensions::Coercion
+      #     coerce_key :count, Integer
+      #   end
+      #   record = Record.new
+      #   record[:count] = '3'
+      #   record[:count] # => 3
       module InstanceMethods
+        # @example Write a coerced value
+        #   class Record < Hash
+        #     include Hashie::Extensions::Coercion
+        #     coerce_key :count, Integer
+        #   end
+        #   record = Record.new
+        #   record.set_value_with_coercion(:count, '3')
+        #   record[:count] # => 3
         def set_value_with_coercion(key, value)
           into = self.class.key_coercion(key) || self.class.value_coercion(value)
 
           unless value.nil? || into.nil?
             begin
               value = self.class.fetch_coercion(into).call(value)
-            rescue NoMethodError, TypeError => e
+            rescue NoMethodError, TypeError, ArgumentError => e
               raise CoercionError.new(key, value, into, e.message)
             end
           end
@@ -50,10 +75,46 @@ module Hashie
           set_value_without_coercion(key, value)
         end
 
+        # @example Route a custom write through coercion
+        #   class Record < Hash
+        #     include Hashie::Extensions::Coercion
+        #     coerce_key :count, Integer
+        #   end
+        #   record = Record.new
+        #   record.custom_writer(:count, '3')
+        #   record[:count] # => 3
         def custom_writer(key, value, _convert = true)
           self[key] = value
         end
 
+        # Ensures that values are coerced before Mash's own recursive
+        # Hash-to-Mash conversion has a chance to run, since by that point
+        # the value would already be an instance of `self.class` rather
+        # than a plain Hash, and value coercion would never trigger. See
+        # https://github.com/hashie/hashie/issues/265.
+        #
+        # @example Convert values by their source type
+        #   class Record < Hash
+        #     include Hashie::Extensions::Coercion
+        #     coerce_value String, Integer
+        #   end
+        #   Record.new.convert_value('3') # => 3
+        #   Record.new.convert_value(false) # => false
+        def convert_value(val, duping = false)
+          into = self.class.value_coercion(val)
+          return self.class.fetch_coercion(into).call(val) if into
+
+          defined?(super) ? super : val
+        end
+
+        # @example Remove old keys and coerce incoming values
+        #   class Record < Hash
+        #     include Hashie::Extensions::Coercion
+        #     coerce_key :count, Integer
+        #   end
+        #   record = Record[:old, true]
+        #   record.replace(count: '3')
+        #   record # => { count: 3 }
         def replace(other_hash)
           (keys - other_hash.keys).each { |key| delete(key) }
           other_hash.each { |key, value| self[key] = value }
@@ -61,6 +122,12 @@ module Hashie
         end
       end
 
+      # @example Configure coercion rules on a hash subclass
+      #   class Record < Hash
+      #     include Hashie::Extensions::Coercion
+      #     coerce_key :count, Integer
+      #   end
+      #   Record.key_coercion(:count) # => Integer
       module ClassMethods
         attr_writer :key_coercions
         protected :key_coercions=
@@ -69,30 +136,58 @@ module Hashie
         # key is set it will be coerced into the specified class.
         # Coercion will occur by first attempting to call Class.coerce
         # and then by calling Class.new with the value as an argument
-        # in either case.
+        # in either case. Procs and other objects implementing #call
+        # may also be used.
         #
-        # @param [Object] key the key or array of keys you would like to be coerced.
-        # @param [Class] into the class into which you want the key(s) coerced.
+        # @param [Array<Object>] attrs the keys followed by the class or callable used to coerce them.
         #
         # @example Coerce a "user" subhash into a User object
+        #   User = Struct.new(:name) do
+        #     def self.coerce(attributes)
+        #       new(attributes[:name])
+        #     end
+        #   end
         #   class Tweet < Hash
         #     include Hashie::Extensions::Coercion
         #     coerce_key :user, User
         #   end
+        #   tweet = Tweet.new
+        #   tweet[:user] = { name: 'Ada' }
+        #   tweet[:user].name # => 'Ada'
         def coerce_key(*attrs)
           into = attrs.pop
           attrs.each { |key| key_coercions[key] = into }
         end
 
+        # @example Configure multiple keys with one rule
+        #   class Record < Hash
+        #     include Hashie::Extensions::Coercion
+        #     coerce_keys :count, :total, Integer
+        #   end
+        #   record = Record.new
+        #   record[:total] = '12'
+        #   record[:total] # => 12
+        #   Record.key_coercion(:count) # => Integer
         alias coerce_keys coerce_key
 
         # Returns a hash of any existing key coercions.
+        #
+        # @example Inspect configured rules
+        #   klass = Class.new(Hash) { include Hashie::Extensions::Coercion }
+        #   klass.coerce_key(:age, Integer)
+        #   klass.key_coercions # => { age: Integer }
         def key_coercions
           @key_coercions ||= {}
         end
 
         # Returns the specific key coercion for the specified key,
         # if one exists.
+        #
+        # @example Look up symbol and string key names
+        #   klass = Class.new(Hash) { include Hashie::Extensions::Coercion }
+        #   klass.coerce_key(:age, Integer)
+        #   klass.key_coercion('age') # => Integer
+        #   klass.key_coercion(:missing) # => nil
         def key_coercion(key)
           key_coercions[key.to_sym]
         end
@@ -102,7 +197,7 @@ module Hashie
         # class.
         #
         # @param [Class] from the type you would like coerced.
-        # @param [Class] into the class into which you would like the value coerced.
+        # @param [Class, #call] into the class or callable used to coerce the value.
         # @option options [Boolean] :strict (true) whether use exact source class
         #   only or include ancestors
         #
@@ -118,6 +213,10 @@ module Hashie
         #       end
         #     end
         #   end
+        #   record = SpecialHash.new
+        #   record[:user] = { name: 'Ada' }
+        #   record[:user].class # => SpecialHash
+        #   record[:user][:name] # => 'Ada'
         def coerce_value(from, into, options = {})
           options = { strict: true }.merge(options)
 
@@ -138,35 +237,67 @@ module Hashie
         end
 
         # Return all value coercions that have the :strict rule as true.
+        #
+        # @example Inspect exact source-type rules
+        #   klass = Class.new(Hash) { include Hashie::Extensions::Coercion }
+        #   klass.coerce_value(String, Integer)
+        #   klass.strict_value_coercions # => { String => Integer }
         def strict_value_coercions
           @strict_value_coercions ||= {}
         end
 
         # Return all value coercions that have the :strict rule as false.
+        #
+        # @example Inspect non-strict source-type rules
+        #   klass = Class.new(Hash) { include Hashie::Extensions::Coercion }
+        #   klass.coerce_value(Integer, String, strict: false)
+        #   klass.lenient_value_coercions # => { Integer => String }
         def lenient_value_coercions
           @lenient_value_coercions ||= {}
         end
 
         # Fetch the value coercion, if any, for the specified object.
+        #
+        # @example Look up a rule from an actual value
+        #   klass = Class.new(Hash) { include Hashie::Extensions::Coercion }
+        #   klass.coerce_value(String, Integer)
+        #   klass.value_coercion('3') # => Integer
+        #   klass.value_coercion(false) # => nil
         def value_coercion(value)
           from = value.class
           strict_value_coercions[from] || lenient_value_coercions[from]
         end
 
+        # @example Retrieve a conversion callable
+        #   klass = Class.new(Hash) { include Hashie::Extensions::Coercion }
+        #   klass.fetch_coercion(Integer).call('3') # => 3
+        #   klass.fetch_coercion(->(value) { value.upcase }).call('ada') # => 'ADA'
         def fetch_coercion(type)
           return type if type.is_a? Proc
+          return type if type.respond_to?(:call) && !type.is_a?(Module) && !type.is_a?(Enumerable)
+
           coercion_cache[type]
         end
 
+        # @example Lazily cache a working conversion
+        #   klass = Class.new(Hash) { include Hashie::Extensions::Coercion }
+        #   conversion = klass.coercion_cache[Integer]
+        #   conversion.call('3') # => 3
+        #   klass.coercion_cache[Integer].equal?(conversion) # => true
         def coercion_cache
           @coercion_cache ||= ::Hash.new do |hash, type|
             hash[type] = build_coercion(type)
           end
         end
 
+        # @example Build scalar and nested collection conversions
+        #   klass = Class.new(Hash) { include Hashie::Extensions::Coercion }
+        #   klass.build_coercion(Integer).call('3') # => 3
+        #   klass.build_coercion([Integer]).call(['3', '4']) # => [3, 4]
+        #   klass.build_coercion({ Symbol => Integer }).call('age' => '42') # => { age: 42 }
         def build_coercion(type)
           if type.is_a? Enumerable
-            if type.class == ::Hash
+            if type.instance_of?(::Hash)
               type, key_type, value_type = type.class, *type.first
               build_hash_coercion(type, key_type, value_type)
             else
@@ -179,18 +310,24 @@ module Hashie
           elsif type.respond_to? :coerce
             lambda do |value|
               return value if value.is_a? type
+
               type.coerce(value)
             end
           elsif type.respond_to? :new
             lambda do |value|
               return value if value.is_a? type
+
               type.new(value)
             end
           else
-            raise TypeError, "#{type} is not a coercable type"
+            raise TypeError, "no coercion is available for `#{type}`"
           end
         end
 
+        # @example Convert both hash keys and values
+        #   klass = Class.new(Hash) { include Hashie::Extensions::Coercion }
+        #   conversion = klass.build_hash_coercion(Hash, Symbol, Integer)
+        #   conversion.call('age' => '42') # => { age: 42 }
         def build_hash_coercion(type, key_type, value_type)
           key_coerce = fetch_coercion(key_type)
           value_coerce = fetch_coercion(value_type)
@@ -199,6 +336,10 @@ module Hashie
           end
         end
 
+        # @example Convert each array element
+        #   klass = Class.new(Hash) { include Hashie::Extensions::Coercion }
+        #   conversion = klass.build_container_coercion(Array, Integer)
+        #   conversion.call(['3', '4']) # => [3, 4]
         def build_container_coercion(type, value_type)
           value_coerce = fetch_coercion(value_type)
           lambda do |value|
@@ -206,14 +347,27 @@ module Hashie
           end
         end
 
+        # @example Use the lenient core conversion
+        #   klass = Class.new(Hash) { include Hashie::Extensions::Coercion }
+        #   conversion = klass.build_core_type_coercion(Integer)
+        #   conversion.call('12 items') # => 12
+        #   conversion.call('not a number') # => 0
         def build_core_type_coercion(type)
           name = CORE_TYPES[type]
           lambda do |value|
             return value if value.is_a? type
-            return value.send(name)
+
+            value.send(name)
           end
         end
 
+        # @example Copy key rules into subclasses without sharing their rule hashes
+        #   parent = Class.new(Hash) { include Hashie::Extensions::Coercion }
+        #   parent.coerce_key(:age, Integer)
+        #   child = Class.new(parent)
+        #   child.coerce_key(:name, String)
+        #   child.key_coercion(:age) # => Integer
+        #   parent.key_coercion(:name) # => nil
         def inherited(klass)
           super
 

data/lib/hashie/extensions/dash/coercion.rb

@@ -1,19 +1,50 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
     module Dash
+      # Adds per-property coercion to a Dash.
+      #
+      # @example
+      #   klass = Class.new(Hashie::Dash) do
+      #     include Hashie::Extensions::Dash::Coercion
+      #     property :count, coerce: Integer
+      #   end
+      #   klass.new(count: '3').count # => 3
       module Coercion
         # Extends a Dash with the ability to define coercion for properties.
-
+        #
+        # @example
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::Coercion
+        #     property :count, coerce: Integer
+        #   end
+        #   klass.new(count: '3').count # => 3
         def self.included(base)
           base.send :include, Hashie::Extensions::Coercion
           base.extend ClassMethods
         end
 
+        # Property declarations supporting coercion.
+        #
+        # @example
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::Coercion
+        #     property :count, coerce: Integer
+        #   end
+        #   klass.new(count: '3').count # => 3
         module ClassMethods
           # Defines a property on the Dash. Options are the standard
-          # <tt>Hashie::Dash#property</tt> options plus:
+          # `Hashie::Dash#property` options plus:
+          #
+          # * `:coerce` - The class into which you want the property coerced.
           #
-          # * <tt>:coerce</tt> - The class into which you want the property coerced.
+          # @example
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::Coercion
+          #     property :count, coerce: Integer
+          #   end
+          #   klass.new(count: '3').count # => 3
           def property(property_name, options = {})
             super
             coerce_key property_name, options[:coerce] if options[:coerce]