grape-entity 0.6.0 → 0.10.1

data/lib/grape_entity/entity.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'multi_json'
 require 'set'
 
@@ -103,7 +105,7 @@ module Grape
         @root_exposure ||= Exposure.new(nil, nesting: true)
       end
 
-      attr_writer :root_exposure
+      attr_writer :root_exposure, :formatters
 
       # Returns all formatters that are registered for this and it's ancestors
       # @return [Hash] of formatters
@@ -111,7 +113,23 @@ module Grape
         @formatters ||= {}
       end
 
-      attr_writer :formatters
+      def hash_access
+        @hash_access ||= :to_sym
+      end
+
+      def hash_access=(value)
+        @hash_access =
+          case value
+          when :to_s, :str, :string
+            :to_s
+          else
+            :to_sym
+          end
+      end
+
+      def delegation_opts
+        @delegation_opts ||= { hash_access: hash_access }
+      end
     end
 
     @formatters = {}
@@ -119,12 +137,33 @@ module Grape
     def self.inherited(subclass)
       subclass.root_exposure = root_exposure.dup
       subclass.formatters = formatters.dup
+
+      super
     end
 
     # This method is the primary means by which you will declare what attributes
     # should be exposed by the entity.
     #
+    # @option options :expose_nil When set to false the associated exposure will not
+    #   be rendered if its value is nil.
+    #
     # @option options :as Declare an alias for the representation of this attribute.
+    #   If a proc is presented it is evaluated in the context of the entity so object
+    #   and the entity methods are available to it.
+    #
+    # @example as: a proc or lambda
+    #
+    #   object = OpenStruct(awesomeness: 'awesome_key', awesome: 'not-my-key', other: 'other-key' )
+    #
+    #   class MyEntity < Grape::Entity
+    #     expose :awesome, as: proc { object.awesomeness }
+    #     expose :awesomeness, as: ->(object, opts) { object.other }
+    #   end
+    #
+    #   => { 'awesome_key': 'not-my-key', 'other-key': 'awesome_key' }
+    #
+    # Note the parameters passed in via the lambda syntax.
+    #
     # @option options :if When passed a Hash, the attribute will only be exposed if the
     #   runtime options match all the conditions passed in. When passed a lambda, the
     #   lambda will execute with two arguments: the object being represented and the
@@ -147,17 +186,23 @@ module Grape
     # @option options :documentation Define documenation for an exposed
     #   field, typically the value is a hash with two fields, type and desc.
     # @option options :merge This option allows you to merge an exposed field to the root
+    #
+    # rubocop:disable Layout/LineLength
     def self.expose(*args, &block)
       options = merge_options(args.last.is_a?(Hash) ? args.pop : {})
 
       if args.size > 1
+
         raise ArgumentError, 'You may not use the :as option on multi-attribute exposures.' if options[:as]
+        raise ArgumentError, 'You may not use the :expose_nil on multi-attribute exposures.' if options.key?(:expose_nil)
         raise ArgumentError, 'You may not use block-setting on multi-attribute exposures.' if block_given?
       end
 
-      raise ArgumentError, 'You may not use block-setting when also using format_with' if block_given? && options[:format_with].respond_to?(:call)
-
       if block_given?
+        if options[:format_with].respond_to?(:call)
+          raise ArgumentError, 'You may not use block-setting when also using format_with'
+        end
+
         if block.parameters.any?
           options[:proc] = block
         else
@@ -167,24 +212,25 @@ module Grape
 
       @documentation = nil
       @nesting_stack ||= []
+      args.each { |attribute| build_exposure_for_attribute(attribute, @nesting_stack, options, block) }
+    end
+    # rubocop:enable Layout/LineLength
 
-      # rubocop:disable Style/Next
-      args.each do |attribute|
-        exposure = Exposure.new(attribute, options)
+    def self.build_exposure_for_attribute(attribute, nesting_stack, options, block)
+      exposure_list = nesting_stack.empty? ? root_exposures : nesting_stack.last.nested_exposures
 
