hashie 4.1.0 → 5.2.0

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
     module Dash
@@ -7,12 +9,12 @@ module Hashie
       # application -- such as a Java API -- where the keys are named
       # differently from Ruby conventions.
       #
-      # == Example from inconsistent APIs
+      # @example Translate inconsistent API keys
       #
       #   class PersonHash < Hashie::Dash
       #     include Hashie::Extensions::Dash::PropertyTranslation
       #
-      #     property :first_name, from :firstName
+      #     property :first_name, from: :firstName
       #     property :last_name, from: :lastName
       #     property :first_name, from: :f_name
       #     property :last_name, from: :l_name
@@ -25,7 +27,8 @@ module Hashie
       # You can also use a lambda to translate the value. This is particularly
       # useful when you want to ensure the type of data you're wrapping.
       #
-      # == Example using translation lambdas
+      # @example Transform input values
+      #   require 'time'
       #
       #   class DataModelHash < Hashie::Dash
       #     include Hashie::Extensions::Dash::PropertyTranslation
@@ -35,28 +38,66 @@ module Hashie
       #   end
       #
       #   model = DataModelHash.new(id: '123', created: '2014-04-25 22:35:28')
-      #   model.id.class          #=> Integer (Fixnum if you are using Ruby 2.3 or lower)
+      #   model.id.class          #=> Integer
       #   model.created_at.class  #=> Time
       module PropertyTranslation
+        # @example Install translation declarations on a Dash
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::PropertyTranslation
+        #     property :name, from: :fullName
+        #   end
+        #   klass.new(fullName: 'Ada').name # => 'Ada'
         def self.included(base)
           base.instance_variable_set(:@transforms, {})
           base.instance_variable_set(:@translations_hash, ::Hash.new { |hash, key| hash[key] = {} })
           base.extend(ClassMethods)
           base.send(:include, InstanceMethods)
+          base.extend Hashie::Extensions::DeepMerge
         end
 
+        # Defines input translations and value transformations.
+        #
+        # @example
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::PropertyTranslation
+        #     property :name, from: :fullName
+        #   end
+        #   klass.translations # => {fullName: :name}
         module ClassMethods
+          # @example Inspect value transformers
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :age, transform_with: ->(value) { value.to_i }
+          #   end
+          #   klass.transforms[:age].call('37') # => 37
+          #   klass.translations_hash # => {}
           attr_reader :transforms, :translations_hash
 
           # Ensures that any inheriting classes maintain their translations.
           #
-          # * <tt>:default</tt> - The class inheriting the translations.
+          # * `:default` - The class inheriting the translations.
+          #
+          # @example Copy translation settings to subclasses
+          #   parent = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :name, from: :fullName
+          #   end
+          #   child = Class.new(parent) { property :age, from: :years }
+          #   child.new(fullName: 'Ada', years: 37).age # => 37
+          #   parent.translations # => {fullName: :name}
           def inherited(klass)
             super
             klass.instance_variable_set(:@transforms, transforms.dup)
-            klass.instance_variable_set(:@translations_hash, translations_hash.dup)
+            klass.instance_variable_set(:@translations_hash, _deep_dup(translations_hash))
           end
 
+          # @example List translated input keys alongside untranslated properties
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :name, from: :fullName
+          #     property :age
+          #   end
+          #   klass.permitted_input_keys # => [:fullName, :age]
           def permitted_input_keys
             @permitted_input_keys ||=
               properties
@@ -65,12 +106,19 @@ module Hashie
 
           # Defines a property on the Trash. Options are as follows:
           #
-          # * <tt>:default</tt> - Specify a default value for this property, to be
+          # * `:default` - Specify a default value for this property, to be
           # returned before a value is set on the property in a new Dash.
-          # * <tt>:from</tt> - Specify the original key name that will be write only.
-          # * <tt>:with</tt> - Specify a lambda to be used to convert value.
-          # * <tt>:transform_with</tt> - Specify a lambda to be used to convert value
+          # * `:from` - Specify the original key name that will be write only.
+          # * `:with` - Specify a lambda to be used to convert value.
+          # * `:transform_with` - Specify a lambda to be used to convert value
           # without using the :from option. It transform the property itself.
+          #
+          # @example Declare a translated and converted property
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :age, from: :years, with: ->(value) { value.to_i }
+          #   end
+          #   klass.new(years: '37').age # => 37
           def property(property_name, options = {})
             super
 
@@ -79,7 +127,7 @@ module Hashie
             transformer = options[:transform_with]
 
             if from
