decanter 0.5.4 → 0.5.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 84d61b3aafe9eeae8726af22da2c9fa239321564
-  data.tar.gz: aa12d102ed3c916f3e6c662502c434f3fb5a7a94
+  metadata.gz: 9ac86e971bab4b5e95eae3ada3b1fe992c6cbc83
+  data.tar.gz: 79a8ec074351d0947a5c28a426c8981c1006bc76
 SHA512:
-  metadata.gz: b5e6756d719f3531fcf28f1cabafda30b41f7f186a83882c406d550ed8897a863af65338f1e652abb9c205bb690cde8676f5395eb3f0fe8892750f5a9e41e8da
-  data.tar.gz: 934e9c5fde54466b13828d40921816bed7f2cd65efc3585d7f8d40fff2762aad0082aff6c9da733464ade29921b830baa90f90b2ff5eba66e99bb002ec6fcb90
+  metadata.gz: 9a99b2791d76756d0d279b123216310e0c230137ac17812934b180dda107cc2950702916442021446a979072b930598b86be19c6f6d0de1486b15683ce2b60a5
+  data.tar.gz: 963650185d1e39baffa089e9115cdd72fe217a5a2378221cbdead7f28d5368970158f706731de6f27efad13eb318d664bb5d67151c2426d6d6ae4a92c643b935

data/.codeclimate.yml

@@ -0,0 +1,38 @@
+engines:
+  rubocop:
+    enabled: true
+    checks:
+      Rubocop/Style/Documentation:
+        enabled: false
+      Rubocop/Metrics/LineLength:
+        enabled: false
+      Rubocop/Rails/Validation:
+        enabled: false
+      Rubocop/Style/IndentationConsistency:
+        enabled: false
+      Rubocop/Style/EmptyLines:
+        enabled: false
+      Rubocop/Style/ClassAndModuleChildren:
+        enabled: false
+      Rubocop/Style/AccessorMethodName:
+        enabled: false
+  golint:
+    enabled: true
+  gofmt:
+    enabled: true
+  eslint:
+    enabled: true
+  csslint:
+    enabled: true
+  brakeman:
+    enabled: true
+  bundler-audit:
+    enabled: true
+ratings:
+   paths:
+   - lib/**
+   - "**.rb"
+exclude_paths:
+- bin/**/*
+- spec/**/*
+- coverage/**/*

data/.gitignore

@@ -0,0 +1,2 @@
+/coverage
+.env

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    decanter (0.5.2)
+    decanter (0.5.4)
       activesupport
 
 GEM
@@ -27,7 +27,11 @@ GEM
       thread_safe (~> 0.3, >= 0.3.4)
       tzinfo (~> 1.1)
     builder (3.2.2)
+    codeclimate-test-reporter (0.4.8)
+      simplecov (>= 0.7.1, < 1.0.0)
     diff-lcs (1.2.5)
+    docile (1.1.5)
+    dotenv (2.1.0)
     erubis (2.7.0)
     i18n (0.7.0)
     json (1.8.3)
@@ -71,6 +75,11 @@ GEM
       rspec-mocks (~> 3.3.0)
       rspec-support (~> 3.3.0)
     rspec-support (3.3.0)
+    simplecov (0.11.2)
+      docile (~> 1.1.0)
+      json (~> 1.8)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
     thor (0.19.1)
     thread_safe (0.3.5)
     tzinfo (1.2.2)
@@ -81,7 +90,9 @@ PLATFORMS
 
 DEPENDENCIES
   bundler (~> 1.9)
+  codeclimate-test-reporter
   decanter!
+  dotenv
   rake (~> 10.0)
   rspec-rails
 

data/README.md

@@ -1,10 +1,17 @@
-ParamsTransformer
+Decanter
 ===
 
