grape 0.9.0 → 0.10.0

data/RELEASING.md

@@ -1,7 +1,7 @@
 Releasing Grape
 ===============
 
-There're no particular rules about when to release Grape. Release bug fixes frequenty, features not so frequently and breaking API changes rarely.
+There're no particular rules about when to release Grape. Release bug fixes frequently, features not so frequently and breaking API changes rarely.
 
 ### Release
 

data/Rakefile

@@ -37,17 +37,16 @@ begin
     end
 
     namespace :pages do
-
-      desc "Check out gh-pages."
+      desc 'Check out gh-pages.'
       task :checkout do
         dir = File.dirname(__FILE__) + '/../grape.doc'
         unless Dir.exist?(dir)
           Dir.mkdir(dir)
           Dir.chdir(dir) do
-            system("git init")
-            system("git remote add origin git@github.com:intridea/grape.git")
-            system("git pull")
-            system("git checkout gh-pages")
+            system('git init')
+            system('git remote add origin git@github.com:intridea/grape.git')
+            system('git pull')
+            system('git checkout gh-pages')
           end
         end
       end
@@ -55,15 +54,15 @@ begin
       desc 'Generate and publish YARD docs to GitHub pages.'
       task :publish => ['doc:pages:checkout', 'doc:pages'] do
         Dir.chdir(File.dirname(__FILE__) + '/../grape.doc') do
-          system("git checkout gh-pages")
-          system("git add .")
-          system("git add -u")
+          system('git checkout gh-pages')
+          system('git add .')
+          system('git add -u')
           system("git commit -m 'Generating docs for version #{Grape::VERSION}.'")
-          system("git push origin gh-pages")
+          system('git push origin gh-pages')
         end
       end
     end
   end
 rescue LoadError
-  puts "You need to install YARD."
+  puts 'You need to install YARD.'
 end

data/UPGRADING.md

@@ -1,13 +1,221 @@
 Upgrading Grape
 ===============
 
