grape-entity 0.7.1 → 0.9.0

data/Guardfile

@@ -1,11 +1,13 @@
+# frozen_string_literal: true
+
 # A sample Guardfile
 # More info at https://github.com/guard/guard#readme
 
 guard 'rspec', version: 2 do
   watch(%r{^spec/.+_spec\.rb$})
-  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^lib/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
   watch(%r{^spec/support/shared_versioning_examples.rb$}) { |_m| 'spec/' }
-  watch('spec/spec_helper.rb')  { 'spec/' }
+  watch('spec/spec_helper.rb') { 'spec/' }
 end
 
 guard 'bundler' do

data/README.md

@@ -1,11 +1,46 @@
-# Grape::Entity
-
 [![Gem Version](http://img.shields.io/gem/v/grape-entity.svg)](http://badge.fury.io/rb/grape-entity)
-[![Build Status](http://img.shields.io/travis/ruby-grape/grape-entity.svg)](https://travis-ci.org/ruby-grape/grape-entity)
+![Ruby](https://github.com/ruby-grape/grape-entity/workflows/Ruby/badge.svg)
 [![Coverage Status](https://coveralls.io/repos/github/ruby-grape/grape-entity/badge.svg?branch=master)](https://coveralls.io/github/ruby-grape/grape-entity?branch=master)
-[![Dependency Status](https://gemnasium.com/ruby-grape/grape-entity.svg)](https://gemnasium.com/ruby-grape/grape-entity)
 [![Code Climate](https://codeclimate.com/github/ruby-grape/grape-entity.svg)](https://codeclimate.com/github/ruby-grape/grape-entity)
 
+# Table of Contents
+
+- [Grape::Entity](#grapeentity)
+  - [Introduction](#introduction)
+    - [Example](#example)
+  - [Reusable Responses with Entities](#reusable-responses-with-entities)
+    - [Defining Entities](#defining-entities)
+      - [Basic Exposure](#basic-exposure)
+      - [Exposing with a Presenter](#exposing-with-a-presenter)
+      - [Conditional Exposure](#conditional-exposure)
+      - [Safe Exposure](#safe-exposure)
+      - [Nested Exposure](#nested-exposure)
+      - [Collection Exposure](#collection-exposure)
+      - [Merge Fields](#merge-fields)
+      - [Runtime Exposure](#runtime-exposure)
+      - [Unexpose](#unexpose)
+      - [Overriding exposures](#overriding-exposures)
+      - [Returning only the fields you want](#returning-only-the-fields-you-want)
+      - [Aliases](#aliases)
+      - [Format Before Exposing](#format-before-exposing)
+      - [Expose Nil](#expose-nil)
+      - [Documentation](#documentation)
+    - [Options Hash](#options-hash)
+      - [Passing Additional Option To Nested Exposure](#passing-additional-option-to-nested-exposure)
+      - [Attribute Path Tracking](#attribute-path-tracking)
+    - [Using the Exposure DSL](#using-the-exposure-dsl)
+    - [Using Entities](#using-entities)
+    - [Entity Organization](#entity-organization)
+    - [Caveats](#caveats)
+  - [Installation](#installation)
+  - [Testing with Entities](#testing-with-entities)
+  - [Project Resources](#project-resources)
+  - [Contributing](#contributing)
+  - [License](#license)
+  - [Copyright](#copyright)
+
+# Grape::Entity
+
 ## Introduction
 
 This gem adds Entity support to API frameworks, such as [Grape](https://github.com/ruby-grape/grape). Grape's Entity is an API focused facade that sits on top of an object model.
@@ -221,7 +256,8 @@ class ExampleEntity < Grape::Entity
 end
 ```
 
-You have always access to the presented instance with `object`
+You always have access to the presented instance (`object`) and the top-level
+entity options (`options`).
 
 ```ruby
 class ExampleEntity < Grape::Entity
@@ -230,7 +266,7 @@ class ExampleEntity < Grape::Entity
   private
 
   def formatted_value
-    "+ X #{object.value}"
+    "+ X #{object.value} #{options[:y]}"
   end
 end
 ```
@@ -265,7 +301,7 @@ class User < Grape::Entity
   expose :name
 end
 
-class Employee < UserData
+class Employee < User
   expose :name, as: :employee_name, override: true
 end
 ```

data/UPGRADING.md

@@ -1,5 +1,22 @@
-Upgrading Grape Entity
-===============
+# Upgrading Grape Entity
+
+
+### Upgrading to >= 0.8.2
+
+Official support for ruby < 2.5 removed, ruby 2.5 only in testing mode, but no support.
+
+In Ruby 3.0: the block handling will be changed
+[language-changes point 3, Proc](https://github.com/ruby/ruby/blob/v3_0_0_preview1/NEWS.md#language-changes).
+This:
+```ruby
+expose :that_method_without_args, &:method_without_args
+```
+will be deprecated.
+
+Prefer to use this pattern for simple setting a value
+```ruby
+expose :method_without_args, as: :that_method_without_args
+```
 
 ### Upgrading to >= 0.6.0
 

data/bench/serializing.rb

@@ -7,6 +7,7 @@ require 'benchmark'
 module Models
   class School
     attr_reader :classrooms
+
     def initialize
       @classrooms = []
     end
@@ -15,6 +16,7 @@ module Models
   class ClassRoom
     attr_reader :students
     attr_accessor :teacher
+
     def initialize(opts = {})
       @teacher = opts[:teacher]
       @students = []
@@ -23,6 +25,7 @@ module Models
 
   class Person
     attr_accessor :name
+
     def initialize(opts = {})
       @name = opts[:name]
     end
@@ -30,6 +33,7 @@ module Models
 
   class Teacher < Models::Person
     attr_accessor :tenure
+
     def initialize(opts = {})
       super(opts)
       @tenure = opts[:tenure]
@@ -38,6 +42,7 @@ module Models
 
   class Student < Models::Person
     attr_reader :grade
+
     def initialize(opts = {})
       super(opts)
       @grade = opts[:grade]

data/grape-entity.gemspec

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-$LOAD_PATH.push File.expand_path('../lib', __FILE__)
+$LOAD_PATH.push File.expand_path('lib', __dir__)
 require 'grape_entity/version'
 
 Gem::Specification.new do |s|
@@ -14,11 +14,9 @@ Gem::Specification.new do |s|
   s.description = 'Extracted from Grape, A Ruby framework for rapid API development with great conventions.'
   s.license     = 'MIT'
 
-  s.required_ruby_version = '>= 2.3'
+  s.required_ruby_version = '>= 2.5'
 
-  s.rubyforge_project = 'grape-entity'
-
-  s.add_runtime_dependency 'activesupport', '>=4.0'
+  s.add_runtime_dependency 'activesupport', '>= 3.0.0'
   # FIXME: remove dependecy
   s.add_runtime_dependency 'multi_json', '>= 1.3.2'
 
@@ -28,7 +26,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'pry-byebug' unless RUBY_PLATFORM.eql?('java') || RUBY_ENGINE.eql?('rbx')
   s.add_development_dependency 'rack-test'
   s.add_development_dependency 'rake'
-  s.add_development_dependency 'rspec', '~> 3.0'
+  s.add_development_dependency 'rspec', '~> 3.9'
   s.add_development_dependency 'yard'
 
   s.files         = `git ls-files`.split("\n")

data/lib/grape_entity.rb

@@ -9,3 +9,4 @@ require 'grape_entity/entity'
 require 'grape_entity/delegator'
 require 'grape_entity/exposure'
 require 'grape_entity/options'
+require 'grape_entity/deprecated'

data/lib/grape_entity/condition/base.rb

@@ -21,7 +21,7 @@ module Grape
         end
 
         def met?(entity, options)
-          !@inverse ? if_value(entity, options) : unless_value(entity, options)
+          @inverse ? unless_value(entity, options) : if_value(entity, options)
         end
 
         def if_value(_entity, _options)

data/lib/grape_entity/delegator/hash_object.rb

@@ -4,8 +4,8 @@ module Grape
   class Entity
     module Delegator
       class HashObject < Base
-        def delegate(attribute)
-          object[attribute]
+        def delegate(attribute, hash_access: :to_sym)
+          object[attribute.send(hash_access)]
         end
       end
     end

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

@@ -105,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
@@ -113,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 = {}
@@ -121,6 +137,8 @@ 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
@@ -168,18 +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
@@ -191,6 +214,7 @@ module Grape
       @nesting_stack ||= []
       args.each { |attribute| build_exposure_for_attribute(attribute, @nesting_stack, options, block) }
     end
+    # rubocop:enable Layout/LineLength
 
     def self.build_exposure_for_attribute(attribute, nesting_stack, options, block)
       exposure_list = nesting_stack.empty? ? root_exposures : nesting_stack.last.nested_exposures
@@ -291,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
 
@@ -454,8 +479,11 @@ module Grape
 
     def initialize(object, options = {})
       @object = object
-      @delegator = Delegator.new(object)
       @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
@@ -495,6 +523,11 @@ module Grape
       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)
@@ -506,28 +539,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 = %i[
-      rewrite as if unless using with proc documentation format_with safe attr_path if_extras unless_extras merge expose_nil override
+      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.

data/lib/grape_entity/exposure.rb

@@ -47,14 +47,20 @@ module Grape
             options[:unless]
           ].compact.flatten.map { |cond| Condition.new_unless(cond) }
 
-          unless_conditions << expose_nil_condition(attribute) if options[:expose_nil] == false
+          unless_conditions << expose_nil_condition(attribute, options) if options[:expose_nil] == false
 
           if_conditions + unless_conditions
         end
 
-        def expose_nil_condition(attribute)
+        def expose_nil_condition(attribute, options)
           Condition.new_unless(
-            proc { |object, _options| Delegator.new(object).delegate(attribute).nil? }
+            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
 

data/lib/grape_entity/exposure/base.rb

@@ -54,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
 
@@ -110,11 +113,9 @@ module Grape
           @key.respond_to?(:call) ? entity.exec_with_object(@options, &@key) : @key
         end
 
-        def with_attr_path(entity, options)
+        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?