simple_params 0.0.1pre2

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NzljZWZmNDczMjI4ZDk5ZDg2NmYxNzRlNzQ5ZjhjNDU4YjJhMmVjNw==
+  data.tar.gz: !binary |-
+    ZWQ0MGE5MjE4NmQ4MDUxYzMxNmUwMjM4ZWU4NDk0YWQyYTJkNWZmNw==
+SHA512:
+  metadata.gz: !binary |-
+    ODJkOTE3YzRjNTUzOGQ3ZGE0MDFlYzg5Mzc3YzNjMmI4NDJlZTA4OGZlYzkw
+    MDkzZDlmMmNkZjY1YmZlNjc0OGJhZTk2MGJiNTEwMjc0NDcyZWFmNzJiMmZi
+    MjVlNzFjZTU0NWY0NGY5ODg5M2RmYmQ0MTQ0ZjNhMTgzMTQ3ZjU=
+  data.tar.gz: !binary |-
+    NDhlYzBmNDhlOGYzYjIyNzY2NDQ2ZmViNmFmOTA2YzQ1NmViNGJlOTEwOTg1
+    OTc4ODg2NDlmYzRkZGRlY2M4NTdjYTBhZjE0NWMzMWRmNTgwZWRmNjI5ZGY5
+    ZjFkY2I1MzliODY4Y2Q2N2I5ODVmYWM5ZDBmNDc4MzRiOWY2OTQ=

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.ruby-gemset

@@ -0,0 +1 @@
+simple_params_gem

data/.ruby-version

@@ -0,0 +1 @@
+ruby-1.9.3-p545

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,60 @@
+PATH
+  remote: .
+  specs:
+    simple_params (0.0.1pre)
+      activemodel (>= 3.0, < 5.0)
+      virtus (>= 1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (4.2.0)
+      activesupport (= 4.2.0)
+      builder (~> 3.1)
+    activesupport (4.2.0)
+      i18n (~> 0.7)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
+    axiom-types (0.1.1)
+      descendants_tracker (~> 0.0.4)
+      ice_nine (~> 0.11.0)
+      thread_safe (~> 0.3, >= 0.3.1)
+    builder (3.2.2)
+    coercible (1.0.0)
+      descendants_tracker (~> 0.0.1)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
+    diff-lcs (1.2.5)
+    equalizer (0.0.9)
+    i18n (0.7.0)
+    ice_nine (0.11.1)
+    json (1.8.2)
+    minitest (5.5.1)
+    rake (10.4.2)
+    rspec (2.99.0)
+      rspec-core (~> 2.99.0)
+      rspec-expectations (~> 2.99.0)
+      rspec-mocks (~> 2.99.0)
+    rspec-core (2.99.2)
+    rspec-expectations (2.99.2)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.99.3)
+    thread_safe (0.3.4)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+    virtus (1.0.4)
+      axiom-types (~> 0.1)
+      coercible (~> 1.0)
+      descendants_tracker (~> 0.0, >= 0.0.3)
+      equalizer (~> 0.0, >= 0.0.9)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.5)
+  rake (~> 10.1)
+  rspec (~> 2.6)
+  simple_params!

data/README.md

