Refactor and extend coercion and type validation

Addresses #1164, #690, #689, #693.
Depends on solnic/virtus#343

`Grape::ParameterTypes` is renamed `Grape::Validations::Types`
to reflect that it should probably be bundled with an eventual
`grape-validations` gem. It is expanded to include two new
categories of types, 'special' and 'recognized' (see
'lib/grape/validations/types.rb'). `CoerceValidator` now makes
use of `Virtus::Attribute::value_coerced?`, simplifying its
internals.

`CustomTypeCoercer` is introduced, attempting to standardize
support for custom types by decoupling coercion and type-checking
logic from the `type` class supplied to
`Grape::Dsl::Parameters::requires`. The process for inferring
which logic to use for each type and coercion method is encoded
in `lib/grape/validations/types/build_coercer.rb`.

`JSON`, `Array[JSON]` and `Rack::Multipart::UploadedFile (a.k.a
`File`) are designated 'special' types, for which special
implementations of `Virtus::Attribute` are provided.

Instances of `Virtus::Attribute` built with `Virtus::Attribute.build`
may now also be passed as the `type` parameter for `requires`.
A number of pre-rolled attributes are available providing coercion
for `Date` and `DateTime` objects from various formats in
`lib/grape/validations/formats/date.rb` and `date_time.rb`.

CHANGELOG.md

@@ -5,6 +5,7 @@
 
 * Your contribution here.
 
+* [#1167](https://github.com/ruby-grape/grape/pull/1167): Refactor and extend coercion and type validation system - [@dslh](https://github.com/dslh).
 * [#1163](https://github.com/ruby-grape/grape/pull/1163): First-class `JSON` parameter type - [@dslh](https://github.com/dslh).
 * [#1161](https://github.com/ruby-grape/grape/pull/1161): Custom parameter coercion using `coerce_with` - [@dslh](https://github.com/dslh).
 * [#1134](https://github.com/ruby-grape/grape/pull/1134): Adds a code of conduct - [@towanda](https://github.com/towanda).

README.md

@@ -31,6 +31,7 @@
 - [Parameter Validation and Coercion](#parameter-validation-and-coercion)
   - [Supported Parameter Types](#supported-parameter-types)
   - [Custom Types and Coercions](#custom-types-and-coercions)
+  - [Multipart File Parameters](#multipart-file-parameters)
   - [First-Class `JSON` Types](#first-class-json-types)
   - [Validation of Nested Parameters](#validation-of-nested-parameters)
   - [Dependent Parameters](#dependent-parameters)
@@ -732,7 +733,8 @@ The following are all valid types, supported out of the box by Grape:
 * Boolean
 * String
 * Symbol
-* Rack::Multipart::UploadedFile
+* Rack::Multipart::UploadedFile (alias `File`)
+* JSON
 
 ### Custom Types and Coercions
 
@@ -784,6 +786,23 @@ params do
 end
 ```
 
+### Multipart File Parameters
+
+Grape makes use of `Rack::Request`'s built-in support for multipart
+file parameters. Such parameters can be declared with `type: File`:
+
+```ruby
+params do
+  requires :avatar, type: File
+end
+post '/' do
+  # Parameter will be wrapped using Hashie:
+  params.avatar.filename # => 'avatar.png'
+  params.avatar.type     # => 'image/png'
+  params.avatar.tempfile # => #<File>
+end
+```
+
 ### First-Class `JSON` Types
 
 Grape supports complex parameters given as JSON-formatted strings using the special `type: JSON`
@@ -810,9 +829,7 @@ client.get('/', json: '[{"int":4}]') # => HTTP 400
 ```
 
 Additionally `type: Array[JSON]` may be used, which explicitly marks the parameter as an array
-of objects. If a single object is supplied it will be wrapped. For stricter control over the
-type of JSON structure which may be supplied, use `type: Array, coerce_with: JSON` or
-`type: Hash, coerce_with: JSON`.
+of objects. If a single object is supplied it will be wrapped.
 
 ```ruby
 params do
