grape-entity 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b398596f88871f8170eb2a73142bfdc08ca91370
-  data.tar.gz: 32aec8564a0c5f46522ffae2ac6167083440b8b0
+  metadata.gz: 35f4a45cc741d725e9cc8d180ae9db0f9123cb7a
+  data.tar.gz: a452232a49b72773f38710733c24104e113e7043
 SHA512:
-  metadata.gz: e6ced06ae9b0a8bada53aae31a4eba8d5a58b717797b72adc2953ed4431dc99b21e711b370f027b45c19ac1b27f312a1d1300e29da64964e2b7e70fbc1f3a96c
-  data.tar.gz: 58fb3f143bffa542f8a8cfe1ce3f19f1f924588a670697c1ae596e27a80dd28eefea8ee4a3031d4c7cf89eeea85f6fa7912bdf6400d29474c0273e358bf594f6
+  metadata.gz: aeaab5ee1c623a0f4359a4b5378b3536afefd0a23009007a5c0a91fb4086658da6abd53458ea85bcd724dea448b0598213160bf74b58084e4ee68a840e0df511
+  data.tar.gz: 6f187c4bb82bea91a739fb3dc8c48d04985b3b72d09e29e91e6565b42ceecb281275d3c973eb3062b25263a997955dcece3efa7fe297ca1dd1e209e7b18dc3ea

data/.gitignore

@@ -36,3 +36,4 @@ tmp
 .rbx
 
 ## PROJECT::SPECIFIC
+.project

data/.rubocop.yml

