grape-entity 0.3.0 → 0.4.0

data/Rakefile

@@ -15,37 +15,7 @@ RSpec::Core::RakeTask.new(:rcov) do |spec|
 end
 
 task :spec
-task :default => :spec
+require 'rubocop/rake_task'
+Rubocop::RakeTask.new(:rubocop)
 
-#
-# TODO: setup a place for documentation and then get this going again.
-#
-# begin
-#   require 'yard'
-#   DOC_FILES = ['lib/**/*.rb', 'README.markdown']
-#   
-#   YARD::Rake::YardocTask.new(:doc) do |t|
-#     t.files   = DOC_FILES
-#   end
-#   
-#   namespace :doc do
-#     YARD::Rake::YardocTask.new(:pages) do |t|
-#       t.files   = DOC_FILES
-#       t.options = ['-o', '../grape.doc']
-#     end
-#     
-#     namespace :pages do
-#       desc 'Generate and publish YARD docs to GitHub pages.'
-#       task :publish => ['doc:pages'] do
-#         Dir.chdir(File.dirname(__FILE__) + '/../grape.doc') do
-#           system("git add .")
-#           system("git add -u")
-#           system("git commit -m 'Generating docs for version #{version}.'")
-#           system("git push origin gh-pages")
-#         end
-#       end
-#     end
-#   end
-# rescue LoadError
-#   puts "You need to install YARD."
-# end
+task default: [:rubocop, :spec]

data/lib/grape-entity.rb

@@ -1 +1 @@
-require 'grape_entity'
+require 'grape_entity'

data/lib/grape_entity.rb

@@ -1,6 +1,3 @@
+require "active_support/core_ext"
 require "grape_entity/version"
-
-module Grape
-  autoload :Entity, 'grape_entity/entity'
-end
-
+require "grape_entity/entity"

data/lib/grape_entity/entity.rb

@@ -12,11 +12,11 @@ module Grape
   #     module Entities
   #       class User < Grape::Entity
   #         expose :first_name, :last_name, :screen_name, :location
-  #         expose :field, :documentation => {:type => "string", :desc => "describe the field"}
-  #         expose :latest_status, :using => API::Status, :as => :status, :unless => {:collection => true}
-  #         expose :email, :if => {:type => :full}
-  #         expose :new_attribute, :if => {:version => 'v2'}
-  #         expose(:name){|model,options| [model.first_name, model.last_name].join(' ')}
+  #         expose :field, documentation: { type: "string", desc: "describe the field" }
+  #         expose :latest_status, using: API::Status, as: :status, unless: { collection: true }
+  #         expose :email, if: { type: :full }
+  #         expose :new_attribute, if: { version: 'v2' }
+  #         expose(:name) { |model, options| [model.first_name, model.last_name].join(' ') }
   #       end
   #     end
   #   end
@@ -32,11 +32,11 @@ module Grape
   #     class Users < Grape::API
   #       version 'v2'
   #
-  #       desc 'User index', { :object_fields => API::Entities::User.documentation }
+  #       desc 'User index', { params: API::Entities::User.documentation }
   #       get '/users' do
   #         @users = User.all
   #         type = current_user.admin? ? :full : :default
-  #         present @users, :with => API::Entities::User, :type => type
+  #         present @users, with: API::Entities::User, type: type
   #       end
   #     end
   #   end
@@ -48,16 +48,16 @@ module Grape
     module DSL
       def self.included(base)
         base.extend ClassMethods
-        ancestor_entity_class = base.ancestors.detect{|a| a.entity_class if a.respond_to?(:entity_class)}
+        ancestor_entity_class = base.ancestors.detect { |a| a.entity_class if a.respond_to?(:entity_class) }
         base.const_set(:Entity, Class.new(ancestor_entity_class || Grape::Entity)) unless const_defined?(:Entity)
       end
 
       module ClassMethods
         # Returns the automatically-created entity class for this
         # Class.
-        def entity_class(search_ancestors=true)
+        def entity_class(search_ancestors = true)
           klass = const_get(:Entity) if const_defined?(:Entity)
