grape-entity 0.4.8 → 0.10.2

data/lib/grape_entity/entity.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'multi_json'
 require 'set'
 
@@ -99,37 +101,69 @@ module Grape
     end
 
     class << self
-      # Returns exposures that have been declared for this Entity or
-      # ancestors. The keys are symbolized references to methods on the
-      # containing object, the values are the options that were passed into expose.
-      # @return [Hash] of exposures
-      attr_accessor :exposures
-      attr_accessor :root_exposures
+      def root_exposure
+        @root_exposure ||= Exposure.new(nil, nesting: true)
+      end
+
+      attr_writer :root_exposure, :formatters
+
       # Returns all formatters that are registered for this and it's ancestors
       # @return [Hash] of formatters
-      attr_accessor :formatters
-      attr_accessor :nested_attribute_names
-      attr_accessor :nested_exposures
+      def formatters
+        @formatters ||= {}
+      end
+
+      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
 
-    @exposures = {}
-    @root_exposures = {}
-    @nested_exposures = {}
-    @nested_attribute_names = {}
     @formatters = {}
 
     def self.inherited(subclass)
-      subclass.exposures = exposures.dup
-      subclass.root_exposures = root_exposures.dup
-      subclass.nested_exposures = nested_exposures.dup
-      subclass.nested_attribute_names = nested_attribute_names.dup
+      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
@@ -151,48 +185,82 @@ module Grape
     #   block to the expose call to achieve the same effect.
     # @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
-        fail ArgumentError, 'You may not use the :as option on multi-attribute exposures.' if options[:as]
-        fail ArgumentError, 'You may not use block-setting on multi-attribute exposures.' if block_given?
-      end
-
-      fail ArgumentError, 'You may not use block-setting when also using format_with' if block_given? && options[:format_with].respond_to?(:call)
 
-      options[:proc] = block if block_given? && block.parameters.any?
+        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
 
-      @nested_attributes ||= []
+      if block_given?
+        if options[:format_with].respond_to?(:call)
+          raise ArgumentError, 'You may not use block-setting when also using format_with'
+        end
 
-      # rubocop:disable Style/Next
-      args.each do |attribute|
-        if @nested_attributes.empty?
-          root_exposures[attribute] = options
+        if block.parameters.any?
+          options[:proc] = block
         else
-          orig_attribute = attribute.to_sym
-          attribute = "#{@nested_attributes.last}__#{attribute}".to_sym
-          nested_attribute_names[attribute] = orig_attribute
-          options[:nested] = true
-          nested_exposures.deep_merge!(@nested_attributes.last.to_sym  => { attribute => options })
+          options[:nesting] = true
         end
+      end
 
-        exposures[attribute] = options
+      @documentation = nil
+      @nesting_stack ||= []
+      args.each { |attribute| build_exposure_for_attribute(attribute, @nesting_stack, options, block) }
+    end
+    # rubocop:enable Layout/LineLength
 
-        # Nested exposures are given in a block with no parameters.
-        if block_given? && block.parameters.empty?
-          @nested_attributes << attribute
-          block.call
-          @nested_attributes.pop
-        end
-      end
+    def self.build_exposure_for_attribute(attribute, nesting_stack, options, block)
+      exposure_list = nesting_stack.empty? ? root_exposures : nesting_stack.last.nested_exposures
+
+      exposure = Exposure.new(attribute, options)
+
+      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.
+    # @return [Array] of exposures
+    def self.root_exposures
+      root_exposure.nested_exposures
+    end
+
+    def self.find_exposure(attribute)
+      root_exposures.find_by(attribute)
+    end
+
+    def self.unexpose(*attributes)
+      cannot_unexpose! unless can_unexpose?
+      @documentation = nil
+      root_exposures.delete_by(*attributes)
+    end
+
+    def self.unexpose_all
+      cannot_unexpose! unless can_unexpose?
+      @documentation = nil
+      root_exposures.clear
+    end
+
+    def self.can_unexpose?
+      (@nesting_stack ||= []).empty?
     end
 
-    def self.unexpose(attribute)
-      root_exposures.delete(attribute)
-      exposures.delete(attribute)
-      nested_exposures.delete(attribute)
-      nested_attribute_names.delete(attribute)
+    def self.cannot_unexpose!
+      raise "You cannot call 'unexpose` inside of nesting exposure!"
     end
 
     # Set options that will be applied to any exposures declared inside the block.
@@ -214,10 +282,8 @@ module Grape
     # the values are document keys in the entity's documentation key. When calling
     # #docmentation, any exposure without a documentation key will be ignored.
     def self.documentation
-      @documentation ||= exposures.each_with_object({}) do |(attribute, exposure_options), memo|
-        if exposure_options[:documentation].present?
-          memo[key_for(attribute)] = exposure_options[:documentation]
-        end
+      @documentation ||= root_exposures.each_with_object({}) do |exposure, memo|
+        memo[exposure.key] = exposure.documentation if exposure.documentation && !exposure.documentation.empty?
       end
     end
 
@@ -248,7 +314,8 @@ module Grape
     #   end
     #
     def self.format_with(name, &block)