@@ -0,0 +1,161 @@
+# Simple Params
+
+A simple class to handle parameter validation, for use in APIs or Service Objects.  Simply pass in your JSON hash, and get a simple, validateable, accessible ActiveModel-like object.
+
+This class provides the following benefits for handling params:
+  * Access via array-like (params[:person][:name]), or struct-like (params.person.name) syntax
+  * Ability to validate with any ActiveModel validation
+  * ActiveModel-like errors, including nested error objects for nested params
+  * Parameter type-coercion (e.g. transform "1" into the Integer 1)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'simple_params', '~> 0.0.1pre'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install simple_params
+
+## Defining your Params class
+
+All you need to do is create a class to specify accepted parameters and validations
+
+```ruby
+class MyParams < SimpleParams::Params
+  param :name
+  param :age, type: Integer
+  param :date_of_birth, type: Date, optional: true
+  param :hair_color, default: "brown", validations: { inclusion: { in: ["brown", "red", "blonde", "white"] }}
+
+  nested_hash :address do
+    param :street
+    param :city
+    param :zip_code, validations: { length: { in: 5..9 } }
+    param :state, optional: true
+    param :country, default: "USA"
+  end
+
+  # You can include whatever custom methods you need as well
+  def full_address
+    [address.street, address.city, address.state, address.zip_code].join(" ")
+  end
+end
+```
+We can now treat these params in very ActiveModel-like ways.  For example:
+
+```ruby
+params = MyParams.new(
+  {
+    name: "Bob Barker",
+    age: "91",
+    date_of_birth: "December 12th, 1923",
+    hair_color: "white",
+    address: {
+      street: "7800 Beverly Blvd",
+      city: "Los Angeles",
+      state: "California",
+      zip_code: "90036"
+    }
+  }
+)
+
+params.valid? #=> true
+params.name #=> "Bob Barker"
+params.full_address #=> "7800 Beverly Blvd Los Angeles California 90036"
+```
+
+## Validation & Errors
+
+Errors are also treated in a very ActiveModel-like way, making it simple to validate even complexly nested inputs.
+
+```ruby
+params = MyParams.new(
+  {
+    name: "",
+    age: "91",
+    address: {
+      city: "Los Angeles",
+      state: "California",
+      zip_code: "90036"
+    }
+  }
+)
+
+params.valid? #=> false
+params.errors[:name] #=> ["can't be blank"] 
+params.errors[:address][:street] #=> ["can't be blank"] 
+params.address.errors[:street] #=> ["can't be blank"] 
+
+params.errors.as_json #=> {:name=>["can't be blank"], :address=>{:street=>["can't be blank"]}} 
+params.address.errors.as_json #=> {:street=>["can't be blank"]}  
+```
+
+## Defaults
+
+It is easy to set simple or complex defaults, with either a static value or a Proc
+
+```ruby
+class DefaultParams < SimpleParams::Params
+  param :name, default: "Doc Brown"
+  param :first_initial, default: lambda { |params, attribute| params.name[0] }
+
+  nested_hash :car do
+    param :make, default: "DeLorean"
+    param :license_plate, default: lambda { |params, attribute| params.make[0..2].upcase + "-1234" }
+  end
+end
+
+params = DefaultParams.new
+
+params.name #=> "Doc Brown"
+params.first_initial #=> "D"
+params.car.make #=> "DeLorean"
+params.car.license_plate #=> "DEL-1234"
+```
+
+# Coercion
+
+SimpleParams provides support for converting incoming params from one type to another.  This is extremely helpful for integers, dates, floats, and booleans, which will often come in as strings but should not be treated as such.
+
+By default, params are assumed to be strings, so there is no need to specify String as a type.
+
+```ruby
+class CoercionParams < SimpleParams::Params
+  param :name
+  param :age, type: Integer
+  param :date_of_birth, type: Date
+  param :pocket_change, type: BigDecimal
+end
+
+params = CoercionParams.new(name: "Bob", age: "21", date_of_birth: "June 1st, 1980", pocket_change: "2.35")
+
+params.name #=> "Bob"
+params.age #=> 21
+params.date_of_birth #=> #<Date: 1980-06-01>
+params.pocket_change #=> #<BigDecimal:89ed240,'0.235E1',18(18)> 
+```
+
+SimpleParams also provide helper methods for implicitly specifying the type, if you prefer that syntax.  Here is the same class as above, but redefined with these helper methods.
+
+```ruby
+class CoercionParams < SimpleParams::Params
+  param :name
+  integer_param :age
+  date_param :date_of_birth
+  decimal_param :pocket_change
+end
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/lib/simple_params/errors.rb

@@ -0,0 +1,133 @@
+require "active_model"
+
+module SimpleParams
+  class Errors < ActiveModel::Errors
+
+    def initialize(base, nested_attributes = [])
+      super(base)
+      @nested_attributes = symbolize_nested(nested_attributes)
+    end
+
+    def [](attribute)
+      get(attribute.to_sym) || reset_attribute(attribute.to_sym)
+    end
+
+    def []=(attribute, error)
+      add_error_to_attribute(attribute, error)
+    end
+
+    def add(attribute, message = :invalid, options = {})
+      message = normalize_message(attribute, message, options)
+      if exception = options[:strict]
+        exception = ActiveModel::StrictValidationFailed if exception == true
+        raise exception, full_message(attribute, message)
+      end
+
+      add_error_to_attribute(attribute, message)
+    end
+
+    def clear
+      super
+      @nested_attributes.each do |attribute|
+        if fetch_nested_attribute(attribute).present?
+          fetch_nested_attribute(attribute).errors.clear
+        end
+      end
+    end
+
+    def empty?
+      super &&
+      @nested_attributes.all? do |attribute|
+        if fetch_nested_attribute(attribute).present?
+          fetch_nested_attribute(attribute).errors.empty?
+        end
+      end
+    end
+    alias_method :blank?, :empty? 
+
+    def include?(attribute)
+      if fetch_nested_attribute(attribute)
+        !fetch_nested_attribute(attribute).errors.empty?
+      else
+        messages[attribute].present?
+      end
+    end
+    alias_method :has_key?, :include? 
+    alias_method :key?, :include?
+
+    def values
+      messages.values +
+      @nested_attributes.map do |attribute|
+        if fetch_nested_attribute(attribute).present?
+          fetch_nested_attribute(attribute).errors.values
+        end
+      end
+    end
+
+    def full_messages
+      parent_messages = map { |attribute, message| full_message(attribute, message) }
+      nested_messages = @nested_attributes.map do |attribute|
+        if fetch_nested_attribute(attribute)
+          messages = fetch_nested_attribute(attribute).errors.full_messages
+          messages.map do |message|
+            "#{attribute} " + message
+          end
+        end
+      end
+      (parent_messages + nested_messages).flatten
+    end
+
+    def to_hash(full_messages = false)
+      messages = super(full_messages)
+      nested_messages = @nested_attributes.map do |attribute|
+        errors = nested_error_messages(attribute, full_messages)
+        unless errors.empty?
+          messages.merge!(attribute.to_sym => errors)
+        end
+      end
+      messages
+    end
+
+    private
+    def nested_error_messages(attribute, full_messages = false)
+      if fetch_nested_attribute(attribute)
+        if full_messages
+          errors = fetch_nested_attribute(attribute).errors
+          errors.messages.each_with_object({}) do |(attribute, array), messages|
+            messages[attribute] = array.map { |message| errors.full_message(attribute, message) }
+          end
+        else
+          fetch_nested_attribute(attribute).errors.messages.dup
+        end
+      else
+        {}
+      end
+    end
+
+    def add_error_to_attribute(attribute, error)
+      if fetch_nested_attribute(attribute)
+        fetch_nested_attribute(attribute).errors[:base] = error
+      else
+        self[attribute] << error
+      end
+    end
+
+    def reset_attribute(attribute)
+      if fetch_nested_attribute(attribute)
+        set(attribute.to_sym, fetch_nested_attribute(attribute).errors) 
+      else
+        set(attribute.to_sym, [])
+      end
+    end
+
+    def fetch_nested_attribute(attribute)
+      if @nested_attributes.include?(attribute)
+        @base.send(attribute)
+      end
+    end
+
+    def symbolize_nested(nested)
+      nested.map { |x| x.to_sym }
+    end
+  end
+end

data/lib/simple_params/params.rb

@@ -0,0 +1,129 @@
+require "active_model"
+require "virtus"
+
+module SimpleParams
+  class Params
+    include Virtus.model
+    include ActiveModel::Validations
+    include SimpleParams::Validations
+
+    class << self
+      TYPE_MAPPINGS = {
+        integer: Integer,
+        string: String,
+        decimal: BigDecimal,
+        datetime: DateTime,
+        date: Time,
+        time: DateTime,
+        float: Float,
+        # See note on Virtus
+        boolean: Axiom::Types::Boolean,
+        array: Array,
+        hash: Hash
+      }
+
+      TYPE_MAPPINGS.each_pair do |sym, klass|
+        define_method("#{sym}_param") do |name, opts={}|
+          param(name, opts.merge(type: klass))
+        end
+      end
+
+      def param(name, opts={})
+        define_attribute(name, opts)
+        add_validations(name, opts)
+      end
+
+      def nested_hash(name, opts={}, &block)
+        attr_accessor name
+        nested_class = define_nested_class(&block)
+        @nested_hashes ||= {}
+        @nested_hashes[name.to_sym] = nested_class
+      end
+      alias_method :nested_param, :nested_hash
+      alias_method :nested, :nested_hash
+
+      def nested_hashes
+        @nested_hashes || {}
+      end
+
+      private
+      def define_attribute(name, opts = {})
+        type = opts[:type] || String
+        default = opts[:default]
+        if default.present?
+          attribute name, type, default: default
+        else
+          attribute name, type
+        end
+      end
+
+      def add_validations(name, opts = {})
+        validations = opts[:validations] || {}
+        validations.merge!(presence: true) unless opts[:optional]
+        validates name, validations unless validations.empty?
+      end
+
+      def define_nested_class(&block)
+        Class.new(Params).tap do |klass|
+          name_function = Proc.new {
+            def self.model_name
+              ActiveModel::Name.new(self, nil, "temp")
+            end
+          }
+          klass.class_eval(&name_function)
+          klass.class_eval(&block)
+        end
+      end
+    end
+
+    def initialize(params={}, parent = nil)
+      @parent = parent
+      @original_params = hash_to_symbolized_hash(params)
+      @nested_params = nested_hashes.keys
+      @errors = SimpleParams::Errors.new(self, @nested_params)
+      initialize_nested_classes
+      set_accessors(params)
+      # This method comes from Virtus
+      # virtus/lib/virtus/instance_methods.rb
+      set_default_attributes
+    end
+
+    protected
+    def set_accessors(params={})
+      params.each do |attribute_name, value| 
+        # Don't set accessors for nested classes
+        unless value.is_a?(Hash)
+          send("#{attribute_name}=", value)
+          reset_blank_attributes
+        end
+      end
+    end
+
+    def reset_blank_attributes
+      # Reset to the default value for blank attributes
+      attributes.each do |attribute_name, value|
+        if send(attribute_name).blank?
+          # This method comes from Virtus
+          # virtus/lib/virtus/instance_methods.rb
+          reset_attribute(attribute_name)
+        end
+      end
+    end
+
+    private
+    def hash_to_symbolized_hash(hash)
+      hash.inject({}){|memo,(k,v)| memo[k.to_sym] = v; memo}
+    end
+
+    def nested_hashes
+      self.class.nested_hashes
+    end
+
+    def initialize_nested_classes
+      nested_hashes.each do |key, klass|
+        initialization_params = @original_params[key.to_sym] || {}
+        send("#{key}=", klass.new(initialization_params, self))
+      end
+    end
+  end
+end

data/lib/simple_params/validations.rb

@@ -0,0 +1,28 @@
+require "active_model"
+
+module SimpleParams
+  module Validations
+    extend ActiveModel::Validations
+
+    # Overriding #valid? to provide recursive validating of 
+    #  nested params
+    def valid?(context = nil)
+      current_context, self.validation_context = validation_context, context
+      errors.clear
+      run_validations!
+      nested_hashes.each do |key, value|
+        nested_class = send("#{key}") 
+        nested_class.valid?
+      end
+      errors.empty?
+    ensure
+      self.validation_context = current_context
+    end
+
+    def validate!
+      unless valid?
+        raise StandardError, errors.to_s
+      end
+    end
+  end
+end

data/lib/simple_params/version.rb

@@ -0,0 +1,3 @@
+module SimpleParams
+  VERSION = "0.0.1pre2"
+end

data/lib/simple_params.rb

@@ -0,0 +1,4 @@
+require 'simple_params/version'
+require 'simple_params/errors'
+require 'simple_params/validations'
+require 'simple_params/params'

data/simple_params.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'simple_params/version'
+
+Gem::Specification.new do |spec|
+  spec.name = "simple_params"
+  spec.version = SimpleParams::VERSION
+  spec.authors = ["brycesenz"]
+  spec.email = ["bryce.senz@gmail.com"]
+  spec.description = %q{Simple way to specify API params}
+  spec.summary = %q{A DSL for specifying params, including type coercion and validation}
+  spec.homepage = "https://github.com/brycesenz/simple_params"
+  spec.license = "MIT"
+
+  spec.files = `git ls-files`.split($/)
+  spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activemodel", ">= 3.0", "< 5.0"
+  spec.add_dependency "virtus", ">= 1.0.0"
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake", "~> 10.1"
+  spec.add_development_dependency "rspec", "~> 2.6"
+end