-        if @nesting_stack.empty?
-          root_exposures << exposure
-        else
-          @nesting_stack.last.nested_exposures << exposure
-        end
+      exposure = Exposure.new(attribute, options)
 
-        # Nested exposures are given in a block with no parameters.
-        if exposure.nesting?
-          @nesting_stack << exposure
-          block.call
-          @nesting_stack.pop
-        end
-      end
+      exposure_list.delete_by(attribute) if exposure.override?
+
+      exposure_list << exposure
+
+      # Nested exposures are given in a block with no parameters.
+      return unless exposure.nesting?
+
+      nesting_stack << exposure
+      block.call
+      nesting_stack.pop
     end
 
     # Returns exposures that have been declared for this Entity on the top level.
@@ -237,9 +283,7 @@ module Grape
     # #docmentation, any exposure without a documentation key will be ignored.
     def self.documentation
       @documentation ||= root_exposures.each_with_object({}) do |exposure, memo|
-        if exposure.documentation && !exposure.documentation.empty?
-          memo[exposure.key] = exposure.documentation
-        end
+        memo[exposure.key] = exposure.documentation if exposure.documentation && !exposure.documentation.empty?
       end
     end
 
@@ -271,6 +315,7 @@ module Grape
     #
     def self.format_with(name, &block)
       raise ArgumentError, 'You must pass a block for formatters' unless block_given?
+
       formatters[name.to_sym] = block
     end
 
@@ -392,6 +437,7 @@ module Grape
     # @option options :only [Array] all the fields that should be returned
     # @option options :except [Array] all the fields that should not be returned
     def self.represent(objects, options = {})
+      @present_collection ||= nil
       if objects.respond_to?(:to_ary) && !@present_collection
         root_element = root_element(:collection_root)
         inner = objects.to_ary.map { |object| new(object, options.reverse_merge(collection: true)).presented }
@@ -409,8 +455,9 @@ module Grape
     # This method returns the entity's root or collection root node, or its parent's
     # @param root_type: either :collection_root or just :root
     def self.root_element(root_type)
-      if instance_variable_get("@#{root_type}")
-        instance_variable_get("@#{root_type}")
+      instance_variable = "@#{root_type}"
+      if instance_variable_defined?(instance_variable) && instance_variable_get(instance_variable)
+        instance_variable_get(instance_variable)
       elsif superclass.respond_to? :root_element
         superclass.root_element(root_type)
       end
@@ -432,12 +479,8 @@ module Grape
 
     def initialize(object, options = {})
       @object = object
-      @delegator = Delegator.new object
-      @options = if options.is_a? Options
-                   options
-                 else
-                   Options.new options
-                 end
+      @options = options.is_a?(Options) ? options : Options.new(options)
+      @delegator = Delegator.new(object)
     end
 
     def root_exposures
@@ -472,7 +515,16 @@ module Grape
     end
 
     def exec_with_object(options, &block)
-      instance_exec(object, options, &block)
+      if block.parameters.count == 1
+        instance_exec(object, &block)
+      else
+        instance_exec(object, options, &block)
+      end
+    rescue StandardError => e
+      # it handles: https://github.com/ruby/ruby/blob/v3_0_0_preview1/NEWS.md#language-changes point 3, Proc
+      raise Grape::Entity::Deprecated.new e.message, 'in ruby 3.0' if e.is_a?(ArgumentError)
+
+      raise e
     end
 
     def exec_with_attribute(attribute, &block)
@@ -484,28 +536,53 @@ module Grape
     end
 
     def delegate_attribute(attribute)
-      if respond_to?(attribute, true) && Grape::Entity > method(attribute).owner
+      if is_defined_in_entity?(attribute)
         send(attribute)
+      elsif delegator.accepts_options?
+        delegator.delegate(attribute, **self.class.delegation_opts)
       else
         delegator.delegate(attribute)
       end
     end
 
+    def is_defined_in_entity?(attribute)
+      return false unless respond_to?(attribute, true)
+
+      ancestors = self.class.ancestors
+      ancestors.index(Grape::Entity) > ancestors.index(method(attribute).owner)
+    end
+
     alias as_json serializable_hash
 
     def to_json(options = {})
