hashie 2.1.2 → 4.1.0

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

@@ -0,0 +1,25 @@
+module Hashie
+  module Extensions
+    module Dash
+      module Coercion
+        # Extends a Dash with the ability to define coercion for properties.
+
+        def self.included(base)
+          base.send :include, Hashie::Extensions::Coercion
+          base.extend ClassMethods
+        end
+
+        module ClassMethods
+          # Defines a property on the Dash. Options are the standard
+          # <tt>Hashie::Dash#property</tt> options plus:
+          #
+          # * <tt>:coerce</tt> - The class into which you want the property coerced.
+          def property(property_name, options = {})
+            super
+            coerce_key property_name, options[:coerce] if options[:coerce]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+module Hashie
+  module Extensions
+    module Dash
+      module IndifferentAccess
+        def self.included(base)
+          base.extend ClassMethods
+          base.send :include, Hashie::Extensions::IndifferentAccess
+        end
+
+        def self.maybe_extend(base)
+          return unless requires_class_methods?(base)
+
+          base.extend(ClassMethods)
+        end
+
+        def self.requires_class_methods?(klass)
+          klass <= Hashie::Dash &&
+            !klass.singleton_class.included_modules.include?(ClassMethods)
+        end
+        private_class_method :requires_class_methods?
+
+        module ClassMethods
+          # Check to see if the specified property has already been
+          # defined.
+          def property?(name)
+            name = translations[name.to_sym] if translation_for?(name)
+            name = name.to_s
+            !!properties.find { |property| property.to_s == name }
+          end
+
+          def translation_exists?(name)
+            name = name.to_s
+            !!translations.keys.find { |key| key.to_s == name }
+          end
+
+          def transformed_property(property_name, value)
+            transform = transforms[property_name] || transforms[property_name.to_sym]
+            transform.call(value)
+          end
+
+          def transformation_exists?(name)
+            name = name.to_s
+            !!transforms.keys.find { |key| key.to_s == name }
+          end
+
+          private
+
+          def translation_for?(name)
+            included_modules.include?(Hashie::Extensions::Dash::PropertyTranslation) &&
+              translation_exists?(name)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,191 @@
+module Hashie
+  module Extensions
+    module Dash
+      # Extends a Dash with the ability to remap keys from a source hash.
+      #
+      # Property translation is useful when you need to read data from another
+      # application -- such as a Java API -- where the keys are named
+      # differently from Ruby conventions.
+      #
+      # == Example from inconsistent APIs
+      #
+      #   class PersonHash < Hashie::Dash
+      #     include Hashie::Extensions::Dash::PropertyTranslation
+      #
+      #     property :first_name, from :firstName
+      #     property :last_name, from: :lastName
+      #     property :first_name, from: :f_name
+      #     property :last_name, from: :l_name
+      #   end
+      #
+      #   person = PersonHash.new(firstName: 'Michael', l_name: 'Bleigh')
+      #   person[:first_name]  #=> 'Michael'
+      #   person[:last_name]   #=> 'Bleigh'
+      #
+      # 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
+      #
+      #   class DataModelHash < Hashie::Dash
+      #     include Hashie::Extensions::Dash::PropertyTranslation
+      #
+      #     property :id, transform_with: ->(value) { value.to_i }
+      #     property :created_at, from: :created, with: ->(value) { Time.parse(value) }
+      #   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.created_at.class  #=> Time
+      module PropertyTranslation
+        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)
+        end
+
+        module ClassMethods
+          attr_reader :transforms, :translations_hash
+
+          # Ensures that any inheriting classes maintain their translations.
+          #
+          # * <tt>:default</tt> - The class inheriting the translations.
+          def inherited(klass)
+            super
+            klass.instance_variable_set(:@transforms, transforms.dup)
+            klass.instance_variable_set(:@translations_hash, translations_hash.dup)
+          end
+
+          def permitted_input_keys
+            @permitted_input_keys ||=
+              properties
+              .map { |property| inverse_translations.fetch property, property }
+          end
+
+          # Defines a property on the Trash. Options are as follows:
+          #
+          # * <tt>:default</tt> - 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
+          # without using the :from option. It transform the property itself.
+          def property(property_name, options = {})
+            super
+
+            from = options[:from]
+            converter = options[:with]
+            transformer = options[:transform_with]
+
+            if from
+              fail_self_transformation_error!(property_name) if property_name == from
+              define_translation(from, property_name, converter || transformer)
+              define_writer_for_source_property(from)
+            elsif valid_transformer?(transformer)
+              transforms[property_name] = transformer
+            end
+          end
+
+          def transformed_property(property_name, value)
+            transforms[property_name].call(value)
+          end
+
+          def transformation_exists?(name)
+            transforms.key? name
+          end
+
+          def translation_exists?(name)
+            translations_hash.key? name
+          end
+
+          def translations
+            @translations ||= {}.tap do |translations|
+              translations_hash.each do |(property_name, property_translations)|
+                translations[property_name] =
+                  if property_translations.size > 1
+                    property_translations.keys
+                  else
+                    property_translations.keys.first
+                  end
+              end
+            end
+          end
+
+          def inverse_translations
+            @inverse_translations ||= {}.tap do |translations|
+              translations_hash.each do |(property_name, property_translations)|
+                property_translations.each_key do |key|
+                  translations[key] = property_name
+                end
+              end
+            end
+          end
+
+          private
+
+          def define_translation(from, property_name, translator)
+            translations_hash[from][property_name] = translator
+          end
+
+          def define_writer_for_source_property(property)
+            define_method "#{property}=" do |val|
+              __translations[property].each do |name, with|
+                self[name] = with.respond_to?(:call) ? with.call(val) : val
+              end
+            end
+          end
+
+          def fail_self_transformation_error!(property_name)
+            raise ArgumentError,
+                  "Property name (#{property_name}) and :from option must not be the same"
+          end
+
+          def valid_transformer?(transformer)
+            transformer.respond_to? :call
+          end
+        end
+
+        module InstanceMethods
+          # Sets a value on the Dash in a Hash-like way.
+          #
+          # Note: Only works on pre-existing properties.
+          def []=(property, value)
+            if self.class.translation_exists? property
+              send("#{property}=", value)
+              super(property, value) if self.class.properties.include?(property)
+            elsif self.class.transformation_exists? property
+              super property, self.class.transformed_property(property, value)
+            elsif property_exists? property
+              super
+            end
+          end
+
+          # Deletes any keys that have a translation
+          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
+          end
+
+          # Raises an NoMethodError if the property doesn't exist
+          def property_exists?(property)
+            fail_no_property_error!(property) unless self.class.property?(property)
+            true
+          end
+
+          private
+
+          def __translations
+            self.class.translations_hash
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hashie/extensions/deep_fetch.rb

