Support custom types

CHANGELOG.md

@@ -3,7 +3,8 @@ Next Release
 
 #### Features
 
-* Your contribution here.
+* [#1039](https://github.com/intridea/grape/pull/1039): Added support for custom parameter types - [@rnubel](https://github.com/rnubel).
+* Your contribution here!
 
 #### Fixes
 

README.md

@@ -29,6 +29,8 @@
   - [Declared](#declared)
   - [Include Missing](#include-missing)
 - [Parameter Validation and Coercion](#parameter-validation-and-coercion)
+  - [Supported Parameter Types](#supported-parameter-types)
+  - [Custom Types](#custom-types)
   - [Built-in Validators](#built-in-validators)
   - [Namespace Validation and Coercion](#namespace-validation-and-coercion)
   - [Custom Validators](#custom-validators)
@@ -730,6 +732,54 @@ params do
 end
 ```
 
+#### Supported Parameter Types
+
+The following are all valid types, supported out of the box by Grape:
+
+* Integer
+* Float
+* BigDecimal
+* Numeric
+* Date
+* DateTime
+* Time
+* Boolean
+* String
+* Symbol
+* Rack::Multipart::UploadedFile
+
+#### Custom Types
+
+Aside from the default set of supported types listed above, any class can be
+used as a type so long as it defines a class-level `parse` method. This method
+must take one string argument and return an instance of the correct type, or
+raise an exception to indicate the value was invalid. E.g.,
+
+```ruby
+class Color
+  attr_reader :value
+  def initialize(color)
+    @value = color
+  end
+
+  def self.parse(value)
+    fail 'Invalid color' unless %w(blue red green).include?(value)
+    new(value)
+  end
+end
+
+# ...
+
+params do
+  requires :color, type: Color, default: Color.new('blue')
+end
+
+get '/stuff' do
+  # params[:color] is already a Color.
+  params[:color].value
+end
+```
+
 #### Validation of Nested Parameters
 
 Parameters can be nested using `group` or by calling `requires` or `optional` with a block.

lib/grape.rb

@@ -22,7 +22,6 @@
 require 'active_support/core_ext/array/extract_options'
 require 'active_support/core_ext/hash/deep_merge'
 require 'active_support/dependencies/autoload'
-require 'grape/util/content_types'
 require 'multi_json'
 require 'multi_xml'
 require 'virtus'
@@ -160,6 +159,9 @@ module Presenters
   end
 end
 
+require 'grape/util/content_types'
+require 'grape/util/parameter_types'
+
 require 'grape/validations/validators/base'
 require 'grape/validations/attributes_iterator'
 require 'grape/validations/validators/allow_blank'

lib/grape/util/parameter_types.rb

@@ -0,0 +1,58 @@
+module Grape
+  module ParameterTypes
+    # Types representing a single value, which are coerced through Virtus
+    # or special logic in Grape.
+    PRIMITIVES = [
+      # Numerical
+      Integer,
+      Float,
+      BigDecimal,
+      Numeric,
+
+      # Date/time
+      Date,
+      DateTime,
+      Time,
+
+      # Misc
+      Virtus::Attribute::Boolean,
+      String,
+      Symbol,
+      Rack::Multipart::UploadedFile
+    ]
+
+    # Types representing data structures.
+    STRUCTURES = [
+      Hash,
+      Array,
+      Set
+    ]
+
+    # @param type [Class] type to check
+    # @returns [Boolean] whether or not the type is known by Grape as a valid
+    #   type for a single value
+    def self.primitive?(type)
+      PRIMITIVES.include?(type)
+    end
+
+    # @param type [Class] type to check
+    # @returns [Boolean] whether or not the type is known by Grape as a valid
+    #   data structure type
+    # @note This method does not yet consider 'complex types', which inherit
+    #   Virtus.model.
+    def self.structure?(type)
+      STRUCTURES.include?(type)
+    end
+
+    # A valid custom type must implement a class-level `parse` method, taking
+    #   one String argument and returning the parsed value in its correct type.
+    # @param type [Class] type to check
+    # @returns [Boolean] whether or not the type can be used as a custom type
+    def self.custom_type?(type)
+      !primitive?(type) &&
+        !structure?(type) &&
+        type.respond_to?(:parse) &&
+        type.method(:parse).arity == 1
+    end
+  end
+end

lib/grape/validations/validators/coerce.rb

@@ -56,7 +56,14 @@ def coerce_value(type, val)
         return val || Set.new if type == Set
         return val || {}      if type == Hash
 
-        converter = Virtus::Attribute.build(type)
+        # To support custom types that Virtus can't easily coerce, pass in an
+        # explicit coercer. Custom types must implement a `parse` class method.
+        converter_options = {}
+        if ParameterTypes.custom_type?(type)
+          converter_options[:coercer] = type.method(:parse)
+        end
+
+        converter = Virtus::Attribute.build(type, converter_options)
         converter.coerce(val)
 
       # not the prettiest but some invalid coercion can currently trigger

spec/grape/util/parameter_types_spec.rb

@@ -0,0 +1,54 @@
+require 'spec_helper'
+
+describe Grape::ParameterTypes do
+  class FooType
+    def self.parse(_)
+    end
+  end
+
+  class BarType
+    def self.parse
+    end
+  end
+
+  describe '::primitive?' do
+    [
+      Integer, Float, Numeric, BigDecimal,
+      Virtus::Attribute::Boolean, String, Symbol,
+      Date, DateTime, Time, Rack::Multipart::UploadedFile
+    ].each do |type|
+      it "recognizes #{type} as a primitive" do
+        expect(described_class.primitive?(type)).to be_truthy
+      end
+    end
+
+    it 'identifies unknown types' do
+      expect(described_class.primitive?(Object)).to be_falsy
+      expect(described_class.primitive?(FooType)).to be_falsy
+    end
+  end
+
+  describe '::structure?' do
+    [
+      Hash, Array, Set
+    ].each do |type|
+      it "recognizes #{type} as a structure" do
+        expect(described_class.structure?(type)).to be_truthy
+      end
+    end
+  end
+
+  describe '::custom_type?' do
+    it 'returns false if the type does not respond to :parse' do
+      expect(described_class.custom_type?(Object)).to be_falsy
+    end
+
+    it 'returns true if the type responds to :parse with one argument' do
+      expect(described_class.custom_type?(FooType)).to be_truthy
+    end
+
+    it 'returns false if the type\'s #parse method takes other than one argument' do
+      expect(described_class.custom_type?(BarType)).to be_falsy
+    end
+  end
+end

spec/grape/validations/params_scope_spec.rb

@@ -89,6 +89,35 @@ def app
     end
   end
 
+  context 'when using custom types' do
+    class CustomType
+      attr_reader :value
+      def self.parse(value)
+        fail if value == 'invalid'
+        new(value)
+      end
+
+      def initialize(value)
+        @value = value
+      end
+    end
+
+    it 'coerces the parameter via the type\'s parse method' do
+      subject.params do
+        requires :foo, type: CustomType
+      end
+      subject.get('/types') { params[:foo].value }
+
+      get '/types', foo: 'valid'
+      expect(last_response.status).to eq(200)
+      expect(last_response.body).to eq('valid')
+
+      get '/types', foo: 'invalid'
+      expect(last_response.status).to eq(400)
+      expect(last_response.body).to match(/foo is invalid/)
+    end
+  end
+
   context 'array without coerce type explicitly given' do
     it 'sets the type based on first element' do
       subject.params do