-      fail ArgumentError, 'You must pass a block for formatters' unless block_given?
+      raise ArgumentError, 'You must pass a block for formatters' unless block_given?
+
       formatters[name.to_sym] = block
     end
 
@@ -315,7 +382,7 @@ module Grape
     #
     #       class Users < Grape::Entity
     #         present_collection true
-    #         expose :items, as: 'users', using: API::Entities::Users
+    #         expose :items, as: 'users', using: API::Entities::User
     #         expose :version, documentation: { type: 'string',
     #                                           desc: 'actual api version',
     #                                           required: true }
@@ -370,9 +437,10 @@ 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 = {})
-      if objects.respond_to?(:to_ary) && ! @present_collection
-        root_element =  root_element(:collection_root)
-        inner = objects.to_ary.map { |object| new(object, { collection: true }.merge(options)).presented }
+      @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 }
       else
         objects = { @collection_name => objects } if @present_collection
         root_element = root_element(:root)
@@ -387,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
@@ -402,20 +471,26 @@ module Grape
       end
     end
 
-    def initialize(object, options = {})
-      @object = object
-      @delegator = Delegator.new object
-      @options = options
+    # Prevent default serialization of :options or :delegator.
+    def inspect
+      fields = serializable_hash.map { |k, v| "#{k}=#{v}" }
+      "#<#{self.class.name}:#{object_id} #{fields.join(' ')}>"
     end
 
-    def exposures
-      self.class.exposures
+    def initialize(object, options = {})
+      @object = object
+      @options = options.is_a?(Options) ? options : Options.new(options)
+      @delegator = Delegator.new(object)
     end
 
     def root_exposures
       self.class.root_exposures
     end
 
+    def root_exposure
+      self.class.root_exposure
+    end
+
     def documentation
       self.class.documentation
     end
@@ -436,222 +511,81 @@ module Grape
 
       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
-      end
-    end
-
-    def should_return_attribute?(attribute, options)
-      key = self.class.key_for(attribute)
-      only = only_fields(options).nil? ||
-             only_fields(options).include?(key)
-      except = except_fields(options) && except_fields(options).include?(key) &&
-               except_fields(options)[key] == true
-      only && !except
+      root_exposure.serializable_value(self, opts)
     end
 
-    def only_fields(options, for_attribute = nil)
-      return nil unless options[:only]
-
-      @only_fields ||= options[:only].each_with_object({}) do |attribute, allowed_fields|
-        if attribute.is_a?(Hash)
-          attribute.each do |attr, nested_attrs|
-            allowed_fields[attr] ||= []
-            allowed_fields[attr] += nested_attrs
-          end
-        else
-          allowed_fields[attribute] = true
-        end
-      end.symbolize_keys
-
-      if for_attribute && @only_fields[for_attribute].is_a?(Array)
-        @only_fields[for_attribute]
-      elsif for_attribute.nil?
-        @only_fields
+    def exec_with_object(options, &block)
+      if block.parameters.count == 1
+        instance_exec(object, &block)
+      else
+        instance_exec(object, options, &block)
       end
-    end
-
-    def except_fields(options, for_attribute = nil)
-      return nil unless options[:except]
-
-      @except_fields ||= options[:except].each_with_object({}) do |attribute, allowed_fields|
-        if attribute.is_a?(Hash)
-          attribute.each do |attr, nested_attrs|
-            allowed_fields[attr] ||= []
-            allowed_fields[attr] += nested_attrs
-          end
-        else
-          allowed_fields[attribute] = true
-        end
-      end.symbolize_keys
-
-      if for_attribute && @except_fields[for_attribute].is_a?(Array)
-        @except_fields[for_attribute]
-      elsif for_attribute.nil?
-        @except_fields
+    rescue StandardError => e
+      # it handles: https://github.com/ruby/ruby/blob/v3_0_0_preview1/NEWS.md#language-changes point 3, Proc
+      # accounting for expose :foo, &:bar
+      if e.is_a?(ArgumentError) && block.parameters == [[:req], [:rest]]
+        raise Grape::Entity::Deprecated.new e.message, 'in ruby 3.0'
       end
-    end
 
-    alias_method :as_json, :serializable_hash
-
-    def to_json(options = {})
-      options = options.to_h if options && 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)
-      serializable_hash(options).to_xml(options)
-    end
-
-    protected
-
-    def self.name_for(attribute)
-      attribute = attribute.to_sym
-      nested_attribute_names[attribute] || attribute
+      raise e
     end
 
-    def self.key_for(attribute)
-      exposures[attribute.to_sym][:as] || name_for(attribute)
-    end
-
-    def self.nested_exposures_for?(attribute)
-      nested_exposures.key?(attribute)
-    end
-
-    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)]
-          end
-        end
-
-      Hash[nested_attributes.compact]
+    def exec_with_attribute(attribute, &block)
+      instance_exec(delegate_attribute(attribute), &block)
     end
 