@@ -9,18 +9,20 @@ module Hashie
     #
     #  options.deep_fetch(:user, :non_existent_key) { 'a value' } #=> 'a value'
     #
-    # This is particularly useful for fetching values from deeply nested api responses or params hashes.
+    # This is particularly useful for fetching values from deeply nested api responses
+    #   or params hashes.
     module DeepFetch
       class UndefinedPathError < StandardError; end
 
       def deep_fetch(*args, &block)
         args.reduce(self) do |obj, arg|
           begin
-            arg = Integer(arg) if obj.kind_of? Array
+            arg = Integer(arg) if obj.is_a? Array
             obj.fetch(arg)
-          rescue ArgumentError, IndexError => e
-            break block.call(arg) if block
-            raise UndefinedPathError, "Could not fetch path (#{args.join(' > ')}) at #{arg}", e.backtrace
+          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

@@ -0,0 +1,69 @@
+require 'hashie/extensions/deep_locate'
+module Hashie
+  module Extensions
+    module DeepFind
+      # Performs a depth-first search on deeply nested data structures for
+      # a key and returns the first occurrence of the key.
+      #
+      #  options = {user: {location: {address: '123 Street'}}}
+      #  options.extend(Hashie::Extensions::DeepFind)
+      #  options.deep_find(:address) # => '123 Street'
+      #
+      #  class MyHash < Hash
+      #    include Hashie::Extensions::DeepFind
+      #  end
+      #
+      #  my_hash = MyHash.new
+      #  my_hash[:user] = {location: {address: '123 Street'}}
+      #  my_hash.deep_find(:address) # => '123 Street'
+      def deep_find(key)
+        _deep_find(key)
+      end
+
+      alias deep_detect deep_find
+
+      # Performs a depth-first search on deeply nested data structures for
+      # a key and returns all occurrences of the key.
+      #
+      #  options = {
+      #    users: [
+      #      { location: {address: '123 Street'} },
+      #      { location: {address: '234 Street'}}
+      #    ]
+      #  }
+      #  options.extend(Hashie::Extensions::DeepFind)
+      #  options.deep_find_all(:address) # => ['123 Street', '234 Street']
+      #
+      #  class MyHash < Hash
+      #    include Hashie::Extensions::DeepFind
+      #  end
+      #
+      #  my_hash = MyHash.new
+      #  my_hash[:users] = [
+      #    {location: {address: '123 Street'}},
+      #    {location: {address: '234 Street'}}
+      #  ]
+      #  my_hash.deep_find_all(:address) # => ['123 Street', '234 Street']
+      def deep_find_all(key)
+        matches = _deep_find_all(key)
+        matches.empty? ? nil : matches
+      end
+
+      alias deep_select deep_find_all
+
+      private
+
+      def _deep_find(key, object = self)
+        _deep_find_all(key, object).first
+      end
+
+      def _deep_find_all(key, object = self, matches = [])
+        deep_locate_result = DeepLocate.deep_locate(key, object).tap do |result|
+          result.map! { |element| element[key] }
+        end
+
+        matches.concat(deep_locate_result)
+      end
+    end
+  end
+end

