grape-entity 0.6.1 → 0.8.2

data/lib/grape_entity/deprecated.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Grape
+  class Entity
+    class Deprecated < StandardError
+      def initialize(msg, spec)
+        message = "DEPRECATED #{spec}: #{msg}"
+
+        super(message)
+      end
+    end
+  end
+end

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,25 @@ 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
+          when :to_sym, :sym, :symbol
+            :to_sym
+          else
+            :to_sym
+          end
+      end
+
+      def delegation_opts
+        @delegation_opts ||= { hash_access: hash_access }
+      end
     end
 
     @formatters = {}
@@ -119,12 +139,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(awesomness: '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 +188,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 +214,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 +285,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 +317,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
 
@@ -434,12 +481,11 @@ 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)
+
+      # Why not `arity > 1`? It might be negative https://ruby-doc.org/core-2.6.6/Method.html#method-i-arity
+      @delegator_accepts_opts = @delegator.method(:delegate).arity != 1
     end
 
     def root_exposures
@@ -474,7 +520,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.class, e.message
     end
 
     def exec_with_attribute(attribute, &block)
@@ -486,28 +541,52 @@ 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_opts
+        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
     ].to_set.freeze
 
     # Merges the given options with current block options.
@@ -517,7 +596,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)
@@ -543,7 +622,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.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'grape_entity/exposure/base'
 require 'grape_entity/exposure/represent_exposure'
 require 'grape_entity/exposure/block_exposure'
@@ -10,67 +12,88 @@ require 'grape_entity/condition'
 module Grape
   class Entity
     module Exposure
-      def self.new(attribute, options)
-        conditions = compile_conditions(options)
-        base_args = [attribute, options, conditions]
-
-        if options[:proc]
-          block_exposure = BlockExposure.new(*base_args, &options[:proc])
-        else
-          delegator_exposure = DelegatorExposure.new(*base_args)
-        end
+      class << self
+        def new(attribute, options)
+          conditions = compile_conditions(attribute, options)
+          base_args = [attribute, options, conditions]
 
-        if options[:using]
+          passed_proc = options[:proc]
           using_class = options[:using]
+          format_with = options[:format_with]
 
-          if options[:proc]
-            RepresentExposure.new(*base_args, using_class, block_exposure)
+          if using_class
+            build_class_exposure(base_args, using_class, passed_proc)
+          elsif passed_proc
+            build_block_exposure(base_args, passed_proc)
+          elsif format_with
+            build_formatter_exposure(base_args, format_with)
+          elsif options[:nesting]
+            build_nesting_exposure(base_args)
           else
-            RepresentExposure.new(*base_args, using_class, delegator_exposure)
+            build_delegator_exposure(base_args)
           end
+        end
 
-        elsif options[:proc]
-          block_exposure
+        private
 
-        elsif options[:format_with]
-          format_with = options[:format_with]
+        def compile_conditions(attribute, options)
+          if_conditions = [
+            options[:if_extras],
+            options[:if]
+          ].compact.flatten.map { |cond| Condition.new_if(cond) }
 
-          if format_with.is_a? Symbol
-            FormatterExposure.new(*base_args, format_with)
-          elsif format_with.respond_to? :call
-            FormatterBlockExposure.new(*base_args, &format_with)
-          end
+          unless_conditions = [
+            options[:unless_extras],
+            options[:unless]
+          ].compact.flatten.map { |cond| Condition.new_unless(cond) }
 
-        elsif options[:nesting]
-          NestingExposure.new(*base_args)
+          unless_conditions << expose_nil_condition(attribute, options) if options[:expose_nil] == false
 
-        else
-          delegator_exposure
+          if_conditions + unless_conditions
         end
-      end
 
-      def self.compile_conditions(options)
-        if_conditions = []
-        unless options[:if_extras].nil?
-          if_conditions.concat(options[:if_extras])
+        def expose_nil_condition(attribute, options)
+          Condition.new_unless(
+            proc do |object, _options|
+              if options[:proc].nil?
+                Delegator.new(object).delegate(attribute).nil?
+              else
+                exec_with_object(options, &options[:proc]).nil?
+              end
+            end
+          )
         end
-        if_conditions << options[:if] unless options[:if].nil?
 
-        if_conditions.map! do |cond|
-          Condition.new_if cond
+        def build_class_exposure(base_args, using_class, passed_proc)
+          exposure =
+            if passed_proc
+              build_block_exposure(base_args, passed_proc)
+            else
+              build_delegator_exposure(base_args)
+            end
+
+          RepresentExposure.new(*base_args, using_class, exposure)
+        end
+
+        def build_formatter_exposure(base_args, format_with)
+          if format_with.is_a? Symbol
+            FormatterExposure.new(*base_args, format_with)
+          elsif format_with.respond_to?(:call)
+            FormatterBlockExposure.new(*base_args, &format_with)
+          end
         end
 
-        unless_conditions = []
-        unless options[:unless_extras].nil?
-          unless_conditions.concat(options[:unless_extras])
+        def build_nesting_exposure(base_args)
+          NestingExposure.new(*base_args)
         end
-        unless_conditions << options[:unless] unless options[:unless].nil?
 
-        unless_conditions.map! do |cond|
-          Condition.new_unless cond
+        def build_block_exposure(base_args, passed_proc)
+          BlockExposure.new(*base_args, &passed_proc)
         end
 
-        if_conditions + unless_conditions
+        def build_delegator_exposure(base_args)
+          DelegatorExposure.new(*base_args)
+        end
       end
     end
   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,13 @@ 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]
           @for_merge = options[:merge]
           @attr_path_proc = options[:attr_path]
           @documentation = options[:documentation]
+          @override = options[:override]
           @conditions = conditions
         end
 
@@ -41,7 +45,7 @@ module Grape
         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
 
@@ -50,7 +54,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
 
@@ -102,11 +109,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