-              fail_self_transformation_error!(property_name) if property_name == from
+              fail_self_transformation_error!(property_name) if property_name.to_s == from.to_s
               define_translation(from, property_name, converter || transformer)
               define_writer_for_source_property(from)
             elsif valid_transformer?(transformer)
@@ -87,18 +135,44 @@ module Hashie
             end
           end
 
+          # @example Apply a declared transformer directly
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :age, transform_with: ->(value) { value.to_i }
+          #   end
+          #   klass.transformed_property(:age, '37') # => 37
           def transformed_property(property_name, value)
             transforms[property_name].call(value)
           end
 
+          # @example Check for a property transformer
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :age, transform_with: ->(value) { value.to_i }
+          #   end
+          #   klass.transformation_exists?(:age) # => true
+          #   klass.transformation_exists?(:name) # => false
           def transformation_exists?(name)
             transforms.key? name
           end
 
+          # @example Check for a translated source key
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :name, from: :fullName
+          #   end
+          #   klass.translation_exists?(:fullName) # => true
+          #   klass.translation_exists?(:name) # => false
           def translation_exists?(name)
             translations_hash.key? name
           end
 
+          # @example Map source keys to destination properties
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :name, from: :fullName
+          #   end
+          #   klass.translations # => {fullName: :name}
           def translations
             @translations ||= {}.tap do |translations|
               translations_hash.each do |(property_name, property_translations)|
@@ -112,6 +186,12 @@ module Hashie
             end
           end
 
+          # @example Map destination properties back to source keys
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :name, from: :fullName
+          #   end
+          #   klass.inverse_translations # => {name: :fullName}
           def inverse_translations
             @inverse_translations ||= {}.tap do |translations|
               translations_hash.each do |(property_name, property_translations)|
@@ -138,7 +218,7 @@ module Hashie
 
           def fail_self_transformation_error!(property_name)
             raise ArgumentError,
-                  "Property name (#{property_name}) and :from option must not be the same"
+                  "property name `#{property_name}` and :from option must not be the same"
           end
 
           def valid_transformer?(transformer)
@@ -146,34 +226,77 @@ module Hashie
           end
         end
 
+        # Applies translations and transformations during assignment.
+        #
+        # @example
+        #   klass = Class.new(Hashie::Dash) do
+        #     include Hashie::Extensions::Dash::PropertyTranslation
+        #     property :name, from: :fullName
+        #   end
+        #   klass.new(fullName: 'Ada').name # => 'Ada'
         module InstanceMethods
           # Sets a value on the Dash in a Hash-like way.
           #
           # Note: Only works on pre-existing properties.
+          #
+          # @example Assign through a translated source key
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :name, from: :fullName
+          #   end
+          #   dash = klass.new
+          #   dash[:fullName] = 'Ada'
+          #   dash.name # => 'Ada'
           def []=(property, value)
             if self.class.translation_exists? property
               send("#{property}=", value)
-              super(property, value) if self.class.properties.include?(property)
+
+              if self.class.transformation_exists? property
+                super(property, self.class.transformed_property(property, value))
+              elsif self.class.properties.include?(property)
+                super
+              end
             elsif self.class.transformation_exists? property
-              super property, self.class.transformed_property(property, value)
+              super(property, self.class.transformed_property(property, value))
             elsif property_exists? property
               super
             end
           end
 
           # Deletes any keys that have a translation
+          #
+          # @example Initialize translated input without modifying the source
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :name, from: :fullName
+          #   end
+          #   attributes = {fullName: 'Ada'}
+          #   dash = klass.new
+          #   dash.initialize_attributes(attributes)
+          #   dash.name # => 'Ada'
+          #   attributes # => {fullName: 'Ada'}
           def initialize_attributes(attributes)
             return unless attributes
+
             attributes_copy = attributes.dup.delete_if do |k, v|
               if self.class.translations_hash.include?(k)
                 self[k] = v
                 true
               end
             end
-            super attributes_copy
+            super(attributes_copy)
           end
 
           # Raises an NoMethodError if the property doesn't exist
+          #
+          # @example Check for an existing property
+          #   klass = Class.new(Hashie::Dash) do
+          #     include Hashie::Extensions::Dash::PropertyTranslation
+          #     property :name
+          #   end
+          #   dash = klass.new
+          #   dash.property_exists?(:name) # => true
+          #   expect { dash.property_exists?(:missing) }.to raise_error(NoMethodError)
           def property_exists?(property)
             fail_no_property_error!(property) unless self.class.property?(property)
             true