data/lib/hashie/extensions/deep_locate.rb

@@ -0,0 +1,113 @@
+module Hashie
+  module Extensions
+    module DeepLocate
+      # The module level implementation of #deep_locate, incase you do not want
+      # to include/extend the base datastructure. 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}, ...]
+      def self.deep_locate(comparator, object)
+        unless comparator.respond_to?(:call)
+          comparator = _construct_key_comparator(comparator, object)
+        end
+
+        _deep_locate(comparator, object)
+      end
+
+      # Performs a depth-first search on deeply nested data structures for a
+      # given comparator callable and returns each Enumerable, for which the
+      # callable returns true for at least one the its elements.
+      #
+      # @example
+      #   books = [
+      #     {
+      #       title: "Ruby for beginners",
+      #       pages: 120
+      #     },
+      #     {
+      #       title: "CSS for intermediates",
+      #       pages: 80
+      #     },
+      #     {
+      #       title: "Collection of ruby books",
+      #       books: [
+      #         {
+      #           title: "Ruby for the rest of us",
+      #           pages: 576
+      #         }
+      #       ]
+      #     }
+      #   ]
+      #
+      #   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}]
+      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? ||
+           activesupport_indifferent?(object)
+          search_key = search_key.to_s
+        end
+
+        lambda do |non_callable_object|
+          ->(key, _, _) { key == non_callable_object }
+        end.call(search_key)
+      end
+      private_class_method :_construct_key_comparator
+
+      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
+
+          (object.respond_to?(:values) ? object.values : object.entries).each do |value|
+            _deep_locate(comparator, value, result)
+          end
+        end
+
+        result
+      end
+      private_class_method :_deep_locate
+
+      def self._match_comparator?(value, comparator, object)
+        if object.is_a?(::Hash)
+          key, value = value
+        else
+          key = nil
+        end
+
+        comparator.call(key, value, object)
+      end
+      private_class_method :_match_comparator?
+
+      def self.activesupport_indifferent?(object)
+        defined?(::ActiveSupport::HashWithIndifferentAccess) &&
+          object.is_a?(::ActiveSupport::HashWithIndifferentAccess)
+      end
+      private_class_method :activesupport_indifferent?
+    end
+  end
+end