-### Upgrading to >= 0.9.0 
+### Upgrading to >= 0.10.0
+
+#### Changes to content-types
+
+The following content-types have been removed:
+
+* atom (application/atom+xml)
+* rss (application/rss+xml)
+* jsonapi (application/jsonapi)
+
+This is because they have never been properly supported.
+
+#### Changes to desc
+
+New block syntax:
+
+Former:
+
+```ruby
+  desc "some descs",
+    detail: 'more details',
+    entity: API::Entities::Entity,
+    params: API::Entities::Status.documentation,
+    named: 'a name',
+    headers: [XAuthToken: {
+      description: 'Valdates your identity',
+      required: true
+    }
+  get nil, http_codes: [
+    [401, 'Unauthorized', API::Entities::BaseError],
+    [404, 'not found', API::Entities::Error]
+  ] do
+```
+
+Now:
+
+```ruby
+desc "some descs" do
+  detail 'more details'
+  params API::Entities::Status.documentation
+  success API::Entities::Entity
+  failure [
+    [401, 'Unauthorized', API::Entities::BaseError],
+    [404, 'not found', API::Entities::Error]
+  ]
+  named 'a name'
+  headers [
+    XAuthToken: {
+      description: 'Valdates your identity',
+      required: true
+    },
+    XOptionalHeader: {
+      description: 'Not really needed',
+      required: false
+    }
+  ]
+end
+```
+
+#### Changes to Route Options and Descriptions
+
+A common hack to extend Grape with custom DSL methods was manipulating `@last_description`.
+
+``` ruby
+module Grape
+  module Extensions
+    module SortExtension
+      def sort(value)
+        @last_description ||= {}
+        @last_description[:sort] ||= {}
+        @last_description[:sort].merge! value
+        value
+      end
+    end
+
+    Grape::API.extend self
+  end
+end
+```
+
+You could access this value from within the API with `route.route_sort` or, more generally, via `env['api.endpoint'].options[:route_options][:sort]`.
+
+This will no longer work, use the documented and supported `route_setting`.
+
+``` ruby
+module Grape
+  module Extensions
+    module SortExtension
+      def sort(value)
+        route_setting :sort, sort: value
+        value
+      end
+    end
+
+    Grape::API.extend self
+  end
+end
+```
+
+To retrieve this value at runtime from within an API, use `env['api.endpoint'].route_setting(:sort)` and when introspecting a mounted API, use `route.route_settings[:sort]`.
+
+#### Accessing Class Variables from Helpers
+
+It used to be possible to fetch an API class variable from a helper function. For example:
+
+```ruby
+@@static_variable = 42
+
+helpers do
+  def get_static_variable
+    @@static_variable
+  end
+end
+
+get do
+  get_static_variable
+end
+```
+
+This will no longer work. Use a class method instead of a helper.
+
+```ruby
+@@static_variable = 42
+
+def self.get_static_variable
+  @@static_variable
+end
+
+get do
+  get_static_variable
+end
+```
+
+For more information see [#836](https://github.com/intridea/grape/issues/836).
+
+#### Changes to Custom Validators
+
+To implement a custom validator, you need to inherit from `Grape::Validations::Base` instead of `Grape::Validations::Validator`.
+
+For more information see [Custom Validators](https://github.com/intridea/grape#custom-validators) in the documentation.
+
+#### Changes to Raising Grape::Exceptions::Validation
+
+In previous versions raising `Grape::Exceptions::Validation` required a single `param`.
+
+```ruby
+raise Grape::Exceptions::Validation, param: :id, message_key: :presence
+```
+
+The `param` argument has been deprecated and is now an array of `params`, accepting multiple values.
+
+```ruby
+raise Grape::Exceptions::Validation, params: [:id], message_key: :presence
+```
+
+#### Changes to routes when using `format`
+
+Routes will no longer get file-type suffixes added if you declare a single API `format`. For example,
+
+```ruby
+class API < Grape::API
+  format :json
+
+  get :hello do
+    { hello: 'world' }
+  end
+end
+```
+
+Pre-0.10.0, this would respond with JSON to `/hello`, `/hello.json`, `/hello.xml`, `/hello.txt`, etc.
+
+Now, this will only respond with JSON to `/hello`, but will be a 404 when trying to access `/hello.json`, `/hello.xml`, `/hello.txt`, etc.
+
+If you declare further `content_type`s, this behavior will be circumvented. For example, the following API will respond with JSON to `/hello`, `/hello.json`, `/hello.xml`, `/hello.txt`, etc.
+
+```ruby
+class API < Grape::API
+  format :json
+  content_type :json, 'application/json'
+
+  get :hello do
+    { hello: 'world' }
+  end
+end
+```
+
+See the [the updated API Formats documentation](https://github.com/intridea/grape#api-formats) and [#809](https://github.com/intridea/grape/pull/809) for more info.
+
+#### Changes to Evaluation of Permitted Parameter Values
+
+Permitted and default parameter values are now only evaluated lazily for each request when declared as a proc. The following code would raise an error at startup time.
+
+```ruby
+params do
+  optional :v, values: -> { [:x, :y] }, default: -> { :z } }
+end
+```
+
+Remove the proc to get the previous behavior.
+
+```ruby
+params do
+  optional :v, values: [:x, :y], default: :z }
+end
+```
+
+See [#801](https://github.com/intridea/grape/issues/801) for more information.
+
+### Upgrading to >= 0.9.0
 
 #### Changes in Authentication
 
 The following middleware classes have been removed:
 
-* `Grape::Middleware::Auth::Basic` 
+* `Grape::Middleware::Auth::Basic`
 * `Grape::Middleware::Auth::Digest`
 * `Grape::Middleware::Auth::OAuth2`
 
@@ -20,7 +228,7 @@ When you use theses classes directly like:
        use Grape::Middleware::Auth::OAuth2,
            token_class: 'AccessToken',
            parameter: %w(access_token api_key)
-           
+
 ```
 
 you have to replace these classes.

data/gemfiles/rails_3.gemfile

@@ -0,0 +1,14 @@
+# This file was generated by Appraisal
+
+source 'http://rubygems.org'
+
+gem 'rails', '3.2.19'
+
+group :development, :test do
+  gem 'rubocop', '~> 0.28.0'
+  gem 'guard'
+  gem 'guard-rspec'
+  gem 'guard-rubocop'
+end
+
+gemspec :path => '../'

data/gemfiles/rails_4.gemfile

@@ -0,0 +1,14 @@
+# This file was generated by Appraisal
+
+source 'http://rubygems.org'
+
+gem 'rails', '4.1.6'
+
+group :development, :test do
+  gem 'rubocop', '~> 0.28.0'
+  gem 'guard'
+  gem 'guard-rspec'
+  gem 'guard-rubocop'
+end
+
+gemspec :path => '../'

data/grape.gemspec

@@ -1,18 +1,18 @@
-$:.push File.expand_path("../lib", __FILE__)
-require "grape/version"
+$:.push File.expand_path('../lib', __FILE__)
+require 'grape/version'
 
 Gem::Specification.new do |s|
-  s.name        = "grape"
+  s.name        = 'grape'
   s.version     = Grape::VERSION
   s.platform    = Gem::Platform::RUBY
-  s.authors     = ["Michael Bleigh"]
-  s.email       = ["michael@intridea.com"]
-  s.homepage    = "https://github.com/intridea/grape"
+  s.authors     = ['Michael Bleigh']
+  s.email       = ['michael@intridea.com']
+  s.homepage    = 'https://github.com/intridea/grape'
   s.summary     = %q{A simple Ruby framework for building REST-like APIs.}
   s.description = %q{A Ruby framework for rapid API development with great conventions.}
-  s.license     = "MIT"
+  s.license     = 'MIT'
 
-  s.rubyforge_project = "grape"
+  s.rubyforge_project = 'grape'
 
   s.add_runtime_dependency 'rack', '>= 1.3.0'
   s.add_runtime_dependency 'rack-mount'
@@ -34,9 +34,10 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'cookiejar'
   s.add_development_dependency 'rack-contrib'
   s.add_development_dependency 'mime-types'
+  s.add_development_dependency 'appraisal'
 
   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"]
+  s.require_paths = ['lib']
 end

data/lib/backports/active_support/deep_dup.rb

@@ -0,0 +1,49 @@
+# Backport from Rails 4.x
+# https://github.com/rails/rails/blob/4-0-stable/activesupport/lib/active_support/core_ext/object/deep_dup.rb
+
+require_relative 'duplicable'
+
+class Object
+  # Returns a deep copy of object if it's duplicable. If it's
+  # not duplicable, returns +self+.
+  #
+  #   object = Object.new
+  #   dup    = object.deep_dup
+  #   dup.instance_variable_set(:@a, 1)
+  #
+  #   object.instance_variable_defined?(:@a) #=> false
+  #   dup.instance_variable_defined?(:@a)    #=> true
+  def deep_dup
+    duplicable? ? dup : self
+  end
+end
+
+class Array
+  # Returns a deep copy of array.
+  #
+  #   array = [1, [2, 3]]
+  #   dup   = array.deep_dup
+  #   dup[1][2] = 4
+  #
+  #   array[1][2] #=> nil
+  #   dup[1][2]   #=> 4
+  def deep_dup
+    map(&:deep_dup)
+  end
+end
+
+class Hash
+  # Returns a deep copy of hash.
+  #
+  #   hash = { a: { b: 'b' } }
+  #   dup  = hash.deep_dup
+  #   dup[:a][:c] = 'c'
+  #
+  #   hash[:a][:c] #=> nil
+  #   dup[:a][:c]  #=> "c"
+  def deep_dup
+    each_with_object(dup) do |(key, value), hash|
+      hash[key.deep_dup] = value.deep_dup
+    end
+  end
+end

data/lib/backports/active_support/duplicable.rb

@@ -0,0 +1,88 @@
+# Backport from Rails 4.x
+# https://github.com/rails/rails/blob/4-0-stable/activesupport/lib/active_support/core_ext/object/deep_dup.rb
+
+#--
+# Most objects are cloneable, but not all. For example you can't dup +nil+:
+#
+# nil.dup # => TypeError: can't dup NilClass
+#
+# Classes may signal their instances are not duplicable removing +dup+/+clone+
+# or raising exceptions from them. So, to dup an arbitrary object you normally
+# use an optimistic approach and are ready to catch an exception, say:
+#
+# arbitrary_object.dup rescue object
+#
+# Rails dups objects in a few critical spots where they are not that arbitrary.
+# That rescue is very expensive (like 40 times slower than a predicate), and it
+# is often triggered.
+#
+# That's why we hardcode the following cases and check duplicable? instead of
+# using that rescue idiom.
+#++
+class Object
+  # Can you safely dup this object?
+  #
+  # False for +nil+, +false+, +true+, symbol, and number objects;
+  # true otherwise.
+  def duplicable?
+    true
+  end
+end
+class NilClass
+  # +nil+ is not duplicable:
+  #
+  # nil.duplicable? # => false
+  # nil.dup # => TypeError: can't dup NilClass
+  def duplicable?
+    false
+  end
+end
+class FalseClass
+  # +false+ is not duplicable:
+  #
+  # false.duplicable? # => false
+  # false.dup # => TypeError: can't dup FalseClass
+  def duplicable?
+    false
+  end
+end
+class TrueClass
+  # +true+ is not duplicable:
+  #
+  # true.duplicable? # => false
+  # true.dup # => TypeError: can't dup TrueClass
+  def duplicable?
+    false
+  end
+end
+class Symbol
+  # Symbols are not duplicable:
+  #
+  # :my_symbol.duplicable? # => false
+  # :my_symbol.dup # => TypeError: can't dup Symbol
+  def duplicable?
+    false
+  end
+end
+class Numeric
+  # Numbers are not duplicable:
+  #
+  # 3.duplicable? # => false
+  # 3.dup # => TypeError: can't dup Fixnum
+  def duplicable?
+    false
+  end
+end
+require 'bigdecimal'
+# rubocop:disable Lint/HandleExceptions
+class BigDecimal
+  begin
+    BigDecimal.new('4.56').dup
+    def duplicable?
+      true
+    end
+  rescue TypeError
+    # can't dup, so use superclass implementation
+  end
+end
+# rubocop:enable Lint/HandleExceptions