-    def value_for(attribute, options = {})
-      exposure_options = exposures[attribute.to_sym]
-      return unless valid_exposure?(attribute, exposure_options)
-
-      if exposure_options[:using]
-        exposure_options[:using] = exposure_options[:using].constantize if exposure_options[:using].respond_to? :constantize
-
-        using_options = options_for_using(attribute, options)
-
-        if exposure_options[:proc]
-          exposure_options[:using].represent(instance_exec(object, options, &exposure_options[:proc]), using_options)
-        else
-          exposure_options[:using].represent(delegate_attribute(attribute), using_options)
-        end
-
-      elsif exposure_options[:proc]
-        instance_exec(object, options, &exposure_options[:proc])
-
-      elsif exposure_options[:format_with]
-        format_with = exposure_options[:format_with]
-
-        if format_with.is_a?(Symbol) && formatters[format_with]
-          instance_exec(delegate_attribute(attribute), &formatters[format_with])
-        elsif format_with.is_a?(Symbol)
-          send(format_with, delegate_attribute(attribute))
-        elsif format_with.respond_to? :call
-          instance_exec(delegate_attribute(attribute), &format_with)
-        end
-
-      elsif self.class.nested_exposures_for?(attribute)
-        nested_value_for(attribute, options)
-      else
-        delegate_attribute(attribute)
-      end
+    def value_for(key, options = Options.new)
+      root_exposure.valid_value_for(key, self, options)
     end
 
     def delegate_attribute(attribute)
-      name = self.class.name_for(attribute)
-      if respond_to?(name, true)
-        send(name)
+      if is_defined_in_entity?(attribute)
+        send(attribute)
+      elsif delegator.accepts_options?
+        delegator.delegate(attribute, **self.class.delegation_opts)
       else
-        delegator.delegate(name)
+        delegator.delegate(attribute)
       end
     end
 
-    def valid_exposure?(attribute, exposure_options)
-      if self.class.nested_exposures_for?(attribute)
-        self.class.nested_exposures[attribute].all? { |a, o| valid_exposure?(a, o) }
-      elsif exposure_options.key?(:proc)
-        true
-      else
-        name = self.class.name_for(attribute)
-        is_delegatable = delegator.delegatable?(name) || respond_to?(name, true)
-        if exposure_options[:safe]
-          is_delegatable
-        else
-          is_delegatable || fail(NoMethodError, "#{self.class.name} missing attribute `#{name}' on #{object}")
-        end
-      end
-    end
-
-    def conditions_met?(exposure_options, options)
-      if_conditions = []
-      unless exposure_options[:if_extras].nil?
-        if_conditions.concat(exposure_options[:if_extras])
-      end
-      if_conditions << exposure_options[:if] unless exposure_options[:if].nil?
+    def is_defined_in_entity?(attribute)
+      return false unless respond_to?(attribute, true)
 
-      if_conditions.each do |if_condition|
-        case if_condition
-        when Hash then if_condition.each_pair { |k, v| return false if options[k.to_sym] != v }
-        when Proc then return false unless instance_exec(object, options, &if_condition)
-        when Symbol then return false unless options[if_condition]
-        end
-      end
+      ancestors = self.class.ancestors
+      ancestors.index(Grape::Entity) > ancestors.index(method(attribute).owner)
+    end
 
-      unless_conditions = []
-      unless exposure_options[:unless_extras].nil?
-        unless_conditions.concat(exposure_options[:unless_extras])
-      end
-      unless_conditions << exposure_options[:unless] unless exposure_options[:unless].nil?
+    alias as_json serializable_hash
 
-      unless_conditions.each do |unless_condition|
-        case unless_condition
-        when Hash then unless_condition.each_pair { |k, v| return false if options[k.to_sym] == v }
-        when Proc then return false if instance_exec(object, options, &unless_condition)
-        when Symbol then return false if options[unless_condition]
-        end
-      end
-
-      true
+    def to_json(options = {})
+      options = options.to_h if options&.respond_to?(:to_h)
+      MultiJson.dump(serializable_hash(options))
     end
 
-    def options_for_using(attribute, options)
-      using_options = options.dup
-      using_options.delete(:collection)
-      using_options[:root] = nil
-      using_options[:only] = only_fields(using_options, attribute)
-      using_options[:except] = except_fields(using_options, attribute)
-
-      using_options
+    def to_xml(options = {})
+      options = options.to_h if options&.respond_to?(:to_h)
+      serializable_hash(options).to_xml(options)
     end
 
     # All supported options.
-    OPTIONS = [
-      :as, :if, :unless, :using, :with, :proc, :documentation, :format_with, :safe, :if_extras, :unless_extras
+    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.
@@ -661,7 +595,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)
@@ -687,8 +621,8 @@ module Grape
     #
     # @param options [Hash] Exposure options.
     def self.valid_options(options)
-      options.keys.each do |key|
-        fail ArgumentError, "#{key.inspect} is not a valid option." unless OPTIONS.include?(key)
+      options.each_key do |key|
+        raise ArgumentError, "#{key.inspect} is not a valid option." unless OPTIONS.include?(key)
       end
 
       options[:using] = options.delete(:with) if options.key?(:with)