-Installation
+[![Code Climate](https://codeclimate.com/github/LaunchPadLab/decanter/badges/gpa.svg)](https://codeclimate.com/github/LaunchPadLab/decanter) [![Test Coverage](https://codeclimate.com/github/LaunchPadLab/decanter/badges/coverage.svg)](https://codeclimate.com/github/LaunchPadLab/decanter/coverage)
 ---
 
-Add Gem:
+
+What is Decanter?
+---
+
+Decanter is a Rails gem that makes it easy to manipulate form data before it hits the model. The basic idea is that form data entered by a user often needs to be processed before it is stored into the database. A typical example of this is a datepicker. A user selects January 15th, 2015 as the date, but this is going to come into our controller as a string like "01/15/2015", so we need to convert this string to a Ruby Date object before it is stored in our database. Many developers perform this conversion right in the controller, which results in errors and unnecessary complexity, especially as the application grows.
+
+Installation
+---
 
 ```ruby
 gem "decanter"
@@ -14,23 +21,31 @@ gem "decanter"
 bundle
 ```
 
+Add the following to application.rb so we can load your decanters properly:
+
+```
+config.paths.add "app/decanter", eager_load: true
+config.to_prepare do
+  Dir[ File.expand_path(Rails.root.join("app/decanter/**/*.rb")) ].each do |file|
+    require_dependency file
+  end
+end
+```
 
 Basic Usage
 ---
 
-Create a class to process your form and have it inherit from ParamsTransformer::Base. I typically create the following folder to hold my form classes: app/classes/forms
+```
+rails g decanter Trip name:string start_date:date end_date:date
+```
 
-**app/classes/forms/property.rb**
+**app/decanter/decanters/trip_decanter.rb**
 
 ```ruby
-class Forms::Property < ParamsTransformer::Base
-
-  input :bedrooms, :integer
-  input :price, :float
-  input :has_air_conditioning, :boolean
-  input :has_parking, :boolean
-  input :has_laundry, :boolean
-
+class TripDecanter < Decanter::Base
+  input :name, :string
+  input :start_date, :date
+  input :end_date, :date
 end
 ```
 
@@ -38,333 +53,294 @@ In your controller:
 
 ```ruby
   def create
-    @form = Forms::Property.new(params)
+    @trip = Trip.decant_new(params[:trip])
 
-    if @form.save
+    if @trip.save
       redirect_to trips_path
     else
-      set_index_variables
-      render "index"
+      render "new"
+    end
+  end
+
+  def update
+    @trip = Trip.find(params[:id])
+    
+    if @trip.decant_update(params[:trip])
+      redirect_to trips_path
+    else
+      render "new"
     end
   end
 ```
 
-Inheritance
+Basic Example
 ---
 
-General pattern:
-
-- forms/property.rb
-- forms/property/create.rb (inherits from forms/property.rb)
-- forms/property/update.rb (inherits from forms/property.rb)
+We have a form where users can create a new Trip, which has the following attributes: name, start_date, and end_date
 
+Without Decanter, here is what our create action may look like:
 
 ```ruby
-# app/classes/forms/property.rb
-class Forms::Property < ParamsTransformer::Base
-
-  input :bedrooms, :integer
-  input :price, :float
-  input :referred_by, :string
+class TripsController < ApplicationController
+  def create
+    @trip = Trip.new(params[:trip])
+    start_date = Date.strptime(params[:trip][:start_date], '%m/%d/%Y')
+    end_date = Date.strptime(params[:trip][:end_date], '%m/%d/%Y')
+    @trip.start_date = start_date
+    @trip.end_date = end_date
 
+    if @trip.save
+      redirect_to trips_path
+    else
+      render 'new'
+    end
+  end
 end
+```
 
+We can see here that converting start_date and end_date to a Ruby date is creating complexity. Could you imagine the complexity involved with performing similar parsing with a nested resource? If you're curious how ugly it would get, we took the liberty of implementing an example here: [Nested Example (Without Decanter)](https://github.com/LaunchPadLab/decanter_demo/blob/master/app/controllers/nested_example/trips_no_decanter_controller.rb)
 
-# app/classes/forms/property/create.rb
-class Forms::Property::Create < Forms::Property
+With Decanter installed, here is what the same controller action would look like:
 
-  # override any input, validation, or method here
+```ruby
+class TripsController < ApplicationController
+  def create
+    @trip = Trip.decant_new(params[:trip])
 
+    if @trip.save
+      redirect_to trips_path
+    else
+      render 'new'
+    end
+  end
 end
 ```
 
-class Forms::Property::Update < Forms::Property
+As you can see, we no longer need to parse the start and end date. Let's take a look at how we accomplished that.
 
-  # override any input, validation, or method here
+From terminal we ran:
 
-end
+```
+rails g decanter Trip name:string start_date:date end_date:date
 ```
 
-Associations
----
-
-Let's say we are creating a web app where teacher's can create Courses with assignments and resources attached to the courses.
+Which generates app/decanter/decanters/trip_decanter.rb:
 
-The modeling would look like:
+```ruby
+class TripDecanter < Decanter::Base
+  input :name, :string
+  input :start_date, :date
+  input :end_date, :date
+end
+```
 
-class Course < ActiveRecord::Base
+You'll also notice that instead of ```@trip = Trip.new(params[:trip])``` we do ```@trip = Trip.decant_new(params[:trip])```. ```decant_new`` is where the magic happens. It is converting the params from this:
 
-  has_many :assignments
-  has_many :resources
+```ruby
+{ 
+  name: "My Trip",
+  start_date: "01/15/2015",
+  end_date: "01/20/2015"
+}
+```
 
-end
+to this:
 
+```ruby
+{ 
+  name: "My Trip",
+  start_date: Mon, 15 Jan 2015,
+  end_date: Mon, 20 Jan 2015
+}
+```
 
+As you can see, the converted params hash has converted start_date and end_date to a Ruby Date object that is ready to be stored in our database.
 
-Why a Library for Parsing Forms?
+Adding Custom Parsers
 ---
 
-In my humble opinion, Rails is missing a tool for parsing forms on the backend. Currently the process looks something like this:
-
-```html
-# new.html.erb
-<%= form_for @trip do |trip_builder| %>
-  <div class="field">
-    <%= trip_builder.label :miles %>
-    <%= trip_builder.text_field :miles, placeholder: '50 miles' %>
-  </div>
-<% end %>
-```
+In the above example, start_date and end_date are ran through a DateParser that lives in Decanter. Let's take a look at the DateParser:
 
 ```ruby
-  # trips_controller
+class DateParser < Decanter::ValueParser::Base
 
-  def create
-    @trip = Trip.new(trip_params)
+  allow Date
 
-    if @trip.save
-      redirect_to trips_path, notice: "New trip successfully created."
-    else
-      render "new"
-    end
+  parser do |name, value, options|
+    parse_format = options.fetch(:parse_format, '%m/%d/%Y')
+    ::Date.strptime(value, parse_format)
   end
+end
 ```
 
-The problem with this approach is that there is nothing that processes the user inputs before being saved into the database. For example, if the user types "1,000 miles" into the form, Rails would store 0 instead of 1000 into our "miles" column.
+```allow Date``` basically tells Decanter that if the value comes in as a Date object, we don't need to parse it at all. Other than that, the parser is really just doing ```Date.strptime("01/15/2015", '%m/%d/%Y')```, which is just a vanilla date parse.
 
-The "Services" concept that many Rails developers favor is on point. Every form should have a corresponding Ruby class whose responsibility is to process the inputs and get the form ready for storage.
-
-However, this "Services" concept does not have a supporting framework. It is repetitive for every developer, for example, to write code to parse a decimal field that comes into our Ruby controller as a string (as in the example above).
-
-Here is how it may be done right now:
+You'll notice that the above ```parser do``` block takes a ```:parse_format``` option. This allows you to specify the format your date string will come in. For example, if you expect "2016-01-15" instead of "01/15/2016", you can adjust the TripDecanter like so:
 
 ```ruby
-class Forms::Trip
-
-  attr_accessor :trip
-
-  def initialize(args = {})
-    @trip = Trip.new
-    @trip.miles = parse_miles(args[:miles)
-  end
-
-  def parse_miles(miles_input)
-    regex = /(\d|[.])/ # only care about numbers and decimals
-    miles_input.scan(regex).join.try(:to_f)
-  end
-
-  def save
-    @trip.save
-  end
+# app/decanter/decanters/trip_decanter.rb
 
+class TripDecanter < Decanter::Base
+  input :name, :string
+  input :start_date, :date, parse_format: '%Y-%m-%d'
+  input :end_date, :date, parse_format: '%Y-%m-%d'
 end
 ```
 
-```ruby
-  # trips_controller.rb
+You can add your own parser if you want more control over the logic, or if you have a peculiar format type we don't support.
 
-  def create
-    form = Forms::Trip.new(trip_params)
-    @trip = form.trip
+```
+rails g parser Date
+```
 
-    if form.save
-      redirect_to trips_path, notice: "New trip successfully created."
-    else
-      render "new"
-    end
+**app/decanter/parsers/date_parser**
+
+```ruby
+class DateParser < Decanter::ValueParser::Base
+  parser do |name, value, options|    
+    # your parsing logic here
   end
+end
 ```
 
-While this process is not so bad with only one field and one model, it gets more complex with many different fields, types of inputs, and especially with nested attributes.
+Nested Example
+---
 
-A better solution is to have the form service classes inherit from a base "form parser" class that can handle the common parsing needs of the community. For example:
+Let's say we have two models in our app: a Trip and a Destination. A trip has many destinations, and is prepared to accept nested attributes from the form.
 
 ```ruby
-class Forms::Trip < FormParse::Base
-
-  input :miles, :float
-
-  def after_init(args)
-    @trip = Trip.new(to_hash)
-  end
+# app/models/trip.rb
 
+class Trip < ActiveRecord::Base
+  has_many :destinations
+  accepts_nested_attributes_for :destinations
 end
 ```
 
 ```ruby
-  # trips_controller.rb
-  # same as above
+# app/models/destination.rb
 
-  def create
-    form = Forms::Trip.new(trip_params)
-    @trip = form.trip
-
-    if form.save
-      redirect_to trips_path, notice: "New trip successfully created."
-    else
-      render "new"
-    end
-  end
+class Destination < ActiveRecord::Base
+  belongs_to :trip
+end
 ```
 
-The FormParse::Base class that Forms::Trip inherits from by default performs the proper regex as seen in the original Forms::Trip service object above. We need only define the input key and the type of input and the base class takes care of the heavy lifting.
+First, let's create our decanters for Trip and Destination. Note: decanters are automatically created whenever you run ```rails g resource```.
 
-The "to_hash" method takes the inputs and converts the parsed values into a hash, which produces the following in this case:
-
-```ruby
-  { miles: 1000.0 }
+```
+rails g decanter Trip name destinations:has_many
+rails g decanter Destination city state arrival_date:date departure_date:date
 ```
 
-A more complex form would end up with a service class like below:
+Which produces app/decanter/decanters/trip and app/decanter/decanters/destination:
 
 ```ruby
-class Forms::Trip
-
-  attr_accessor :trip
-
-  def initialize(args = {})
-    @trip = Trip.new
-    @trip.miles = parse_miles(args[:miles)
-    @trip.origin_city = args[:origin_city]
-    @trip.origin_state = args[:origin_state]
-    @trip.departure_datetime = parse_datetime(args[:departure_datetime])
-    @trip.destination_city = args[:destination_city]
-    @trip.destination_state = args[:destination_state]
-    @trip.arrival_datetime = parse_datetime(args[:arrival_datetime])
-  end
-
-  def parse_miles(miles_input)
-    regex = /(\d|[.])/ # only care about numbers and decimals
-    miles_input.scan(regex).join.try(:to_f)
-  end
-
-  def parse_datetime(datetime_input)
-    Date.strptime(datetime, "%m/%d/%Y")
-  end
-
-  def save
-    @trip.save
-  end
-
+class TripDecanter < Decanter::Base
+  input :name, :string
+  has_many :destinations
 end
 ```
 
-With a framework, it would only involve the following:
-
 ```ruby
-class Forms::Trip < FormParse::Base
-
-  input :miles, :float
-  input :origin_city, :string
-  input :origin_state, :string
-  input :departure_datetime, :datetime
-  input :destination_city, :string
-  input :destination_state, :string
-  input :arrival_datetime, :datetime
-
-  def after_init(args)
-    @trip = Trip.new(to_hash)
-  end
-
-  # to_hash produces:
-  # {
-  #   miles: 1000.0,
-  #   origin_city: "Chicago",
-  #   origin_state: "IL",
-  #   departure_datetime: # DateTime object
-  #   destination_city: "New York",
-  #   destination_state: "NY",
-  #   arrival_datetime: # DateTime object
-  # }
-
+class DestinationDecanter < Decanter::Base
+  input :city, :string
+  input :state, :string
+  input :arrival_date, :date
+  input :departure_date, :date
 end
 ```
 
-Taking it a step further, if our form inputs are not database backed, we can even validate within our new service object like so:
+With that, we can use the same vanilla create action syntax you saw in the basic example above:
 
 ```ruby
-class FormParse::Base
-  include ActiveModel::Model
+class TripsController < ApplicationController
+  def create
+    @trip = Trip.decant_new(params[:trip])
 
-  # ... base parsing code
+    if @trip.save
+      redirect_to trips_path
+    else
+      render 'new'
+    end
+  end
 end
+```
 
-class Form::Trip < FormParse::Base
-
-  input :miles, :float
-  input :origin_city, :string
-  input :origin_city, :string
-  input :destination_city, :string
-  input :destination_state, :string
+Each of the destinations in our params[:trip] are automatically parsed according to the DestinationDecanter inputs set above. This means that ```arrival_date``` and ```departure_date``` are converted to Ruby Date objects for each of the destinations passed through the nested params. Yeehaw!
 
-  validates :miles, :origin_city, :origin_state, :destination_city, :destination_state, presence: true
+Non Database-Backed Objects
+---
 
-  def after_init(args)
-    @trip = Trip.new(to_hash)
-  end
+Decanter will work for you non database-backed objects as well. We just need to call ```decant``` to parse our params according to our decanter logic. 
 
-  def save
-    if valid? && trip.valid?
-      trip.save
-    else
-      return false
-    end
-  end
+Let's say we have a search filtering object called ```SearchFilter```. We start by generating our decanter:
 
-end
 ```
-
-Of course, the save method could be abstracted to our base class too, assuming we define which object the Form::Trip class is saving like so:
+rails g decanter SearchFilter start_date:date end_date:date city:string state:string
+```
 
 ```ruby
-class Form::Trip
+# app/decanter/decanters/search_filter_decanter.rb
 
-  def object
-    trip
-  end
+class SearchFilterDecanter < Decanter::Base
 
-  # ... above code here
 end
+```
 
-class FormParse::Base
+```ruby
+# app/controllers/search_controller.rb
 
-  def save
-    if valid? && object.valid?
-      object.save
-    else
-      return false
-    end
-  end
+def search
+  decanted_params = SearchFilterDecanter.decant(params[:search])
+  # decanted_params is now parsed according to the parsers defined
+  # in SearchFilterDecanter
 end
-
 ```
 
-But where we really can see benefits from a "framework" for parsing our Rails forms is when we start to use nested attributes. For example, if we abstract the origin and destination fields to a "Location" model, we could build out a separate service class to handle parsing our "Location" form (even if it is in the context of a parent object like Trip).
+Default Parsers
+---
 
-```ruby
-class Forms::Location < FormParse::Base
+Decanter comes with the following parsers:
+- boolean
+- date
+- datetime
+- float
+- integer
+- phone
+- string
 
-  input :city, :string
-  input :state, :string
-  input :departure_datetime, :datetime
-  input :arrival_datetime, :datetime
+As an example as to how these parsers differ, let's consider ```float```. The float parser will perform a regex to find only characters that are digits or decimals. By doing that, your users can enter in commas and currency symbols without your backend throwing a hissy fit.
 
-  validates :city, :state :presence => true
+We encourage you to create your own parsers for other needs in your app, or generate one of the above listed parsers to override its behavior.
 
-end
+```
+rails g parser Zip
+```
 
-class Forms::Trip < FormParse::Base
+Squashing Inputs
+---
 
-  input :miles, :float
-  input :origin_attributes, :belongs_to, class: 'location'
-  input :destination_attributes, :belongs_to, class: 'location'
+Sometimes, you may want to take several inputs and combine them into one finished input prior to sending to your model. For example, if day, month, and year come in as separate parameters, but your database really only cares about start_date. 
 
-  validates :miles, presence: true
+```ruby
+class TripDecanter < Decanter::Base
+  input [:day, :month, :year], :squash_date, key: :start_date  
+end
+```
 
-  def after_init(args)
-    @trip = Trip.new(to_hash)
+```
+rails g parser SquashDate
+```
+
+```ruby
+# app/decanter/squashers/date_squasher.rb
+
+class SquashDateParser < Decanter::Parser::Base
+  parser do |name, values, options|    
+    day = values[0]
+    month = values[1]
+    year = values[2]
+    Date.new(year, month, day)
   end
 end
 ```
-
-The FormParse::Base class will recoginze the :belongs_to relationship and utilize the Location service class to parse the part of the params hash that correspond with our destination and origin models. This is great because if there is anywhere that the user can update just the origin or destination of the trip, we could just reuse that Location service object to parse the form.

data/decanter.gemspec

@@ -6,7 +6,7 @@ require 'decanter/version'
 Gem::Specification.new do |spec|
   spec.name          = "decanter"
   spec.version       = Decanter::VERSION
-  spec.authors       = ["Ryan Francis", "Dave Corwin"]
+  spec.authors       = ["Ryan Francis", "David Corwin"]
   spec.email         = ["ryan@launchpadlab.com"]
 
   spec.summary       = %q{Form Parser for Rails}
@@ -32,4 +32,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.9"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec-rails"
+  spec.add_development_dependency "codeclimate-test-reporter"
+  spec.add_development_dependency "dotenv"
 end

data/lib/decanter/core.rb

@@ -7,101 +7,125 @@ module Decanter
 
     module ClassMethods
 
-      def associations
-        @associations ||= {}.with_indifferent_access
-      end
+      def input(name, parser=nil, **options)
 
-      def inputs
-        @inputs ||= {}.with_indifferent_access
-      end
+        _name = [name].flatten
 
-      def input(name=nil, type, **options)
-        set_input options, {
-          name:    name,
-          options: options.reject { |k| k == :context },
-          type:    type
-        }
-      end
-
-      def set_input(options, input_cfg)
-        set_for_context options, input_cfg, inputs
-      end
+        if _name.length > 1 && parser.blank?
+          raise ArgumentError.new("#{self.name} no parser specified for input with multiple values.")
+        end
 
-      def input_for(name, context)
-        (inputs[context || :default] || {})[name]
+        handlers[_name] = {
+          key:     options.fetch(:key, _name.first),
+          name:    _name,
+          options: options,
+          parser:  parser,
+          type:    :input
+        }
       end
 
-      def has_many(name=nil, **options)
-        set_association options, {
-          key:     options[:key] || "#{name}_attributes".to_sym,
+      def has_many(assoc, **options)
+        name = ["#{assoc}_attributes".to_sym]
+        handlers[name] = {
+          assoc:   assoc,
+          key:     options.fetch(:key, name.first),
           name:    name,
-          options: options.reject { |k| k == :context },
+          options: options,
           type:    :has_many
         }
       end
 
-      def has_one(name=nil, **options)
-        set_association options, {
-          key:     options[:key] || "#{name}_attributes".to_sym,
+      def has_one(assoc, **options)
+        name = ["#{assoc}_attributes".to_sym]
+        handlers[name] = {
+          assoc:   assoc,
+          key:     options.fetch(:key, name.first),
           name:    name,
-          options: options.reject { |k| k == :context },
+          options: options,
           type:    :has_one
         }
       end
 
-      def has_many_for(key, context)
-        (associations[context || :default] || {})
-          .detect { |name, assoc| assoc[:type] == :has_many && assoc[:key] == key.to_sym}
+      def strict(mode)
+        raise( ArgumentError.new("#{self.name}: Unknown strict value #{mode}")) unless [:with_exception, true, false].include? mode
+        @strict_mode = mode
       end
 
-      def has_one_for(key, context)
-        (associations[context || :default] || {})
-          .detect { |name, assoc| assoc[:type] == :has_one && assoc[:key] == key.to_sym}
+      def decant(args)
+        args = args.to_unsafe_h if args.class.name == 'ActionController::Parameters'
+        {}.merge( unhandled_keys(args) )
+          .merge( handled_keys(args) )
       end
 
-      def set_association(options, assoc)
-        set_for_context options, assoc, associations
-      end
+      # protected
+
+        def unhandled_keys(args)
+
+          unhandled_keys = args.keys - handlers.keys.flatten.uniq
+
+          if unhandled_keys.any?
+            case strict_mode
+            when true
+              p "#{self.name} ignoring unhandled keys: #{unhandled_keys.join(', ')}."
+              {}
+            when :with_exception
+              raise ArgumentError.new("#{self.name} received unhandled keys: #{unhandled_keys.join(', ')}.")
+            else
+              args.select { |key| unhandled_keys.include? key }
+            end
+          else
+            {}
+          end
+        end
 
-      def set_for_context(options, arg, hash)
-        context = options[:context] || @context || :default
-        hash[context] = {} unless hash.has_key? context
-        hash[context][arg[:name]] = arg
-      end
+        def handled_keys(args)
+          handlers.values
+                  .select     { |handler| (args.keys.map(&:to_sym) & handler[:name]).any? }
+                  .reduce({}) { |memo, handler| memo.merge handle(handler, args) }
+        end
 
-      def with_context(context, &block)
-        raise NameError.new('no context argument provided to with_context') unless context
+        def handle(handler, args)
+          values = args.values_at(*handler[:name])
+          values = values.length == 1 ? values.first : values
+          self.send("handle_#{handler[:type]}", handler, values)
+        end
 
-        @context = context
-        block.arity.zero? ? instance_eval(&block) : block.call(self)
-        @context = nil
-      end
+        def handle_input(handler, values)
+           parse(handler[:key], handler[:parser], values, handler[:options])
+        end
 
-      def decant(args={}, context=nil)
-        Hash[
-          args.keys.map { |key| handle_arg(key, args[key], context) }.compact
-        ]
-      end
+        def handle_has_many(handler, values)
+            decanter = decanter_for_handler(handler)
+            {
+              handler[:key] => values.compact.map { |value| decanter.decant(value) }
+            }
+        end
 
-      def handle_arg(name, value, context)
-        case
-        when input_cfg = input_for(name, context)
-          [name, parse(name, input_cfg[:type], value, input_cfg[:options])]
-        when assoc = has_one_for(name, context)
-          [assoc.pop[:key], Decanter::decanter_for(assoc[1][:options][:decanter] || assoc.first).decant(value, context)]
-        when assoc = has_many_for(name, context)
-          decanter = Decanter::decanter_for(assoc[1][:options][:decanter] || assoc.first)
-          [assoc.pop[:key], value.map { |val| decanter.decant(val, context) }]
-        else
-          context ? nil : [name, value]
+        def handle_has_one(handler, values)
+            {
+              handler[:key] => decanter_for_handler(handler).decant(values)
+            }
         end
-      end
 
-      def parse(name, type, val, options)
-        type ?
-          ValueParser.value_parser_for(type).parse(name, val, options) :
-          val
-      end
+        def decanter_for_handler(handler)
+          Decanter::decanter_for(handler[:options][:decanter] || handler[:assoc])
+        end
+
+        def parse(key, parser, values, options)
+          parser ?
+            ValueParser.value_parser_for(parser)
+                       .parse(key, values, options)
+            :
+            { key => values }
+        end
+
+        def handlers
+          @handlers ||= {}
+        end
+
+        def strict_mode
+          @strict_mode ||= {}
+        end
     end
   end
 end

data/lib/decanter/extensions.rb

@@ -5,32 +5,35 @@ module Decanter
       base.extend(ClassMethods)
     end
 
-    def decant_update(args={}, context=nil)
-      self.attributes = self.class.decant(args, context)
-      self.save(context: context)
+    def decant_update(args, **options)
+      self.attributes = self.class.decant(args, options)
+      self.save(context: options[:context])
     end
 
-    def decant_update!(args={}, context=nil)
-      self.attributes = self.class.decant(args, context)
-      self.save!(context: context)
+    def decant_update!(args, **options)
+      self.attributes = self.class.decant(args, options)
+      self.save!(context: options[:context])
     end
 
     module ClassMethods
 
-      def decant_create(args={}, context=nil)
-        self.new(decant(args, context)).save(context: context)
+      def decant_create(args, **options)
+        self.new(decant(args, options))
+            .save(context: options[:context])
       end
 
-      def decant_new(args={}, context=nil)
-        self.new(decant(args, context))
+      def decant_new(args, **options)
+        self.new(decant(args, options))
       end
 
-      def decant_create!(args={}, context=nil)
-        self.new(decant(args, context)).save!(context: context)
+      def decant_create!(args, **options)
+        self.new(decant(args, options))
+            .save!(context: options[:context])
       end
 
-      def decant(args, context)
-        Decanter.decanter_for(self).decant(args, context)
+      def decant(args, options)
+        options.fetch(:decanter, Decanter.decanter_for(self))
+          .decant(args)
       end
     end
   end

data/lib/decanter/railtie.rb

@@ -6,4 +6,10 @@ class Decanter::Railtie < Rails::Railtie
   initializer 'decanter.configure' do
     ActiveRecord::Base.include(Decanter::Extensions) if defined? ActiveRecord
   end
+
+  generators do |app|
+    Rails::Generators.configure!(app.config.generators)
+    Rails::Generators.hidden_namespaces.uniq!
+    require 'generators/rails/resource_override'
+  end
 end

data/lib/decanter/value_parser.rb

@@ -7,7 +7,6 @@ module Decanter
     end
 
     def self.value_parser_for(sym)
-      p "find parser for #{sym}"
       @@value_parsers["#{sym.to_s.camelize}Parser"] || (raise NameError.new("unknown value parser #{sym.to_s.capitalize}Parser"))
     end
   end
@@ -22,3 +21,5 @@ require_relative 'value_parser/string_parser'
 require_relative 'value_parser/phone_parser'
 require_relative 'value_parser/float_parser'
 require_relative 'value_parser/integer_parser'
+require_relative 'value_parser/key_value_splitter_parser'
+require_relative 'value_parser/join_parser'

data/lib/decanter/value_parser/core.rb

@@ -4,30 +4,42 @@ module Decanter
 
       def self.included(base)
         base.extend(ClassMethods)
-        ValueParser.register(base)
       end
 
       module ClassMethods
 
-        def parse(name, val=nil, options={})
+        def parse(name, values, options={})
 
-          if val.blank?
+          value_ary = values.is_a?(Array) ? values : [values]
+
+          # want to treat 'false' as an actual value
+          if value_ary.all? { |value| value.nil? || value == "" }
             if options[:required]
               raise ArgumentError.new("No value for required argument: #{name}")
             else
-              return val
+              return { name => nil }
             end
           end
 
-          if @allowed && @allowed.include?(val.class)
-            return val
+          if @allowed && value_ary.all? { |value| @allowed.include?(value.class) }
+            return { name => values }
           end
 
           unless @parser
-            raise ArgumentError.new("No parser for argument: #{name} with type: #{val.class}")
+            raise ArgumentError.new("No parser for argument: #{name} with types: #{value_ary.map(&:class).join(', ')}")
           end
 
-          @parser.call(name, val, options)
+          case @result
+          when :raw
+            # Parser result must be a hash
+            parsed = @parser.call(name, values, options)
+            parsed.is_a?(Hash) ?
+              parsed :
+              raise(ArgumentError.new("Result of parser #{self.name} with values #{values} was #{parsed} when it must be a hash."))
+          else
+            # Parser result will be treated as a single value belonging to the name
+            { name => @parser.call(name, values, options) }
+          end
         end
 
         def parser(&block)
@@ -37,6 +49,10 @@ module Decanter
         def allow(*args)
           @allowed = args
         end
+
+        def result(opt)
+          @result = opt
+        end
       end
     end
   end

data/lib/decanter/value_parser/join_parser.rb

@@ -0,0 +1,13 @@
+module Decanter
+  module ValueParser
+    class JoinParser < Base
+      DELIM = ','
+
+      parser do |name, val, options|
+        delimiter = options.fetch(:delimiter, ITEM_DELIM)
+        val.join(DELIM)
+      end
+    end
+  end
+end
+

data/lib/decanter/value_parser/key_value_splitter_parser.rb

@@ -0,0 +1,17 @@
+module Decanter
+  module ValueParser
+    class KeyValueSplitterParser < Base
+      ITEM_DELIM = ','
+      PAIR_DELIM = ':'
+
+      result :raw
+
+      parser do |name, val, options|
+        item_delimiter = options.fetch(:item_delimiter, ITEM_DELIM)
+        pair_delimiter = options.fetch(:pair_delimiter, PAIR_DELIM)
+        val.split(item_delimiter).reduce({}) { |memo, pair| memo.merge( Hash[ *pair.split(pair_delimiter) ] ) }
+      end
+    end
+  end
+end
+

data/lib/decanter/version.rb

@@ -1,3 +1,3 @@
 module Decanter
-  VERSION = '0.5.4'
+  VERSION = '0.5.5'
 end

data/lib/generators/rails/decanter_generator.rb

@@ -0,0 +1,31 @@
+module Rails
+  module Generators
+    class DecanterGenerator < NamedBase
+      source_root File.expand_path('../templates', __FILE__)
+      check_class_collision :suffix => 'Decanter'
+      ASSOCIATION_TYPES = [:has_many, :has_one, :belongs_to]
+
+      argument :attributes, :type => :array, :default => [], :banner => 'field:type field:type'
+
+      class_option :parent, :type => :string, :desc => 'The parent class for the generated decanter'
+
+      def create_decanter_file
+        template 'decanter.rb.erb', File.join('app/decanter/decanters', class_path, "#{file_name}_decanter.rb")
+      end
+
+      private
+
+      def inputs
+        attributes.find_all { |attr| ASSOCIATION_TYPES.exclude?(attr.type) }
+      end
+
+      def associations
+        attributes - inputs
+      end
+
+      def parent_class_name
+        'Decanter::Base'
+      end
+    end
+  end
+end

data/lib/generators/rails/parser_generator.rb

@@ -0,0 +1,20 @@
+module Rails
+  module Generators
+    class ParserGenerator < NamedBase
+      source_root File.expand_path('../templates', __FILE__)
+      check_class_collision :suffix => 'Parser'
+
+      class_option :parent, :type => :string, :desc => 'The parent class for the generated parser'
+
+      def create_parser_file
+        template 'parser.rb.erb', File.join('app/decanter/parsers', class_path, "#{file_name}_parser.rb")
+      end
+
+      private
+
+      def parent_class_name
+        'Decanter::ValueParser::Base'
+      end
+    end
+  end
+end

data/lib/generators/rails/resource_override.rb

@@ -0,0 +1,10 @@
+require 'rails/generators'
+require 'rails/generators/rails/resource/resource_generator'
+
+module Rails
+  module Generators
+    class ResourceGenerator
+      hook_for :decanter, default: true, boolean: true
+    end
+  end
+end

data/lib/generators/rails/templates/decanter.rb.erb

@@ -0,0 +1,10 @@
+<% module_namespacing do -%>
+class <%= class_name %>Decanter < <%= parent_class_name %>
+<% inputs.each do |input| -%>
+  input :<%= input.name %>, :<%= input.type %>
+<% end -%>
+<% associations.each do |assoc| -%>
+  <%= assoc.type %> :<%= assoc.name %>
+<% end -%>
+end
+<% end -%>

data/lib/generators/rails/templates/parser.rb.erb

@@ -0,0 +1,7 @@
+<% module_namespacing do -%>
+class <%= class_name %>Parser < <%= parent_class_name %>
+  parser do |name, value, options|
+    value
+  end
+end
+<% end -%>

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: decanter
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 0.5.5
 platform: ruby
 authors:
 - Ryan Francis
-- Dave Corwin
+- David Corwin
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-02-15 00:00:00.000000000 Z
+date: 2016-02-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -67,6 +67,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: codeclimate-test-reporter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Decanter aims to reduce complexity in Rails controllers by creating a
   place for transforming data before it hits the model and database.
 email:
@@ -75,6 +103,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".codeclimate.yml"
+- ".gitignore"
 - ".rspec"
 - Gemfile
 - Gemfile.lock
@@ -98,9 +128,16 @@ files:
 - lib/decanter/value_parser/datetime_parser.rb
 - lib/decanter/value_parser/float_parser.rb
 - lib/decanter/value_parser/integer_parser.rb
+- lib/decanter/value_parser/join_parser.rb
+- lib/decanter/value_parser/key_value_splitter_parser.rb
 - lib/decanter/value_parser/phone_parser.rb
 - lib/decanter/value_parser/string_parser.rb
 - lib/decanter/version.rb
+- lib/generators/rails/decanter_generator.rb
+- lib/generators/rails/parser_generator.rb
+- lib/generators/rails/resource_override.rb
+- lib/generators/rails/templates/decanter.rb.erb
+- lib/generators/rails/templates/parser.rb.erb
 homepage: https://github.com/launchpadlab/decanter
 licenses:
 - MIT