data/lib/hashie/extensions/deep_fetch.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
-    # Searches a deeply nested datastructure for a key path, and returns the associated value.
+    # Searches a deeply nested data structure for a key path, and returns the associated value.
     #
     #  options = { user: { location: { address: '123 Street' } } }
     #  options.deep_fetch :user, :location, :address #=> '123 Street'
@@ -11,19 +13,29 @@ module Hashie
     #
     # This is particularly useful for fetching values from deeply nested api responses
     #   or params hashes.
+    #
+    # @example Traverse hashes and arrays
+    #   hash = { users: [{ name: 'Ada' }] }.extend(Hashie::Extensions::DeepFetch)
+    #   hash.deep_fetch(:users, 0, :name) # => 'Ada'
     module DeepFetch
+      # @example Report an undefined path
+      #   error = Hashie::Extensions::DeepFetch::UndefinedPathError.new('missing address')
+      #   error.message # => 'missing address'
       class UndefinedPathError < StandardError; end
 
+      # @example Use a fallback for a missing path
+      #   hash = { user: {} }.extend(Hashie::Extensions::DeepFetch)
+      #   hash.deep_fetch(:user, :name) { |key| "missing #{key}" } # => 'missing name'
+      #   hash.deep_fetch(:user) # => {}
       def deep_fetch(*args, &block)
         args.reduce(self) do |obj, arg|
-          begin
-            arg = Integer(arg) if obj.is_a? Array
-            obj.fetch(arg)
-          rescue ArgumentError, IndexError, NoMethodError => e
-            break yield(arg) if block
-            raise UndefinedPathError,
-                  "Could not fetch path (#{args.join(' > ')}) at #{arg}", e.backtrace
-          end
+          arg = Integer(arg) if obj.is_a? Array
+          obj.fetch(arg)
+        rescue ArgumentError, IndexError, NoMethodError => e
+          break yield(arg) if block
+
+          raise UndefinedPathError,
+                "could not fetch path (`#{args.join(' > ')}`) at `#{arg}`", e.backtrace
         end
       end
     end

data/lib/hashie/extensions/deep_find.rb

@@ -1,6 +1,11 @@
+# frozen_string_literal: true
+
 require 'hashie/extensions/deep_locate'
 module Hashie
   module Extensions
+    # @example Find values in nested collections
+    #   hash = { users: [{ name: 'Ada' }] }.extend(Hashie::Extensions::DeepFind)
+    #   hash.deep_find(:name) # => 'Ada'
     module DeepFind
       # Performs a depth-first search on deeply nested data structures for
       # a key and returns the first occurrence of the key.
@@ -16,10 +21,17 @@ module Hashie
       #  my_hash = MyHash.new
       #  my_hash[:user] = {location: {address: '123 Street'}}
       #  my_hash.deep_find(:address) # => '123 Street'
+      #
+      # @example Return the first value
+      #   hash = { users: [{ name: 'Ada' }, { name: 'Grace' }] }.extend(Hashie::Extensions::DeepFind)
+      #   hash.deep_find(:name) # => 'Ada'
       def deep_find(key)
         _deep_find(key)
       end
 
+      # @example Detect the first nested value
+      #   hash = { user: { name: 'Ada' } }.extend(Hashie::Extensions::DeepFind)
+      #   hash.deep_detect(:name) # => 'Ada'
       alias deep_detect deep_find
 
       # Performs a depth-first search on deeply nested data structures for
@@ -44,11 +56,19 @@ module Hashie
       #    {location: {address: '234 Street'}}
       #  ]
       #  my_hash.deep_find_all(:address) # => ['123 Street', '234 Street']
+      #
+      # @example Collect all values, or nil if absent
+      #   hash = { users: [{ name: 'Ada' }, { name: 'Grace' }] }.extend(Hashie::Extensions::DeepFind)
+      #   hash.deep_find_all(:name) # => ['Ada', 'Grace']
+      #   hash.deep_find_all(:email) # => nil
       def deep_find_all(key)
         matches = _deep_find_all(key)
         matches.empty? ? nil : matches
       end
 
+      # @example Select every nested value
+      #   hash = { users: [{ name: 'Ada' }, { name: 'Grace' }] }.extend(Hashie::Extensions::DeepFind)
+      #   hash.deep_select(:name) # => ['Ada', 'Grace']
       alias deep_select deep_find_all
 
       private

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, incase you do not want
-      # to include/extend the base datastructure. For further examples please
+      # The module level implementation of #deep_locate, in case you do not want
+      # 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,18 +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
-        attributes.each_pair do |att, value|
-          next unless klass.property?(att) || (translations && translations.include?(att))
-          self[att] = value
-        end
+        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