hashie 5.1.0 → 5.2.0

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,41 +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 =
-        { Numeric => [Integer, Float, Complex, Rational] }
+        { 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
@@ -43,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 }
@@ -54,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=
@@ -62,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
@@ -95,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
         #
@@ -111,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)
 
@@ -131,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
@@ -172,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)
@@ -192,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|
@@ -199,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]

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

@@ -1,12 +1,33 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
     module Dash
+      # Allows string and symbol access to declared Dash properties.
+      #
+      # @example
+      #   klass = Class.new(Hashie::Dash) do
+      #     include Hashie::Extensions::Dash::IndifferentAccess
+      #     property :name
+      #   end
+      #   klass.new(name: 'Ada')['name'] # => 'Ada'
       module IndifferentAccess
+        # @example Include indifferent access in a Dash subclass
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::IndifferentAccess
+        #     property :name
+        #   end
+        #   klass.property?('name') # => true
         def self.included(base)
           base.extend ClassMethods
           base.send :include, Hashie::Extensions::IndifferentAccess
         end
 
+        # @example Add Dash-specific class methods when needed
+        #   klass = Class.new(Hashie::Dash) { property :name }
+        #   Hashie::Extensions::Dash::IndifferentAccess.maybe_extend(klass)
+        #   klass.property?('name') # => true
+        #   klass.singleton_class.included_modules.include?(Hashie::Extensions::Dash::IndifferentAccess::ClassMethods) # => true
         def self.maybe_extend(base)
           return unless requires_class_methods?(base)
 
@@ -19,34 +40,91 @@ module Hashie
         end
         private_class_method :requires_class_methods?
 
+        # @example Include defaults under string keys in the returned hash
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::IndifferentAccess
+        #     property :name, default: 'Ada'
+        #     property :age
+        #   end
+        #   klass.new(age: 37).to_h # => {'name' => 'Ada', 'age' => 37}
         def to_h
-          defaults = ::Hash[self.class.properties.map do |prop|
+          defaults = self.class.properties.to_h do |prop|
             [Hashie::Extensions::IndifferentAccess.convert_key(prop), self.class.defaults[prop]]
-          end]
+          end
 
           defaults.merge(self)
         end
+        # @example
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::IndifferentAccess
+        #     property :name, default: 'Ada'
+        #   end
+        #   klass.new.to_hash # => {'name' => 'Ada'}
         alias to_hash to_h
 
+        # Class-level property and translation lookup with indifferent keys.
+        #
+        # @example
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::IndifferentAccess
+        #     property :name
+        #   end
+        #   klass.property?('name') # => true
         module ClassMethods
           # Check to see if the specified property has already been
           # defined.
+          #
+          # @example
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::IndifferentAccess
+          #     property :name
+          #   end
+          #   klass.property?('name') # => true
+          #   klass.property?(:missing) # => false
           def property?(name)
-            name = translations[name.to_sym] if translation_for?(name)
-            name = name.to_s
-            !!properties.find { |property| property.to_s == name }
+            targets = if translation_for?(name)
+                        Array(translations.find { |key, _| key.to_s == name.to_s }.last)
+                      else
+                        [name]
+                      end
+            targets.all? do |target|
+              properties.any? { |property| property.to_s == target.to_s }
+            end
           end
 
+          # @example Look up a translation with a string or symbol
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     include Hashie::Extensions::Dash::IndifferentAccess
+          #     property :name, from: :fullName
+          #   end
+          #   klass.translation_exists?('fullName') # => true
+          #   klass.translation_exists?(:missing) # => false
           def translation_exists?(name)
             name = name.to_s
             !!translations.keys.find { |key| key.to_s == name }
           end
 
+          # @example Apply a transformer declared with a symbol key
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     include Hashie::Extensions::Dash::IndifferentAccess
+          #     property :age, transform_with: ->(value) { value.to_i }
+          #   end
+          #   klass.transformed_property('age', '37') # => 37
           def transformed_property(property_name, value)
             transform = transforms[property_name] || transforms[property_name.to_sym]
             transform.call(value)
           end
 
+          # @example Find a transformer regardless of key type
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     include Hashie::Extensions::Dash::IndifferentAccess
+          #     property :age, transform_with: ->(value) { value.to_i }
+          #   end
+          #   klass.transformation_exists?('age') # => true
+          #   klass.transformation_exists?(:missing) # => false
           def transformation_exists?(name)
             name = name.to_s
             !!transforms.keys.find { |key| key.to_s == name }