-          klass ||= ancestors.detect{|a| a.entity_class(false) if a.respond_to?(:entity_class) } if search_ancestors
+          klass ||= ancestors.detect { |a| a.entity_class(false) if a.respond_to?(:entity_class) } if search_ancestors
           klass
         end
 
@@ -70,7 +70,7 @@ module Grape
         #
         #   class User
         #     include Grape::Entity::DSL
-        #     
+        #
         #     entity :name, :email
         #   end
         #
@@ -78,14 +78,14 @@ module Grape
         #
         #   class User
         #     include Grape::Entity::DSL
-        #     
+        #
         #     entity :name, :email do
         #       expose :latest_status, using: Status::Entity, if: :include_status
-        #       expose :new_attribute, :if => {:version => 'v2'}
+        #       expose :new_attribute, if: { version: 'v2' }
         #     end
         #   end
         def entity(*exposures, &block)
-          entity_class.expose *exposures if exposures.any?
+          entity_class.expose(*exposures) if exposures.any?
           entity_class.class_eval(&block) if block_given?
           entity_class
         end
@@ -123,8 +123,7 @@ module Grape
     # @option options :documentation Define documenation for an exposed
     #   field, typically the value is a hash with two fields, type and desc.
     def self.expose(*args, &block)
-      options = args.last.is_a?(Hash) ? args.pop : {}
-      options = (@block_options ||= []).inject({}){|final, step| final.merge!(step)}.merge(options)
+      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]
@@ -133,24 +132,36 @@ module Grape
 
       raise 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?
+      options[:proc] = block if block_given? && block.parameters.any?
 
+      @nested_attributes ||= []
       args.each do |attribute|
+        unless @nested_attributes.empty?
+          attribute = "#{@nested_attributes.last}__#{attribute}"
+        end
+
         exposures[attribute.to_sym] = options
+
+        # 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
     end
 
     # Set options that will be applied to any exposures declared inside the block.
     #
     # @example Multi-exposure if
-    # 
+    #
     #   class MyEntity < Grape::Entity
-    #     with_options :if => {:awesome => true} do
+    #     with_options if: { awesome: true } do
     #       expose :awesome, :sweet
     #     end
     #   end
     def self.with_options(options)
-      (@block_options ||= []).push(options)
+      (@block_options ||= []).push(valid_options(options))
       yield
       @block_options.pop
     end
@@ -172,12 +183,12 @@ 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.inject({}) do |memo, value|
-                           unless value[1][:documentation].nil? || value[1][:documentation].empty?
-                             memo[value[0]] = value[1][:documentation]
-                           end
-                           memo
-                         end
+      @documentation ||= exposures.inject({}) do |memo, (attribute, exposure_options)|
+        unless exposure_options[:documentation].nil? || exposure_options[:documentation].empty?
+          memo[key_for(attribute)] = exposure_options[:documentation]
+        end
+        memo
+      end
 
       if superclass.respond_to? :documentation
         @documentation = superclass.documentation.merge(@documentation)
@@ -192,8 +203,6 @@ module Grape
     # @param name [Symbol] the name of the formatter
     # @param block [Proc] the block that will interpret the exposed attribute
     #
-    #
-    #
     # @example Formatter declaration
     #
     #   module API
@@ -203,7 +212,7 @@ module Grape
     #           date.strftime('%m/%d/%Y')
     #         end
     #
-    #         expose :birthday, :last_signed_in, :format_with => :timestamp
+    #         expose :birthday, :last_signed_in, format_with: :timestamp
     #       end
     #     end
     #   end
@@ -256,20 +265,20 @@ module Grape
     #     class Users < Grape::API
     #       version 'v2'
     #
-    #       # this will render { "users": [ {"id":"1"}, {"id":"2"} ] }
+    #       # this will render { "users" : [ { "id" : "1" }, { "id" : "2" } ] }
     #       get '/users' do
     #         @users = User.all
-    #         present @users, :with => API::Entities::User
+    #         present @users, with: API::Entities::User
     #       end
     #
-    #       # this will render { "user": {"id":"1"} }
+    #       # this will render { "user" : { "id" : "1" } }
     #       get '/users/:id' do
     #         @user = User.find(params[:id])
