grape-entity 0.1.0

data/.gitignore

@@ -0,0 +1,37 @@
+## MAC OS
+.DS_Store
+.com.apple.timemachine.supported
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## REDCAR
+.redcar
+
+## VIM
+*.swp
+*.swo
+
+## RUBYMINE
+.idea
+
+## PROJECT::GENERAL
+coverage
+doc
+pkg
+.rvmrc
+.bundle
+.yardoc/*
+dist
+Gemfile.lock
+
+## Rubinius
+.rbx
+
+## PROJECT::SPECIFIC

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format=progress

data/.travis.yml

@@ -0,0 +1,8 @@
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - jruby
+  - rbx
+  - ree
+

data/.yardopts

@@ -0,0 +1,2 @@
+--markup-provider=redcarpet
+--markup=markdown

data/CHANGELOG.markdown

@@ -0,0 +1,8 @@
+Next Release
+============
+* Your contribution here.
+
+0.1.0 (01/11/2013)
+==================
+
+* Initial Release

data/Gemfile

@@ -0,0 +1,16 @@
+source 'http://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'pry'
+  gem 'guard'
+  gem 'guard-rspec'
+  gem 'guard-bundler'
+  gem 'rb-fsevent'
+  gem 'growl'
+  gem 'json'
+  gem 'rspec'
+  gem 'rack-test', "~> 0.6.2", :require => "rack/test"
+  gem 'github-markup'
+end

data/Guardfile

@@ -0,0 +1,15 @@
+# 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{^spec/support/shared_versioning_examples.rb$}) { |m| "spec/" }
+  watch('spec/spec_helper.rb')  { "spec/" }
+end
+
+
+guard 'bundler' do
+  watch('Gemfile')
+  watch(/^.+\.gemspec/)
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Michael Bleigh and Intridea, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,210 @@
+# GrapeEntity
+
+## CI
+[![Build Status](https://travis-ci.org/agileanimal/grape-entity.png?branch=master)](https://travis-ci.org/agileanimal/grape-entity)
+
+## Introduction
+
+This gem is the Entity extracted out of [Grape](https://github.com/intridea/grape).
+
+Grape's Entity is a great idea: a API focussed Facade that sits on top of a model object.
+
+The intend is to allow the Entity to be used outside of Grape and provide additional exposure to parts of the entity needed to simplify testing parts of an API.
+
+We intend to use the specs from grape to ensure we maintain compatability with Grape through our changes so that we can use the Entity to replace Grape's internal Entity.
+
+## Goals
+
+Through my own use of Entities I have found them really useful but wished they could be reused in other situations. In the context of Grape I wish it was easier to test the Entity so that you could test them seperately from your API and isolate their behavior. Entities also have a deep connection with the model and they should know what parameters are required and (especially in the case of an ActiveRecord Model) they should know how to ask about validation.
+
+The Entity is a simple Facade on top of the model to transform it into the object you want to expose on your API.
+
+There is probably something heavier than an Entity that exists as well. A way to get a model object back from the Entity.
+
+In this spirit I want to give Entities a life of their own.
+
+## Project Tracking
+
+* - Need to setup something up for this - 
+
+## Reusable Responses with Entities
+
+Entities are a reusable means for converting Ruby objects to API responses.
+Entities can be used to conditionally include fields, nest other entities, and build
+ever larger responses, using inheritance.
+
+### Defining Entities
+
+Entities inherit from GrapeEntity::Entity, and define a simple DSL. Exposures can use
+runtime options to determine which fields should be visible, these options are
+available to `:if`, `:unless`, and `:proc`. The option keys `:version` and `:collection`
+will always be defined. The `:version` key is defined as `api.version`. The
+`:collection` key is boolean, and defined as `true` if the object presented is an
+array.
+
+  * `expose SYMBOLS`
+    * define a list of fields which will always be exposed
+  * `expose SYMBOLS, HASH`
+    * HASH keys include `:if`, `:unless`, `:proc`, `:as`, `:using`, `:format_with`, `:documentation`
+      * `:if` and `:unless` accept hashes (passed during runtime) or procs (arguments are object and options)
+  * `expose SYMBOL, { :format_with => :formatter }`
+    * expose a value, formatting it first
+    * `:format_with` can only be applied to one exposure at a time
+  * `expose SYMBOL, { :as => "alias" }`
+    * Expose a value, changing its hash key from SYMBOL to alias
+    * `:as` can only be applied to one exposure at a time
+  * `expose SYMBOL BLOCK`
+    * block arguments are object and options
+    * expose the value returned by the block
+    * block can only be applied to one exposure at a time
+
+```ruby
+module API
+  module Entities
+    class Status < GrapeEntity::Entity
+      expose :user_name
+      expose :text, :documentation => { :type => "string", :desc => "Status update text." }
+      expose :ip, :if => { :type => :full }
+      expose :user_type, user_id, :if => lambda{ |status, options| status.user.public? }
+      expose :digest { |status, options| Digest::MD5.hexdigest(satus.txt) }
+      expose :replies, :using => API::Status, :as => :replies
+    end
+  end
+end
+
+module API
+  module Entities
+    class StatusDetailed < API::Entities::Status
+      expose :internal_id
+    end
+  end
+end
+```
+
+#### Using the Exposure DSL
+
+Grape ships with a DSL to easily define entities within the context
+of an existing class:
+
+```ruby
+class Status
+  include GrapeEntity::Entity::DSL
+
+  entity :text, :user_id do
+    expose :detailed, if: :conditional
+  end
+end
+```
+
+The above will automatically create a `Status::Entity` class and define properties on it according
+to the same rules as above. If you only want to define simple exposures you don't have to supply
+a block and can instead simply supply a list of comma-separated symbols.
+
+### Using Entities
+
+Once an entity is defined, it can be used within endpoints, by calling `present`. The `present`
+method accepts two arguments, the object to be presented and the options associated with it. The
+options hash must always include `:with`, which defines the entity to expose.
+
+If the entity includes documentation it can be included in an endpoint's description.
+
+```ruby
+module API
+  class Statuses < GrapeEntity::API
+    version 'v1'
+
+    desc 'Statuses index', {
+      :object_fields => API::Entities::Status.documentation
+    }
+    get '/statuses' do
+      statuses = Status.all
+      type = current_user.admin? ? :full : :default
+      present statuses, with: API::Entities::Status, :type => type
+    end
+  end
+end
+```
+
+### Entity Organization
+
+In addition to separately organizing entities, it may be useful to put them as namespaced
+classes underneath the model they represent.
+
+```ruby
+class Status
+  def entity
+    Status.new(self)
+  end
+
+  class Entity < GrapeEntity::Entity
+    expose :text, :user_id
+  end
+end
+```
+
+If you organize your entities this way, Grape will automatically detect the `Entity` class and
+use it to present your models. In this example, if you added `present User.new` to your endpoint,
+Grape would automatically detect that there is a `Status::Entity` class and use that as the
+representative entity. This can still be overridden by using the `:with` option or an explicit
+`represents` call.
+
+### Caveats
+
+Entities with duplicate exposure names and conditions will silently overwrite one another.
+In the following example, when `object.check` equals "foo", only `field_a` will be exposed.
+However, when `object.check` equals "bar" both `field_b` and `foo` will be exposed.
+
+```ruby
+module API
+  module Entities
+    class Status < GrapeEntity::Entity
+      expose :field_a, :foo, :if => lambda { |object, options| object.check == "foo" }
+      expose :field_b, :foo, :if => lambda { |object, options| object.check == "bar" }
+    end
+  end
+end
+```
+
+This can be problematic, when you have mixed collections. Using `respond_to?` is safer.
+
+```ruby
+module API
+  module Entities
+    class Status < GrapeEntity::Entity
+      expose :field_a, :if => lambda { |object, options| object.check == "foo" }
+      expose :field_b, :if => lambda { |object, options| object.check == "bar" }
+      expose :foo, :if => lambda { |object, options| object.respond_to?(:foo) }
+    end
+  end
+end
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'grape-entity'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install grape-entity
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+MIT License. See LICENSE for details.
+
+## Copyright
+
+Copyright (c) 2010-2012 Michael Bleigh, and Intridea, Inc.

data/Rakefile

@@ -0,0 +1,51 @@
+require 'rubygems'
+require 'bundler'
+Bundler.setup :default, :test, :development
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec
+task :default => :spec
+
+#
+# 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

data/grape-entity.gemspec

@@ -0,0 +1,35 @@
+$:.push File.expand_path("../lib", __FILE__)
+require "grape_entity/version"
+
+Gem::Specification.new do |s|
+  s.name        = "grape-entity"
+  s.version     = GrapeEntity::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Michael Bleigh"]
+  s.email       = ["michael@intridea.com"]
+  s.homepage    = "https://github.com/intridea/grape"
+  s.summary     = %q{A simple facade for managing the relationship between your model and API.}
+  s.description = %q{Extracted from Grape, A Ruby framework for rapid API development with great conventions.}
+  s.license     = "MIT"
+
+  s.rubyforge_project = "grape-entity"
+
+  # s.add_runtime_dependency 'activesupport'
+  # s.add_runtime_dependency 'rack-jsonp'
+  # s.add_runtime_dependency 'multi_json', '>= 1.3.2'
+  # s.add_runtime_dependency 'multi_xml', '>= 0.5.2'
+  # s.add_runtime_dependency 'hashie', '~> 1.2'
+  # s.add_runtime_dependency 'virtus'
+  # s.add_runtime_dependency 'builder'
+
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'maruku'
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'rspec', '~> 2.9'
+  s.add_development_dependency 'bundler'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/grape-entity.rb

@@ -0,0 +1 @@
+require 'grape_entity'

data/lib/grape_entity.rb

@@ -0,0 +1,5 @@
+require "grape_entity/version"
+
+module GrapeEntity
+  autoload :Entity, 'grape_entity/entity'
+end

data/lib/grape_entity/entity.rb

@@ -0,0 +1,389 @@
+module GrapeEntity
+  # An Entity is a lightweight structure that allows you to easily
+  # represent data from your application in a consistent and abstracted
+  # way in your API. Entities can also provide documentation for the
+  # fields exposed.
+  #
+  # @example Entity Definition
+  #
+  #   module API
+  #     module Entities
+  #       class User < GrapeEntity::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(' ')}
+  #       end
+  #     end
+  #   end
+  #
+  # Entities are not independent structures, rather, they create
+  # **representations** of other Ruby objects using a number of methods
+  # that are convenient for use in an API. Once you've defined an Entity,
+  # you can use it in your API like this:
+  #
+  # @example Usage in the API Layer
+  #
+  #   module API
+  #     class Users < GrapeEntity::API
+  #       version 'v2'
+  #
+  #       desc 'User index', { :object_fields => API::Entities::User.documentation }
+  #       get '/users' do
+  #         @users = User.all
+  #         type = current_user.admin? ? :full : :default
+  #         present @users, :with => API::Entities::User, :type => type
+  #       end
+  #     end
+  #   end
+  class Entity
+    attr_reader :object, :options
+
+    # The Entity DSL allows you to mix entity functionality into
+    # your existing classes.
+    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)}
+        base.const_set(:Entity, Class.new(ancestor_entity_class || GrapeEntity::Entity)) unless const_defined?(:Entity)
+      end
+
+      module ClassMethods
+        # Returns the automatically-created entity class for this
+        # Class.
+        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
+        end
+
+        # Call this to make exposures to the entity for this Class.
+        # Can be called with symbols for the attributes to expose,
+        # a block that yields the full Entity DSL (See GrapeEntity::Entity),
+        # or both.
+        #
+        # @example Symbols only.
+        #
+        #   class User
+        #     include GrapeEntity::Entity::DSL
+        #     
+        #     entity :name, :email
+        #   end
+        #
+        # @example Mixed.
+        #
+        #   class User
+        #     include GrapeEntity::Entity::DSL
+        #     
+        #     entity :name, :email do
+        #       expose :latest_status, using: Status::Entity, if: :include_status
+        #       expose :new_attribute, :if => {:version => 'v2'}
+        #     end
+        #   end
+        def entity(*exposures, &block)
+          entity_class.expose *exposures if exposures.any?
+          entity_class.class_eval(&block) if block_given?
+          entity_class
+        end
+      end
+
+      # Instantiates an entity version of this object.
+      def entity
+        self.class.entity_class.new(self)
+      end
+    end
+
+    # This method is the primary means by which you will declare what attributes
+    # should be exposed by the entity.
+    #
+    # @option options :as Declare an alias for the representation of this attribute.
+    # @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
+    #   options passed into the representation call. Return true if you want the attribute
+    #   to be exposed.
+    # @option options :unless When passed a Hash, the attribute will be exposed if the
+    #   runtime options fail to match any of the conditions passed in. If passed a lambda,
+    #   it will yield the object being represented and the options passed to the
+    #   representation call. Return true to prevent exposure, false to allow it.
+    # @option options :using This option allows you to map an attribute to another Grape
+    #   Entity. Pass it a GrapeEntity::Entity class and the attribute in question will
+    #   automatically be transformed into a representation that will receive the same
+    #   options as the parent entity when called. Note that arrays are fine here and
+    #   will automatically be detected and handled appropriately.
+    # @option options :proc If you pass a Proc into this option, it will
+    #   be used directly to determine the value for that attribute. It
+    #   will be called with the represented object as well as the
+    #   runtime options that were passed in. You can also just supply a
+    #   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.
+    def self.expose(*args, &block)
+      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 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)
+
+      options[:proc] = block if block_given?
+
+      args.each do |attribute|
+        exposures[attribute.to_sym] = options
+      end
+    end
+
+    # Returns a hash of 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.
+    def self.exposures
+      @exposures ||= {}
+
+      if superclass.respond_to? :exposures
+        @exposures = superclass.exposures.merge(@exposures)
+      end
+
+      @exposures
+    end
+
+    # Returns a hash, the keys are symbolized references to fields in the entity,
+    # 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
+
+      if superclass.respond_to? :documentation
+        @documentation = superclass.documentation.merge(@documentation)
+      end
+
+      @documentation
+    end
+
+    # This allows you to declare a Proc in which exposures can be formatted with.
+    # It take a block with an arity of 1 which is passed as the value of the exposed attribute.
+    #
+    # @param name [Symbol] the name of the formatter
+    # @param block [Proc] the block that will interpret the exposed attribute
+    #
+    #
+    #
+    # @example Formatter declaration
+    #
+    #   module API
+    #     module Entities
+    #       class User < GrapeEntity::Entity
+    #         format_with :timestamp do |date|
+    #           date.strftime('%m/%d/%Y')
+    #         end
+    #
+    #         expose :birthday, :last_signed_in, :format_with => :timestamp
+    #       end
+    #     end
+    #   end
+    #
+    # @example Formatters are available to all decendants
+    #
+    #   GrapeEntity::Entity.format_with :timestamp do |date|
+    #     date.strftime('%m/%d/%Y')
+    #   end
+    #
+    def self.format_with(name, &block)
+      raise ArgumentError, "You must pass a block for formatters" unless block_given?
+      formatters[name.to_sym] = block
+    end
+
+    # Returns a hash of all formatters that are registered for this and it's ancestors.
+    def self.formatters
+      @formatters ||= {}
+
+      if superclass.respond_to? :formatters
+        @formatters = superclass.formatters.merge(@formatters)
+      end
+
+      @formatters
+    end
+
+    # This allows you to set a root element name for your representation.
+    #
+    # @param plural   [String] the root key to use when representing
+    #   a collection of objects. If missing or nil, no root key will be used
+    #   when representing collections of objects.
+    # @param singular [String] the root key to use when representing
+    #   a single object. If missing or nil, no root key will be used when
+    #   representing an individual object.
+    #
+    # @example Entity Definition
+    #
+    #   module API
+    #     module Entities
+    #       class User < GrapeEntity::Entity
+    #         root 'users', 'user'
+    #         expose :id
+    #       end
+    #     end
+    #   end
+    #
+    # @example Usage in the API Layer
+    #
+    #   module API
+    #     class Users < GrapeEntity::API
+    #       version 'v2'
+    #
+    #       # this will render { "users": [ {"id":"1"}, {"id":"2"} ] }
+    #       get '/users' do
+    #         @users = User.all
+    #         present @users, :with => API::Entities::User
+    #       end
+    #
+    #       # this will render { "user": {"id":"1"} }
+    #       get '/users/:id' do
+    #         @user = User.find(params[:id])
+    #         present @user, :with => API::Entities::User
+    #       end
+    #     end
+    #   end
+    def self.root(plural, singular=nil)
+      @collection_root = plural
+      @root = singular
+    end
+
+    # This convenience method allows you to instantiate one or more entities by
+    # passing either a singular or collection of objects. Each object will be
+    # initialized with the same options. If an array of objects is passed in,
+    # an array of entities will be returned. If a single object is passed in,
+    # a single entity will be returned.
+    #
+    # @param objects [Object or Array] One or more objects to be represented.
+    # @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.
+    def self.represent(objects, options = {})
+      inner = if objects.respond_to?(:to_ary)
+        objects.to_ary().map{|o| self.new(o, {:collection => true}.merge(options))}
+      else
+        self.new(objects, options)
+      end
+
+      root_element = if options.has_key?(:root)
+        options[:root]
+      else
+        objects.respond_to?(:to_ary) ? @collection_root : @root
+      end
+      root_element ? { root_element => inner } : inner
+    end
+
+    def initialize(object, options = {})
+      @object, @options = object, options
+    end
+
+    def exposures
+      self.class.exposures
+    end
+
+    def documentation
+      self.class.documentation
+    end
+
+    def formatters
+      self.class.formatters
+    end
+
+    # The serializable hash is the Entity's primary output. It is the transformed
+    # hash for the given data model and is used as the basis for serialization to
+    # JSON and other formats.
+    #
+    # @param runtime_options [Hash] Any options you pass in here will be known to the entity
+    #   representation, this is where you can trigger things from conditional options
+    #   etc.
+    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)
+          partial_output = value_for(attribute, opts)
+          output[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}
+            else
+              partial_output
+            end
+        end
+        output
+      end
+    end
+
+    alias :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 key_for(attribute)
+      exposures[attribute.to_sym][:as] || attribute.to_sym
+    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]
+        using_options = options.dup
+        using_options.delete(:collection)
+        using_options[:root] = nil
+        exposure_options[:using].represent(object.send(attribute), using_options)
+      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))
+        elsif format_with.is_a?(Symbol)
+          self.send(format_with, object.send(attribute))
+        elsif format_with.respond_to? :call
+          format_with.call(object.send(attribute))
+        end
+      else
+        object.send(attribute)
+      end
+    end
+
+    def conditions_met?(exposure_options, options)
+      if_condition = exposure_options[:if]
+      unless_condition = exposure_options[:unless]
+
+      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)
+      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)
+      end
+
+      true
+    end
+  end
+end