@@ -0,0 +1,69 @@
+AllCops:
+  Excludes:
+    - vendor/**
+
+LineLength:
+  Enabled: false
+
+MethodLength:
+  Enabled: false
+
+ClassLength:
+  Enabled: false
+
+Documentation:
+  # don't require classes to be documented
+  Enabled: false
+
+CollectionMethods:
+  # don't prefer map to collect, recuce to inject
+  Enabled: false
+
+Encoding:
+  # no need to always specify encoding
+  Enabled: false
+
+HashMethods:
+  # key? instead of has_key?
+  # value? instead of has_value?
+  Enabled: false
+
+StringLiterals:
+  # use single or double-quoted strings, as you please
+  Enabled: false
+
+Void:
+  # == operator used in void context in specs
+  Enabled: false
+
+SignalException:
+  # prefer raise to fail
+  EnforcedStyle: only_raise
+
+RaiseArgs:
+  # don't care for what kind of raise
+  Enabled: false
+
+PerlBackrefs:
+  # TODO: regular expression matching with $1, $2, etc.
+  Enabled: false
+
+BlockNesting:
+  # TODO: fix too much nesting
+  Max: 4
+
+Lambda:
+  # TODO: replace all lambda with -> or Proc
+  Enabled: false
+
+Blocks:
+  # allow multi-line blocks like expect { }
+  Enabled: false
+
+WordArray:
+  # %w vs. [ '', ... ]
+  Enabled: false
+
+CyclomaticComplexity:
+  Enabled: false
+

data/.travis.yml

@@ -1,8 +1,7 @@
+language: ruby
+cache: bundler
 rvm:
-  - 1.8.7
-  - 1.9.2
+  - 2.0.0
   - 1.9.3
-  - jruby
-  - rbx
-  - ree
-
+  - jruby-19mode
+  - rbx-2.1.1

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+Next Release
+============
+* Ruby 1.8.x is no longer supported - [@dblock](https://github.com/dblock).
+* [#36](https://github.com/intridea/grape-entity/pull/36): Enforcing Ruby style guidelines via Rubocop - [@dblock](https://github.com/dblock).
+* [#7](https://github.com/intridea/grape-entity/issues/7): Added `serializable` option to `represent` - [@mbleigh](https://github.com/mbleigh).
+* [#18](https://github.com/intridea/grape-entity/pull/18): Added `safe` option to `expose`, will not raise error for a missing attribute - [@fixme](https://github.com/fixme).
+* [#16](https://github.com/intridea/grape-entity/pull/16): Added `using` option to `expose SYMBOL BLOCK` - [@fahchen](https://github.com/fahchen).
+* [#24](https://github.com/intridea/grape-entity/pull/24): Return documentation with `as` param considered - [@drakula2k](https://github.com/drakula2k).
+* [#27](https://github.com/intridea/grape-entity/pull/27): Properly serialize hashes - [@clintonb](https://github.com/clintonb).
+* [#28](https://github.com/intridea/grape-entity/pull/28): Look for method on entity before calling it on the object - [@MichaelXavier](https://github.com/MichaelXavier).
+* [#33](https://github.com/intridea/grape-entity/pull/33): Support proper merging of nested conditionals - [@wyattisimo](https://github.com/wyattisimo).
+* [#43](https://github.com/intridea/grape-entity/pull/43): Call procs in context of entity instance - [@joelvh](https://github.com/joelvh).
+* [#47](https://github.com/intridea/grape-entity/pull/47): Support nested exposures - [@wyattisimo](https://github.com/wyattisimo).
+* [#46](https://github.com/intridea/grape-entity/issues/46), [#50](https://github.com/intridea/grape-entity/pull/50): Added support for specifying the presenter class in `using` in string format - [@larryzhao](https://github.com/larryzhao).
+* [#51](https://github.com/intridea/grape-entity/pull/51): Raise `ArgumentError` if an unknown option is used with `expose` - [@aj0strow](https://github.com/aj0strow).
+* [#51](https://github.com/intridea/grape-entity/pull/51): Alias `:with` to `:using`, consistently with the Grape api endpoints - [@aj0strow](https://github.com/aj0strow).
+* Your contribution here.
+
+0.3.0 (2013-03-29)
+==================
+
+* [#9](https://github.com/intridea/grape-entity/pull/9): Added `with_options` for block-level exposure setting - [@SegFaultAX](https://github.com/SegFaultAX).
+* The `instance.entity` method now optionally accepts `options` - [@mbleigh](https://github.com/mbleigh).
+* You can pass symbols to `:if` and `:unless` to simply check for truthiness/falsiness of the specified options key - [@mbleigh](https://github.com/mbleigh).
+
+0.2.0 (2013-01-11)
+==================
+
+* Moved the namespace back to `Grape::Entity` to preserve compatibility with Grape - [@dblock](https://github.com/dblock).
+
+0.1.0 (2013-01-11)
+==================
+
+* Initial public release - [@agileanimal](https://github.com/agileanimal).
+

data/Gemfile

@@ -13,4 +13,11 @@ group :development, :test do
   gem 'rspec'
   gem 'rack-test', "~> 0.6.2", :require => "rack/test"
   gem 'github-markup'
+  gem 'rubocop', '~> 0.16.0'
+end
+
+platforms :rbx do
+  gem 'rubysl', '~> 2.0'
+  gem 'parser', '~> 2.1'
+  gem 'racc', '~> 1.4'
 end

data/Guardfile

@@ -8,7 +8,6 @@ guard 'rspec', :version => 2 do
   watch('spec/spec_helper.rb')  { "spec/" }
 end
 
-
 guard 'bundler' do
   watch('Gemfile')
   watch(/^.+\.gemspec/)

data/README.md

@@ -0,0 +1,320 @@
+# Grape::Entity
+
+[![Build Status](https://travis-ci.org/agileanimal/grape-entity.png?branch=master)](https://travis-ci.org/agileanimal/grape-entity)
+
+## Introduction
+
+This gem adds Entity support to API frameworks, such as [Grape](https://github.com/intridea/grape). Grape's Entity is an API focused facade that sits on top of an object model.
+
+### Example
+
+```ruby
+module API
+  module Entities
+    class Status < Grape::Entity
+      format_with(:iso_timestamp) { |dt| dt.iso8601 }
+
+      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 :contact_info do
+        expose :phone
+        expose :address, using: API::Address
+      end
+      expose :digest do |status, options|
+        Digest::MD5.hexdigest status.txt
+      end
+      expose :replies, using: API::Status, as: :replies
+      expose :last_reply, using: API::Status do |status, options|
+        status.replies.last
+      end
+
+      with_options(format_with: :iso_timestamp) do
+        expose :created_at
+        expose :updated_at
+      end
+    end
+  end
+end
+
+module API
+  module Entities
+    class StatusDetailed < API::Entities::Status
+      expose :internal_id
+    end
+  end
+end
+```
+
+## 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 Grape::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`.
+
+#### Basic Exposure
+
+Define a list of fields that will always be exposed.
+
+```ruby
+expose :user_name, :ip
+```
+
+#### Exposing with a Presenter
+
+Don't derive your model classes from `Grape::Entity`, expose them using a presenter.
+
+```ruby
+expose :replies, using: API::Status, as: :replies
+```
+
+Presenter classes can also be specified in string format, which helps with circular dependencies.
+
+```ruby
+expose :replies, using: `API::Status`, as: :replies
+```
+
+#### Conditional Exposure
+
+Use `:if` or `:unless` to expose fields conditionally.
+
+```ruby
+expose :ip, if: { type: :full }
+
+expose :ip, if: lambda { |instance, options| options[:type] == :full } # exposed if the function evaluates to true
+expose :ip, if: :type # exposed if :type is available in the options hash
+expose :ip, if { type: :full } # exposed if options :type has a value of :full
+
+expose :ip, unless: ... # the opposite of :if
+```
+
+#### Safe Exposure
+
+Don't raise an exception and expose as nil, even if the :x cannot be evaluated.
+
+```ruby
+expose :ip, safe: true
+```
+
+#### Nested Exposure
+
+Supply a block to define a hash using nested exposures.
+
+```ruby
+expose :contact_info do
+  expose :phone
+  expose :address, using: API::Address
+end
+```
+
+#### Runtime Exposure
+
+Use a block or a `Proc` to evaluate exposure at runtime. The supplied block or
+`Proc` will be called with two parameters: the represented object and runtime options.
+
+**NOTE:** A block supplied with no parameters will be evaluated as a nested exposure (see above).
+
+```ruby
+expose :digest do |status, options|
+  Digest::MD5.hexdigest status.txt
+end
+```
+
+```ruby
+expose :digest, proc: ... # equivalent to a block
+```
+
+You can also define a method on the entity and it will try that before trying
+on the object the entity wraps.
+
+```ruby
+class ExampleEntity < Grape::Entity
+  expose :attr_not_on_wrapped_object
+  # ...
+private
+
+  def attr_not_on_wrapped_object
+    42
+  end
+end
+```
+
+#### Aliases
+
+Expose under a different name with `:as`.
+
+```ruby
+expose :replies, using: API::Status, as: :replies
+```
+
+#### Format Before Exposing
+
+Apply a formatter before exposing a value.
+
+```ruby
+format_with(:iso_timestamp) { |dt| dt.iso8601 }
+with_options(format_with: :iso_timestamp) do
+  expose :created_at
+  expose :updated_at
+end
+```
+
+#### Documentation
+
+Expose documentation with the field. Gets bubbled up when used with Grape and various API documentation systems.
+
+```ruby
+expose :text, documentation: { type: "String", desc: "Status update text." }
+```
+
+### Options Hash
+
+The option keys `:version` and `:collection` are always 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. The options also contain the runtime environment in `:env`, which includes request parameters in `options[:env][:grape.request.params]`.
+
+Any additional options defined on the entity exposure are included as is. In the following example `user` is set to the value of `current_user`.
+
+```ruby
+class Status < Grape::Entity
+  expose :user, if: lambda { |instance, options| options[:user] } do |instance, options|
+    # examine available environment keys with `p options[:env].keys`
+    options[:user]
+  end
+end
+```
+
+```
+present s, with: Status, user: current_user
+```
+
+### Using the Exposure DSL
+
+Grape ships with a DSL to easily define entities within the context of an existing class:
+
+```ruby
+class Status
+  include Grape::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
+
+With Grape, 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 < Grape::API
+    version 'v1'
+
+    desc 'Statuses.', {
+      params: 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
+    Entity.new(self)
+  end
+
+  class Entity < Grape::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 < Grape::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 < Grape::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
+```
+
+Also note that an `ArgumentError` is raised when unknown options are passed to either `expose` or `with_options`.
+
+## 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
+
+## Testing with Entities
+
+Test API request/response as usual.
+
+Also see [Grape Entity Matchers](https://github.com/agileanimal/grape-entity-matchers).
+
+## Project Resources
+
+* Need help? [Grape Google Group](http://groups.google.com/group/ruby-grape)
+
+## Contributing
+
+1. Fork the project
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Write tests. Make changes. Run `rubocop`.
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new pull request
+
+## License
+
+MIT License. See LICENSE for details.
+
+## Copyright
+
+Copyright (c) 2010-2013 Michael Bleigh, Intridea, Inc., and contributors.
+