-    #         present @user, :with => API::Entities::User
+    #         present @user, with: API::Entities::User
     #       end
     #     end
     #   end
-    def self.root(plural, singular=nil)
+    def self.root(plural, singular = nil)
       @collection_root = plural
       @root = singular
     end
@@ -284,21 +293,24 @@ module Grape
     # @param options [Hash] Options that will be passed through to each entity
     #   representation.
     #
-    # @option options :root [String] override the default root name set for the
-    #   entity. Pass nil or false to represent the object or objects with no
-    #   root name even if one is defined for the entity.
+    # @option options :root [String] override the default root name set for the entity.
+    #   Pass nil or false to represent the object or objects with no root name
+    #   even if one is defined for the entity.
     def self.represent(objects, options = {})
-      inner = if objects.respond_to?(:to_ary)
-        objects.to_ary().map{|o| self.new(o, {:collection => true}.merge(options))}
+      if objects.respond_to?(:to_ary)
+        inner = objects.to_ary.map { |object| new(object, { collection: true }.merge(options)) }
+        inner = inner.map(&:serializable_hash) if options[:serializable]
       else
-        self.new(objects, options)
+        inner = new(objects, options)
+        inner = inner.serializable_hash if options[:serializable]
       end
 
       root_element = if options.has_key?(:root)
-        options[:root]
-      else
-        objects.respond_to?(:to_ary) ? @collection_root : @root
-      end
+                       options[:root]
+                     else
+                       objects.respond_to?(:to_ary) ? @collection_root : @root
+                     end
+
       root_element ? { root_element => inner } : inner
     end
 
@@ -310,6 +322,12 @@ module Grape
       self.class.exposures
     end
 
+    def valid_exposures
+      exposures.select do |attribute, exposure_options|
+        valid_exposure?(attribute, exposure_options)
+      end
+    end
+
     def documentation
       self.class.documentation
     end
@@ -328,14 +346,18 @@ module Grape
     def serializable_hash(runtime_options = {})
       return nil if object.nil?
       opts = options.merge(runtime_options || {})
-      exposures.inject({}) do |output, (attribute, exposure_options)|
-        if (exposure_options.has_key?(:proc) || object.respond_to?(attribute)) && conditions_met?(exposure_options, opts)
+      valid_exposures.inject({}) do |output, (attribute, exposure_options)|
+        if conditions_met?(exposure_options, opts)
           partial_output = value_for(attribute, opts)
-          output[key_for(attribute)] =
+          output[self.class.key_for(attribute)] =
             if partial_output.respond_to? :serializable_hash
               partial_output.serializable_hash(runtime_options)
-            elsif partial_output.kind_of?(Array) && !partial_output.map {|o| o.respond_to? :serializable_hash}.include?(false)
-              partial_output.map {|o| o.serializable_hash}
+            elsif partial_output.kind_of?(Array) && !partial_output.map { |o| o.respond_to? :serializable_hash }.include?(false)
+              partial_output.map { |o| o.serializable_hash }
+            elsif partial_output.kind_of?(Hash)
+              partial_output.each do |key, value|
+                partial_output[key] = value.serializable_hash if value.respond_to? :serializable_hash
+              end
             else
               partial_output
             end
@@ -344,7 +366,7 @@ module Grape
       end
     end
 
-    alias :as_json :serializable_hash
+    alias_method :as_json, :serializable_hash
 
     def to_json(options = {})
       options = options.to_h if options && options.respond_to?(:to_h)
@@ -358,52 +380,149 @@ module Grape
 
     protected
 
