Merge pull request #139 from calfzhou/feature/attr-path

tracking attribute path into options[:attr_path]

Author: dblock

.rubocop_todo.yml

@@ -7,12 +7,12 @@
 
 # Offense count: 8
 Metrics/AbcSize:
-  Max: 51
+  Max: 53
 
 # Offense count: 1
 # Configuration parameters: CountComments.
 Metrics/ClassLength:
-  Max: 328
+  Max: 346
 
 # Offense count: 5
 Metrics/CyclomaticComplexity:
@@ -26,7 +26,7 @@ Metrics/LineLength:
 # Offense count: 7
 # Configuration parameters: CountComments.
 Metrics/MethodLength:
-  Max: 32
+  Max: 37
 
 # Offense count: 5
 Metrics/PerceivedComplexity:

CHANGELOG.md

@@ -1,5 +1,6 @@
 0.5.0 (Next)
 ============
+* [#139](https://github.com/intridea/grape-entity/pull/139): Keep a track of attribute nesting path during condition check or runtime exposure - [@calfzhou](https://github.com/calfzhou).
 * Your contribution here.
 
 0.4.6 (2015-07-27)
@@ -83,4 +84,3 @@
 ==================
 
 * Initial public release - [@agileanimal](https://github.com/agileanimal).
-

README.md

@@ -334,6 +334,32 @@ end
 ```
 **Notice**: In the above code, you should pay attention to [**Safe Exposure**](#safe-exposure) yourself, for example, `instance.address` might be `nil`, in this situation, it is better to expose it as nil directly.
 
+#### Attribute Path Tracking
+
+Sometimes, especially when there are nested attributes, you might want to know which attribute it
+is being exposed. For example, some APIs allow user provide a parameter to control which fields
+will be included in (or excluded from) the response.
+
+Grape entity can track the path of each attribute, then you could access it during condition check
+or runtime exposure, via `options[:attr_path]`.
+
+Attribute path is an array. The last item of this array is the name (alias) of current attribute.
+And if the attribute is nested, the former items are names (aliases) of its ancestor attributes.
+
+Here is an example shows what the attribute path will be.
+
+```ruby
+class Status < Grape::Entity
+  expose :user  # path is [:user]
+  expose :foo, as: :bar  # path is [:bar]
+  expose :a do
+    expose :b, as: :xx do
+      expose :c  # path is [:a, :xx, :c]
+    end
+  end
+end
+```
+
 ### Using the Exposure DSL
 
 Grape ships with a DSL to easily define entities within the context of an existing class:

lib/grape_entity/entity.rb

@@ -428,22 +428,11 @@ def serializable_hash(runtime_options = {})
       opts = options.merge(runtime_options || {})
 
       root_exposures.each_with_object({}) do |(attribute, exposure_options), output|
-        next unless should_return_attribute?(attribute, opts) && conditions_met?(exposure_options, opts)
-
-        partial_output = value_for(attribute, opts)
-
-        output[self.class.key_for(attribute)] =
-          if partial_output.respond_to?(:serializable_hash)
-            partial_output.serializable_hash(runtime_options)
-          elsif partial_output.is_a?(Array) && partial_output.all? { |o| o.respond_to?(:serializable_hash) }
-            partial_output.map(&:serializable_hash)
-          elsif partial_output.is_a?(Hash)
-            partial_output.each do |key, value|
-              partial_output[key] = value.serializable_hash if value.respond_to?(:serializable_hash)
-            end
-          else
-            partial_output
-          end
+        parent_path = track_attr_path(attribute, opts)
+        if should_return_attribute?(attribute, opts) && conditions_met?(exposure_options, opts)
+          output[self.class.key_for(attribute)] = partial_hash(attribute, opts)
+        end
+        backtrack_attr_path(parent_path, opts)
       end
     end
 
@@ -529,14 +518,34 @@ def nested_value_for(attribute, options)
       nested_exposures = self.class.nested_exposures[attribute]
       nested_attributes =
         nested_exposures.map do |nested_attribute, nested_exposure_options|
-          if conditions_met?(nested_exposure_options, options)
-            [self.class.key_for(nested_attribute), value_for(nested_attribute, options)]
+          parent_path = track_attr_path(nested_attribute, options)
+          begin
+            if conditions_met?(nested_exposure_options, options)
+              [self.class.key_for(nested_attribute), value_for(nested_attribute, options)]
+            end
+          ensure
+            backtrack_attr_path(parent_path, options)
           end
         end
 
       Hash[nested_attributes.compact]
     end
 
+    def self.path_for(attribute)
+      key_for(attribute)
+    end
+
+    def track_attr_path(attribute, options)
+      parent_path = options[:attr_path]
+      current_path = self.class.path_for(attribute)
+      options[:attr_path] = (parent_path || []).dup << current_path unless current_path.nil?
+      parent_path
+    end
+
+    def backtrack_attr_path(parent_path, options)
+      options[:attr_path] = parent_path
+    end
+
     def value_for(attribute, options = {})
       exposure_options = exposures[attribute.to_sym]
       return unless valid_exposure?(attribute, exposure_options)
@@ -573,6 +582,21 @@ def value_for(attribute, options = {})
       end
     end
 
+    def partial_hash(attribute, options = {})
+      partial_output = value_for(attribute, options)
+      if partial_output.respond_to?(:serializable_hash)
+        partial_output.serializable_hash(options)
+      elsif partial_output.is_a?(Array) && !partial_output.map { |o| o.respond_to?(:serializable_hash) }.include?(false)
+        partial_output.map(&:serializable_hash)
+      elsif partial_output.is_a?(Hash)
+        partial_output.each do |key, value|
+          partial_output[key] = value.serializable_hash if value.respond_to?(:serializable_hash)
+        end
+      else
+        partial_output
+      end
+    end
+
     def delegate_attribute(attribute)
       name = self.class.name_for(attribute)
       if respond_to?(name, true)

spec/grape_entity/entity_spec.rb

@@ -829,6 +829,11 @@ class Parent < Person
         friends: [
           double(name: 'Friend 1', email: '[email protected]', characteristics: [], fantasies: [], birthday: Time.gm(2012, 2, 27), friends: []),
           double(name: 'Friend 2', email: '[email protected]', characteristics: [], fantasies: [], birthday: Time.gm(2012, 2, 27), friends: [])
+        ],
+        extra: { key: 'foo', value: 'bar' },
+        nested: [
+          { name: 'n1', data: { key: 'ex1', value: 'v1' } },
+          { name: 'n2', data: { key: 'ex2', value: 'v2' } }
         ]
       }
     end
@@ -991,6 +996,110 @@ def embedded
           expect(presenter.serializable_hash).to eq(name: 'abc', embedded: { a: nil, b: { abc: 'def' } })
         end
       end
+
+      context '#attr_path' do
+        it 'for all kinds of attributes' do
+          module EntitySpec
+            class EmailEntity < Grape::Entity
+              expose(:email, as: :addr) { |_, o| o[:attr_path].join('/') }
+            end
+
+            class UserEntity < Grape::Entity
+              expose(:name, as: :full_name) { |_, o| o[:attr_path].join('/') }
+              expose :email, using: 'EntitySpec::EmailEntity'
+            end
+
+            class ExtraEntity < Grape::Entity
+              expose(:key) { |_, o| o[:attr_path].join('/') }
+              expose(:value) { |_, o| o[:attr_path].join('/') }
+            end
+
+            class NestedEntity < Grape::Entity
+              expose(:name) { |_, o| o[:attr_path].join('/') }
+              expose :data, using: 'EntitySpec::ExtraEntity'
+            end
+          end
+
+          fresh_class.class_eval do
+            expose(:id) { |_, o| o[:attr_path].join('/') }
+            expose(:foo, as: :bar) { |_, o| o[:attr_path].join('/') }
+            expose :title do
+              expose :full do
+                expose(:prefix, as: :pref) { |_, o| o[:attr_path].join('/') }
+                expose(:main) { |_, o| o[:attr_path].join('/') }
+              end
+            end
+            expose :friends, as: :social, using: 'EntitySpec::UserEntity'
+            expose :extra, using: 'EntitySpec::ExtraEntity'
+            expose :nested, using: 'EntitySpec::NestedEntity'
+          end
+
+          expect(subject.serializable_hash).to eq(
+            id: 'id',
+            bar: 'bar',
+            title: { full: { pref: 'title/full/pref', main: 'title/full/main' } },
+            social: [
+              { full_name: 'social/full_name', email: { addr: 'social/email/addr' } },
+              { full_name: 'social/full_name', email: { addr: 'social/email/addr' } }
+            ],
+            extra: { key: 'extra/key', value: 'extra/value' },
+            nested: [
+              { name: 'nested/name', data: { key: 'nested/data/key', value: 'nested/data/value' } },
+              { name: 'nested/name', data: { key: 'nested/data/key', value: 'nested/data/value' } }
+            ]
+          )
+        end
+
+        it 'allows customize path of an attribute' do
+          module EntitySpec
+            class CharacterEntity < Grape::Entity
+              expose(:key) { |_, o| o[:attr_path].join('/') }
+              expose(:value) { |_, o| o[:attr_path].join('/') }
+            end
+          end
+
+          fresh_class.class_eval do
+            expose :characteristics, using: EntitySpec::CharacterEntity
+
+            protected
+
+            def self.path_for(attribute)
+              attribute == :characteristics ? :character : super
+            end
+          end
+
+          expect(subject.serializable_hash).to eq(
+            characteristics: [
+              { key: 'character/key', value: 'character/value' }
+            ]
+          )
+        end
+
+        it 'can drop one nest level by set path_for to nil' do
+          module EntitySpec
+            class NoPathCharacterEntity < Grape::Entity
+              expose(:key) { |_, o| o[:attr_path].join('/') }
+              expose(:value) { |_, o| o[:attr_path].join('/') }
+            end
+          end
+
+          fresh_class.class_eval do
+            expose :characteristics, using: EntitySpec::NoPathCharacterEntity
+
+            protected
+
+            def self.path_for(_attribute)
+              nil
+            end
+          end
+
+          expect(subject.serializable_hash).to eq(
+            characteristics: [
+              { key: 'key', value: 'value' }
+            ]
+          )
+        end
+      end
     end
 
     describe '#value_for' do