-      options = options.to_h if options && options.respond_to?(:to_h)
+      options = options.to_h if options&.respond_to?(:to_h)
       MultiJson.dump(serializable_hash(options))
     end
 
     def to_xml(options = {})
-      options = options.to_h if options && options.respond_to?(:to_h)
+      options = options.to_h if options&.respond_to?(:to_h)
       serializable_hash(options).to_xml(options)
     end
 
     # All supported options.
-    OPTIONS = [
-      :rewrite, :as, :if, :unless, :using, :with, :proc, :documentation, :format_with, :safe, :attr_path, :if_extras, :unless_extras, :merge
+    OPTIONS = %i[
+      rewrite
+      as
+      if
+      unless
+      using
+      with
+      proc
+      documentation
+      format_with
+      safe
+      attr_path
+      if_extras
+      unless_extras
+      merge
+      expose_nil
+      override
+      default
     ].to_set.freeze
 
     # Merges the given options with current block options.
@@ -515,7 +592,7 @@ module Grape
       opts = {}
 
       merge_logic = proc do |key, existing_val, new_val|
-        if [:if, :unless].include?(key)
+        if %i[if unless].include?(key)
           if existing_val.is_a?(Hash) && new_val.is_a?(Hash)
             existing_val.merge(new_val)
           elsif new_val.is_a?(Hash)
@@ -541,7 +618,7 @@ module Grape
     #
     # @param options [Hash] Exposure options.
     def self.valid_options(options)
-      options.keys.each do |key|
+      options.each_key do |key|
         raise ArgumentError, "#{key.inspect} is not a valid option." unless OPTIONS.include?(key)
       end
 

data/lib/grape_entity/exposure/base.rb

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 module Grape
   class Entity
     module Exposure
       class Base
-        attr_reader :attribute, :key, :is_safe, :documentation, :conditions, :for_merge
+        attr_reader :attribute, :is_safe, :documentation, :override, :conditions, :for_merge
 
         def self.new(attribute, options, conditions, *args, &block)
           super(attribute, options, conditions).tap { |e| e.setup(*args, &block) }
@@ -11,11 +13,14 @@ module Grape
         def initialize(attribute, options, conditions)
           @attribute = attribute.try(:to_sym)
           @options = options
-          @key = (options[:as] || attribute).try(:to_sym)
+          key = options[:as] || attribute
+          @key = key.respond_to?(:to_sym) ? key.to_sym : key
           @is_safe = options[:safe]
+          @default_value = options[:default]
           @for_merge = options[:merge]
           @attr_path_proc = options[:attr_path]
           @documentation = options[:documentation]
+          @override = options[:override]
           @conditions = conditions
         end
 
@@ -34,15 +39,14 @@ module Grape
             @conditions == other.conditions
         end
 
-        def setup
-        end
+        def setup; end
 
         def nesting?
           false
         end
 
         # if we have any nesting exposures with the same name.
-        def deep_complex_nesting?
+        def deep_complex_nesting?(entity) # rubocop:disable Lint/UnusedMethodArgument
           false
         end
 
@@ -51,7 +55,10 @@ module Grape
           if @is_safe
             is_delegatable
           else
-            is_delegatable || raise(NoMethodError, "#{entity.class.name} missing attribute `#{@attribute}' on #{entity.object}")
+            is_delegatable || raise(
+              NoMethodError,
+              "#{entity.class.name} missing attribute `#{@attribute}' on #{entity.object}"
+            )
           end
         end
 
@@ -76,7 +83,10 @@ module Grape
         end
 
         def valid_value(entity, options)
-          value(entity, options) if valid?(entity)
+          return unless valid?(entity)
+
+          output = value(entity, options)
+          output.blank? && @default_value.present? ? @default_value : output
         end
 
         def should_return_key?(options)
@@ -103,11 +113,17 @@ module Grape
           end
         end
 
-        def with_attr_path(entity, options)
+        def key(entity = nil)
+          @key.respond_to?(:call) ? entity.exec_with_object(@options, &@key) : @key
+        end
+
+        def with_attr_path(entity, options, &block)
           path_part = attr_path(entity, options)
-          options.with_attr_path(path_part) do
-            yield
-          end
+          options.with_attr_path(path_part, &block)
+        end
+
+        def override?
+          @override
         end
 
         protected

data/lib/grape_entity/exposure/block_exposure.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Grape
   class Entity
     module Exposure

data/lib/grape_entity/exposure/delegator_exposure.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Grape
   class Entity
     module Exposure

data/lib/grape_entity/exposure/formatter_block_exposure.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Grape
   class Entity
     module Exposure

data/lib/grape_entity/exposure/formatter_exposure.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Grape
   class Entity
     module Exposure

data/lib/grape_entity/exposure/nesting_exposure/nested_exposures.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Grape
   class Entity
     module Exposure
@@ -7,12 +9,17 @@ module Grape
 
           def initialize(exposures)
             @exposures = exposures
+            @deep_complex_nesting = nil
           end
 
           def find_by(attribute)
             @exposures.find { |e| e.attribute == attribute }
           end
 
+          def select_by(attribute)
+            @exposures.select { |e| e.attribute == attribute }
+          end
+
           def <<(exposure)
             reset_memoization!
             @exposures << exposure
@@ -29,31 +36,36 @@ module Grape
             @exposures.clear
           end
 
-          [
-            :each,
-            :to_ary, :to_a,
-            :all?,
-            :select,
-            :each_with_object,
-            :[],
-            :==,
-            :size,
-            :count,
-            :length,
-            :empty?
+          # rubocop:disable Style/DocumentDynamicEvalDefinition
+          %i[
+            each
+            to_ary to_a
+            all?
+            select
+            each_with_object
+            \[\]
+            ==
+            size
+            count
+            length
+            empty?
           ].each do |name|
-            class_eval <<-RUBY, __FILE__, __LINE__
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
               def #{name}(*args, &block)
                 @exposures.#{name}(*args, &block)
               end
             RUBY
           end
+          # rubocop:enable Style/DocumentDynamicEvalDefinition
 
           # Determine if we have any nesting exposures with the same name.
-          def deep_complex_nesting?
+          def deep_complex_nesting?(entity)
             if @deep_complex_nesting.nil?
               all_nesting = select(&:nesting?)
-              @deep_complex_nesting = all_nesting.group_by(&:key).any? { |_key, exposures| exposures.length > 1 }
+              @deep_complex_nesting =
+                all_nesting
+                .group_by { |exposure| exposure.key(entity) }
+                .any? { |_key, exposures| exposures.length > 1 }
             else
               @deep_complex_nesting
             end

data/lib/grape_entity/exposure/nesting_exposure/output_builder.rb

@@ -1,11 +1,16 @@
+# frozen_string_literal: true
+
 module Grape
   class Entity
     module Exposure
       class NestingExposure
         class OutputBuilder < SimpleDelegator
-          def initialize
+          def initialize(entity)
+            @entity = entity
             @output_hash = {}
             @output_collection = []
+
+            super
           end
 
           def add(exposure, result)
@@ -16,9 +21,10 @@ module Grape
               # If we have an array which should not be merged - save it with a key as a hash
               # If we have hash which should be merged - save it without a key (merge)
               return unless result
+
               @output_hash.merge! result, &merge_strategy(exposure.for_merge)
             else
-              @output_hash[exposure.key] = result
+              @output_hash[exposure.key(@entity)] = result
             end
           end
 

data/lib/grape_entity/exposure/nesting_exposure.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Grape
   class Entity
     module Exposure
@@ -29,45 +31,33 @@ module Grape
         end
 
         def value(entity, options)
-          new_options = nesting_options_for(options)
-          output = OutputBuilder.new
-
-          normalized_exposures(entity, new_options).each_with_object(output) do |exposure, out|
-            exposure.with_attr_path(entity, new_options) do
-              result = exposure.value(entity, new_options)
-              out.add(exposure, result)
-            end
+          map_entity_exposures(entity, options) do |exposure, nested_options|
+            exposure.value(entity, nested_options)
           end
         end
 
-        def valid_value_for(key, entity, options)
-          new_options = nesting_options_for(options)
-
-          result = nil
-          normalized_exposures(entity, new_options).select { |e| e.key == key }.each do |exposure|
-            exposure.with_attr_path(entity, new_options) do
-              result = exposure.valid_value(entity, new_options)
-            end
+        def serializable_value(entity, options)
+          map_entity_exposures(entity, options) do |exposure, nested_options|
+            exposure.serializable_value(entity, nested_options)
           end
-          result
         end
 
-        def serializable_value(entity, options)
+        def valid_value_for(key, entity, options)
           new_options = nesting_options_for(options)
-          output = OutputBuilder.new
 
-          normalized_exposures(entity, new_options).each_with_object(output) do |exposure, out|
+          key_exposures = normalized_exposures(entity, new_options).select { |e| e.key(entity) == key }
+
+          key_exposures.map do |exposure|
             exposure.with_attr_path(entity, new_options) do
-              result = exposure.serializable_value(entity, new_options)
-              out.add(exposure, result)
+              exposure.valid_value(entity, new_options)
             end
-          end
+          end.last
         end
 
         # if we have any nesting exposures with the same name.
-        # delegate :deep_complex_nesting?, to: :nested_exposures
-        def deep_complex_nesting?
-          nested_exposures.deep_complex_nesting?
+        # delegate :deep_complex_nesting?(entity), to: :nested_exposures
+        def deep_complex_nesting?(entity)
+          nested_exposures.deep_complex_nesting?(entity)
         end
 
         private
@@ -90,16 +80,18 @@ module Grape
 
         # This method 'merges' subsequent nesting exposures with the same name if it's needed
         def normalized_exposures(entity, options)
-          return easy_normalized_exposures(entity, options) unless deep_complex_nesting? # optimization
+          return easy_normalized_exposures(entity, options) unless deep_complex_nesting?(entity) # optimization
 
           table = nested_exposures.each_with_object({}) do |exposure, output|
             should_expose = exposure.with_attr_path(entity, options) do
               exposure.should_expose?(entity, options)
             end
             next unless should_expose
-            output[exposure.key] ||= []
-            output[exposure.key] << exposure
+
+            output[exposure.key(entity)] ||= []
+            output[exposure.key(entity)] << exposure
           end
+
           table.map do |key, exposures|
             last_exposure = exposures.last
 
@@ -111,13 +103,27 @@ module Grape
               end
               new_nested_exposures = nesting_tail.flat_map(&:nested_exposures)
               NestingExposure.new(key, {}, [], new_nested_exposures).tap do |new_exposure|
-                new_exposure.instance_variable_set(:@deep_complex_nesting, true) if nesting_tail.any?(&:deep_complex_nesting?)
+                if nesting_tail.any? { |exposure| exposure.deep_complex_nesting?(entity) }
+                  new_exposure.instance_variable_set(:@deep_complex_nesting, true)
+                end
               end
             else
               last_exposure
             end
           end
         end
+
+        def map_entity_exposures(entity, options)
+          new_options = nesting_options_for(options)
+          output = OutputBuilder.new(entity)
+
+          normalized_exposures(entity, new_options).each_with_object(output) do |exposure, out|
+            exposure.with_attr_path(entity, new_options) do
+              result = yield(exposure, new_options)
+              out.add(exposure, result)
+            end
+          end
+        end
       end
     end
   end

data/lib/grape_entity/exposure/represent_exposure.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Grape
   class Entity
     module Exposure
@@ -21,7 +23,7 @@ module Grape
         end
 
         def value(entity, options)
-          new_options = options.for_nesting(key)
+          new_options = options.for_nesting(key(entity))
           using_class.represent(@subexposure.value(entity, options), new_options)
         end