-    def key_for(attribute)
-      exposures[attribute.to_sym][:as] || attribute.to_sym
+    def self.name_for(attribute)
+      attribute.to_s.split('__').last.to_sym
+    end
+
+    def self.key_for(attribute)
+      exposures[attribute.to_sym][:as] || name_for(attribute)
+    end
+
+    def self.nested_exposures_for(attribute)
+      exposures.select { |a, _| a.to_s =~ /^#{attribute}__/ }
     end
 
     def value_for(attribute, options = {})
       exposure_options = exposures[attribute.to_sym]
 
-      if exposure_options[:proc]
-        exposure_options[:proc].call(object, options)
-      elsif exposure_options[:using]
+      nested_exposures = self.class.nested_exposures_for(attribute)
+
+      if exposure_options[:using]
+        exposure_options[:using] = exposure_options[:using].constantize if exposure_options[:using].respond_to? :constantize
+
         using_options = options.dup
         using_options.delete(:collection)
         using_options[:root] = nil
-        exposure_options[:using].represent(object.send(attribute), using_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]
-          formatters[format_with].call(object.send(attribute))
+          instance_exec(delegate_attribute(attribute), &formatters[format_with])
         elsif format_with.is_a?(Symbol)
-          self.send(format_with, object.send(attribute))
+          send(format_with, delegate_attribute(attribute))
         elsif format_with.respond_to? :call
-          format_with.call(object.send(attribute))
+          instance_exec(delegate_attribute(attribute), &format_with)
         end
+
+      elsif nested_exposures.any?
+        Hash[nested_exposures.map do |nested_attribute, _|
+          [self.class.key_for(nested_attribute), value_for(nested_attribute, options)]
+        end]
+
       else
-        object.send(attribute)
+        delegate_attribute(attribute)
       end
     end
 
-    def conditions_met?(exposure_options, options)
-      if_condition = exposure_options[:if]
-      unless_condition = exposure_options[:unless]
+    def delegate_attribute(attribute)
+      name = self.class.name_for(attribute)
+      if respond_to?(name, true)
+        send(name)
+      else
+        object.send(name)
+      end
+    end
 
-      case if_condition
-        when Hash; if_condition.each_pair{|k,v| return false if options[k.to_sym] != v }
-        when Proc; return false unless if_condition.call(object, options)
-        when Symbol; return false unless options[if_condition]
+    def valid_exposure?(attribute, exposure_options)
+      nested_exposures = self.class.nested_exposures_for(attribute)
+      (nested_exposures.any? && nested_exposures.all? { |a, o| valid_exposure?(a, o) }) || \
+      exposure_options.has_key?(:proc) || \
+      !exposure_options[:safe] || \
+      object.respond_to?(self.class.name_for(attribute))
+    end
+
+    def conditions_met?(exposure_options, options)
+      if_conditions = (exposure_options[:if_extras] || []).dup
+      if_conditions << exposure_options[:if] unless exposure_options[:if].nil?
+
+      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
 
-      case unless_condition
-        when Hash; unless_condition.each_pair{|k,v| return false if options[k.to_sym] == v}
-        when Proc; return false if unless_condition.call(object, options)
-        when Symbol; return false if options[unless_condition]
+      unless_conditions = (exposure_options[:unless_extras] || []).dup
+      unless_conditions << exposure_options[:unless] unless exposure_options[:unless].nil?
+
+      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
     end
+
+    private
+
+    # All supported options.
+    OPTIONS = [
+      :as, :if, :unless, :using, :with, :proc, :documentation, :format_with, :safe, :if_extras, :unless_extras
+    ].to_set.freeze
+
+    # Merges the given options with current block options.
+    #
+    # @param options [Hash] Exposure options.
+    def self.merge_options(options)
+      opts = {}
+
+      merge_logic = proc do |key, existing_val, new_val|
+        if [: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)
+            (opts["#{key}_extras".to_sym] ||= []) << existing_val
+            new_val
+          else
+            (opts["#{key}_extras".to_sym] ||= []) << new_val
+            existing_val
+          end
+        else
+          new_val
+        end
+      end
+
+      @block_options ||= []
+      opts.merge @block_options.inject({}) { |final, step|
+        final.merge(step, &merge_logic)
+      }.merge(valid_options(options), &merge_logic)
+    end
+
+    # Raises an error if the given options include unknown keys.
+    # Renames aliased options.
+    #
+    # @param options [Hash] Exposure options.
+    def self.valid_options(options)
+      options.keys.each do |key|
+        raise ArgumentError, "#{key.inspect} is not a valid option." unless OPTIONS.include?(key)
+      end
+
+      options[:using] = options.delete(:with) if options.has_key?(:with)
+      options
+    end
   end
 end