grape-entity 0.6.1 → 0.8.2

data/README.md

@@ -2,7 +2,7 @@
 
 [![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)
-[![Dependency Status](https://gemnasium.com/ruby-grape/grape-entity.svg)](https://gemnasium.com/ruby-grape/grape-entity)
+[![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)
 [![Code Climate](https://codeclimate.com/github/ruby-grape/grape-entity.svg)](https://codeclimate.com/github/ruby-grape/grape-entity)
 
 ## Introduction
@@ -220,7 +220,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
@@ -229,7 +230,7 @@ class ExampleEntity < Grape::Entity
   private
 
   def formatted_value
-    "+ X #{object.value}"
+    "+ X #{object.value} #{options[:y]}"
   end
 end
 ```
@@ -255,6 +256,22 @@ class MailingAddress < UserData
 end
 ```
 
+#### Overriding exposures
+
+If you want to add one more exposure for the field but don't want the first one to be fired (for instance, when using inheritance), you can use the `override` flag. For instance:
+
+```ruby
+class User < Grape::Entity
+  expose :name
+end
+
+class Employee < User
+  expose :name, as: :employee_name, override: true
+end
+```
+
+`User` will return something like this `{ "name" : "John" }` while `Employee` will present the same data as `{ "employee_name" : "John" }` instead of `{ "name" : "John", "employee_name" : "John" }`.
+
 #### Returning only the fields you want
 
 After exposing the desired attributes, you can choose which one you need when representing some object or collection by using the only: and except: options. See the example:
@@ -320,7 +337,7 @@ module Entities
     with_options(format_with: :iso_timestamp) do
       expose :created_at
       expose :updated_at
-    end    
+    end
   end
 end
 ```
@@ -349,6 +366,86 @@ module Entities
 end
 ```
 
+#### Expose Nil
+
+By default, exposures that contain `nil` values will be represented in the resulting JSON as `null`.
+
+As an example, a hash with the following values:
+
+```ruby
+{
+  name: nil,
+  age: 100
+}
+```
+
+will result in a JSON object that looks like:
+
+```javascript
+{
+  "name": null,
+  "age": 100
+}
+```
+
+There are also times when, rather than displaying an attribute with a `null` value, it is more desirable to not display the attribute at all. Using the hash from above the desired JSON would look like:
+
+```javascript
+{
+  "age": 100
+}
+```
+
+In order to turn on this behavior for an as-exposure basis, the option `expose_nil` can be used. By default, `expose_nil` is considered to be `true`, meaning that `nil` values will be represented in JSON as `null`. If `false` is provided, then attributes with `nil` values will be omitted from the resulting JSON completely.
+
+```ruby
+module  Entities
+  class MyModel < Grape::Entity
+    expose :name, expose_nil: false
+    expose :age, expose_nil: false
+  end
+end
+```
+
+`expose_nil` is per exposure, so you can suppress exposures from resulting in `null` or express `null` values on a per exposure basis as you need:
+
+```ruby
+module  Entities
+  class MyModel < Grape::Entity
+    expose :name, expose_nil: false
+    expose :age # since expose_nil is omitted nil values will be rendered as null
+  end
+end
+```
+
+It is also possible to use `expose_nil` with `with_options` if you want to add the configuration to multiple exposures at once.
+
+```ruby
+module  Entities
+  class MyModel < Grape::Entity
+    # None of the exposures in the with_options block will render nil values as null
+    with_options(expose_nil: false) do
+      expose :name
+      expose :age
+    end
+  end
+end
+```
+
+When using `with_options`, it is possible to again override which exposures will render `nil` as `null` by adding the option on a specific exposure.
+
+```ruby
+module  Entities
+  class MyModel < Grape::Entity
+    # None of the exposures in the with_options block will render nil values as null
+    with_options(expose_nil: false) do
+      expose :name
+      expose :age, expose_nil: true # nil values would be rendered as null in the JSON
+    end
+  end
+end
+```
+
 #### Documentation
 
 Expose documentation with the field. Gets bubbled up when used with Grape and various API documentation systems.

data/Rakefile

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 require 'rubygems'
 require 'bundler'
@@ -17,4 +17,4 @@ RSpec::Core::RakeTask.new(:spec)
 require 'rubocop/rake_task'
 RuboCop::RakeTask.new(:rubocop)
 
-task default: [:spec, :rubocop]
+task default: %i[spec rubocop]

data/UPGRADING.md

@@ -1,5 +1,34 @@
-Upgrading Grape Entity
-===============
+# Upgrading Grape Entity
+
+### Upgrading to >= 0.8.2
+
+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.8.2
+
+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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 require 'grape-entity'
 require 'benchmark'
@@ -5,6 +7,7 @@ require 'benchmark'
 module Models
   class School
     attr_reader :classrooms
+
     def initialize
       @classrooms = []
     end
@@ -13,6 +16,7 @@ module Models
   class ClassRoom
     attr_reader :students
     attr_accessor :teacher
+
     def initialize(opts = {})
       @teacher = opts[:teacher]
       @students = []
@@ -21,6 +25,7 @@ module Models
 
   class Person
     attr_accessor :name
+
     def initialize(opts = {})
       @name = opts[:name]
     end
@@ -28,6 +33,7 @@ module Models
 
   class Teacher < Models::Person
     attr_accessor :tenure
+
     def initialize(opts = {})
       super(opts)
       @tenure = opts[:tenure]
@@ -36,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,4 +1,6 @@
-$LOAD_PATH.push File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+$LOAD_PATH.push File.expand_path('lib', __dir__)
 require 'grape_entity/version'
 
 Gem::Specification.new do |s|
@@ -12,22 +14,20 @@ 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.2.6'
-
-  s.rubyforge_project = 'grape-entity'
+  s.required_ruby_version = '>= 2.4'
 
+  s.add_runtime_dependency 'activesupport', '>= 3.0.0'
+  # FIXME: remove dependecy
   s.add_runtime_dependency 'multi_json', '>= 1.3.2'
-  s.add_runtime_dependency 'activesupport', '>= 5.0.0'
 
   s.add_development_dependency 'bundler'
-  s.add_development_dependency 'rake'
-  s.add_development_dependency 'rubocop', '~> 0.40'
-  s.add_development_dependency 'rspec', '~> 3.0'
-  s.add_development_dependency 'rack-test'
   s.add_development_dependency 'maruku'
-  s.add_development_dependency 'yard'
   s.add_development_dependency 'pry' unless RUBY_PLATFORM.eql?('java') || RUBY_ENGINE.eql?('rbx')
   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.9'
+  s.add_development_dependency 'yard'
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec}/*`.split("\n")

data/lib/grape-entity.rb

@@ -1 +1,3 @@
+# frozen_string_literal: true
+
 require 'grape_entity'

data/lib/grape_entity.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'active_support/version'
 require 'active_support/core_ext/string/inflections'
 require 'active_support/core_ext/hash/reverse_merge'
@@ -7,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.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'grape_entity/condition/base'
 require 'grape_entity/condition/block_condition'
 require 'grape_entity/condition/hash_condition'
@@ -6,19 +8,26 @@ require 'grape_entity/condition/symbol_condition'
 module Grape
   class Entity
     module Condition
-      def self.new_if(arg)
-        case arg
-        when Hash then HashCondition.new false, arg
-        when Proc then BlockCondition.new false, &arg
-        when Symbol then SymbolCondition.new false, arg
+      class << self
+        def new_if(arg)
+          condition(false, arg)
         end
-      end
 
-      def self.new_unless(arg)
-        case arg
-        when Hash then HashCondition.new true, arg
-        when Proc then BlockCondition.new true, &arg
-        when Symbol then SymbolCondition.new true, arg
+        def new_unless(arg)
+          condition(true, arg)
+        end
+
+        private
+
+        def condition(inverse, arg)
+          condition_klass =
+            case arg
+            when Hash then HashCondition
+            when Proc then BlockCondition
+            when Symbol then SymbolCondition
+            end
+
+          condition_klass.new(inverse, arg)
         end
       end
     end

data/lib/grape_entity/condition/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Grape
   class Entity
     module Condition
@@ -19,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/condition/block_condition.rb

@@ -1,10 +1,12 @@
+# frozen_string_literal: true
+
 module Grape
   class Entity
     module Condition
       class BlockCondition < Base
         attr_reader :block
 
-        def setup(&block)
+        def setup(block)
           @block = block
         end
 

data/lib/grape_entity/condition/hash_condition.rb

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

data/lib/grape_entity/condition/symbol_condition.rb

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

data/lib/grape_entity/delegator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'grape_entity/delegator/base'
 require 'grape_entity/delegator/hash_object'
 require 'grape_entity/delegator/openstruct_object'
@@ -8,15 +10,14 @@ module Grape
   class Entity
     module Delegator
       def self.new(object)
-        if object.is_a?(Hash)
-          HashObject.new object
-        elsif defined?(OpenStruct) && object.is_a?(OpenStruct)
-          OpenStructObject.new object
-        elsif object.respond_to? :fetch, true
-          FetchableObject.new object
-        else
-          PlainObject.new object
-        end
+        delegator_klass =
+          if object.is_a?(Hash) then HashObject
+          elsif defined?(OpenStruct) && object.is_a?(OpenStruct) then OpenStructObject
+          elsif object.respond_to?(:fetch, true) then FetchableObject
+          else PlainObject
+          end
+
+        delegator_klass.new(object)
       end
     end
   end

data/lib/grape_entity/delegator/base.rb

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

data/lib/grape_entity/delegator/fetchable_object.rb

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

data/lib/grape_entity/delegator/hash_object.rb

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
+
 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/delegator/openstruct_object.rb

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

data/lib/grape_entity/delegator/plain_object.rb

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