@@ -824,6 +841,8 @@ get '/' do
   params[:json].each { |obj| ... } # always works
 end
 ```
+For stricter control over the type of JSON structure which may be supplied,
+use `type: Array, coerce_with: JSON` or `type: Hash, coerce_with: JSON`.
 
 ### Validation of Nested Parameters
 

lib/grape.rb

@@ -19,10 +19,14 @@
 require 'active_support/notifications'
 require 'multi_json'
 require 'multi_xml'
-require 'virtus'
 require 'i18n'
 require 'thread'
 
+require 'virtus'
+# Patch for Virtus::Attribute::Collection
+# See the file for more details
+require_relative 'virtus/attribute/collection_patch'
+
 I18n.load_path << File.expand_path('../grape/locale/en.yml', __FILE__)
 
 module Grape
@@ -159,7 +163,6 @@ module Presenters
 end
 
 require 'grape/util/content_types'
-require 'grape/util/parameter_types'
 
 require 'grape/validations/validators/base'
 require 'grape/validations/attributes_iterator'
@@ -174,5 +177,6 @@ module Presenters
 require 'grape/validations/validators/values'
 require 'grape/validations/params_scope'
 require 'grape/validations/validators/all_or_none'
+require 'grape/validations/types'
 
 require 'grape/version'

lib/grape/dsl/parameters.rb

@@ -49,7 +49,7 @@ def use(*names)
       #   the :using hash. The last key can be a hash, which specifies
       #   options for the parameters
       # @option attrs :type [Class] the type to coerce this parameter to before
-      #   passing it to the endpoint. See {Grape::ParameterTypes} for a list of
+      #   passing it to the endpoint. See {Grape::Validations::Types} for a list of
       #   types that are supported automatically. Custom classes may be used
       #   where they define a class-level `::parse` method, or in conjunction
       #   with the `:coerce_with` parameter. `JSON` may be supplied to denote

lib/grape/validations/formats.rb

@@ -0,0 +1,14 @@
+require_relative 'formats/dates'
+require_relative 'formats/date_times'
+
+module Grape
+  module Validations
+    # Contains collections of constants that may be passed
+    # as the +type+ parameter of {Grape::Dsl::Parameters#requires}
+    # or {Grape::Dsl::Parameters#optional}, providing
+    # parameter coercion from a range of standard formats
+    # to a number of standard types.
+    module Formats
+    end
+  end
+end

lib/grape/validations/formats/date_times.rb

@@ -0,0 +1,47 @@
+require 'time'
+require_relative '../types/custom_type_coercer'
+
+module Grape
+  module Validations
+    module Formats
+      # This module provides a set of ready-made +Virtus::Attribute+
+      # constants, suitable for use as the +type+ option for
+      # {Grape::Dsl::Parameters#requires} and {Grape::Dsl::Parameters#optional}.
+      # These definitions will coerce input strings to the standard
+      # ruby +DateTime+ type using the standard parsing methods defined
+      # on that class.
+      #
+      # This module is not required by default.
+      module DateTimes
+        # Parses timestamps using +DateTime.httpdate+
+        HttpDate = Types::CustomTypeCoercer.build(::DateTime, ::DateTime.method(:httpdate))
+
+        # Parses timestamps using +DateTime.iso8601+
+        Iso8601 = Types::CustomTypeCoercer.build(::DateTime, ::DateTime.method(:iso8601))
+
+        # Parses timestamps using +DateTime.jisx0301+
+        Jisx0301 = Types::CustomTypeCoercer.build(::DateTime, ::DateTime.method(:jisx0301))
+
+        # Parses julian dates using +DateTime.jd+.
+        # Time of day is not supported.
+        JulianDay = Types::CustomTypeCoercer.build(::DateTime, lambda do |val|
+          fail Grape::Exceptions::Validations, 'julian date must be an integer' unless val =~ /^\d*$/
+
+          ::DateTime.jd val.to_i
+        end)
+
+        # Parses timestamps using +DateTime.rfc2822+
+        Rfc2822 = Types::CustomTypeCoercer.build(::DateTime, ::DateTime.method(:rfc2822))
+
+        # Parses timestamps using +DateTime.rfc3339+
+        Rfc3339 = Types::CustomTypeCoercer.build(::DateTime, ::DateTime.method(:rfc3339))
+
+        # Parses timestamps using +DateTime.rfc822+
+        Rfc822 = Types::CustomTypeCoercer.build(::DateTime, ::DateTime.method(:rfc822))
+
+        # Parses timestamps using +DateTime.xmlschema+
+        XmlSchema = Types::CustomTypeCoercer.build(::DateTime, ::DateTime.method(:xmlschema))
+      end
+    end
+  end
+end

lib/grape/validations/formats/dates.rb

@@ -0,0 +1,46 @@
+require 'date'
+require_relative '../types/custom_type_coercer'
+
+module Grape
+  module Validations
+    module Formats
+      # This module provides a set of ready-made +Virtus::Attribute+
+      # constants, suitable for use as the +type+ option for
+      # {Grape::Dsl::Parameters#requires} and {Grape::Dsl::Parameters#optional}.
+      # These definitions will coerce input strings to the standard
+      # ruby +Date+ type using the standard parsing methods defined
+      # on that class.
+      #
+      # This module is not required by default.
+      module Dates
+        # Parses dates using +Date.httpdate+
+        HttpDate = Types::CustomTypeCoercer.build(::Date, ::Date.method(:httpdate))
+
+        # Parses dates using +Date.iso8601+
+        Iso8601 = Types::CustomTypeCoercer.build(::Date, ::Date.method(:iso8601))
+
+        # Parses dates using +Date.jisx0301+
+        Jisx0301 = Types::CustomTypeCoercer.build(::Date, ::Date.method(:jisx0301))
+
+        # Parses dates using +Date.jd+
+        JulianDay = Types::CustomTypeCoercer.build(::Date, lambda do |val|
+          fail Grape::Exceptions::Validations, 'julian date must be an integer' unless val =~ /^\d*$/
+
+          ::Date.jd val.to_i
+        end)
+
+        # Parses dates using +Date.rfc2822+
+        Rfc2822 = Types::CustomTypeCoercer.build(::Date, ::Date.method(:rfc2822))
+
+        # Parses dates using +Date.rfc3339+
+        Rfc3339 = Types::CustomTypeCoercer.build(::Date, ::Date.method(:rfc3339))
+
+        # Parses dates using +Date.rfc822+
+        Rfc822 = Types::CustomTypeCoercer.build(::Date, ::Date.method(:rfc822))
+
+        # Parses dates using +Date.xmlschema+
+        XmlSchema = Types::CustomTypeCoercer.build(::Date, ::Date.method(:xmlschema))
+      end
+    end
+  end
+end