parametric 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
----
-SHA1:
-  metadata.gz: 9fece5e356da755e6b7d0571b1e86b20a6291def
-  data.tar.gz: af78d3380fb03a0b95036d5a66345d26c6ec85aa
-SHA512:
-  metadata.gz: 365b72ed5a785678d6788023972124ddfc796118426f4281da28ea1529ebb4bd38db417fbc85d0c8fe6b28bfa9482ba22d9dc8a073448450a4bdc33f92de879c
-  data.tar.gz: d3bc507e91bc614db0f665bff1ef33ae5af4ae77a6ab92e98befb3e90b97ddca09908fa65dfeac583e44dac5a9915421de60b02a8432c89dc48da9b959ba5bd1
+--- 
+SHA1: 
+  metadata.gz: ea2ea42f0944e44e3fa09a487428f6b8cd6ef61f
+  data.tar.gz: 5e058214303cc07ac28f93924529efe8b88875fc
+SHA512: 
+  metadata.gz: e418038925d9b0e9c302cfd616b8148dd855377aaf1fa3d69ec7cb9f821add9c6e649bb096bb539fb581b4c2fcb6ca2b51ea23fc953530930daa71cdb754d184
+  data.tar.gz: 6efb123579da71f5195f3a36f5a02a0747193c55a60217c2061afc3186367cfe28bf5798c09ba11da82335b05a9e2cd83b2434964457685e9c3e905df621d45a

data/README.md

@@ -2,7 +2,7 @@
 [![Build Status](https://travis-ci.org/ismasan/parametric.png)](https://travis-ci.org/ismasan/parametric)
 [![Gem Version](https://badge.fury.io/rb/parametric.png)](http://badge.fury.io/rb/parametric)
 
-DSL for declaring allowed parameters with options, regexp patern and default values.
+DSL for declaring allowed parameters with options, regexp pattern and default values.
 
 Useful for building self-documeting APIs, search or form objects.
 
@@ -138,24 +138,25 @@ order_search.available_params # => {page: 2, per_page: 50}
 `#schema` returns a data structure including meta-data on each parameter, such as "label" and "options". Useful for building forms or self-documented Hypermedia APIs (or maybe [json-schema](http://json-schema.org/example2.html) endpoints).
 
 ```ruby
-order_search.schema # =>
+order_search.schema[:q].label # => 'Full text search query'
+order_search.schema[:q].value # => ''
 
-{
-  q: {label: 'Full text search query', value: ''},
-  page: {label: 'Page number', value: 1},
-  per_page: {label: 'Items per page', value: 30},
-  status: {label: 'Order status', value: '', options: ['checkout', 'pending', 'closed', 'shipped'], multiple: true},
-  sort: {label: 'Sort', value: 'updated_on-desc', options: ['updated_on-desc', 'updated_on-asc']}
-}
+order_search.schema[:page].label # => 'Page number'
+order_search.schema[:page].value # => 1
+
+order_search.schema[:status].label # => 'Order status'
+order_search.schema[:status].value # => ['pending']
+order_search.schema[:status].options # => ['checkout', 'pending', 'closed', 'shipped']
+order_search.schema[:status].multiple # => true
+order_search.schema[:status].default # => 'closed'
 ```
 
 ## Parametric::Hash
 
-The alternative `Parametric::Hash` module makes your objects quack like a hash, instead of exposing the `#params` object directly.
+The alternative `Parametric::Hash` class makes your objects quack like a hash, instead of exposing the `#params` object directly.
 
 ```ruby
-class OrdersParams
-  include Parametric::Hash
+class OrdersParams < Parametric::Hash
   param :q, 'Full text search query'
   param :page, 'Page number', default: 1
   param :per_page, 'Items per page', default: 30
@@ -170,10 +171,48 @@ order_params[:per_page] # => 30
 order_params.each{|key, value| ... }
 ```
 
+## Nested structures
+
+You can also nest parameter definitions. This is useful if you need to model POST payloads, for example.
+
+```ruby
+class AccountPayload
+  include Parametric::Params
+  param :status, 'Account status', default: 'pending', options: ['pending', 'active', 'cancelled']
+  param :users, 'Users in this account', multiple: true do
+    param :name, 'User name'
+    param :title, 'Job title', default: 'Employee'
+    param :email, 'User email', match: /\w+@\w+\.\w+/
+  end
+  param :owner, 'Owner user' do
+    param :name, 'User name'
+    param :email, 'User email', match: /\w+@\w+\.\w+/
+  end
+end
+```
+
+The example above expects a data structure like the following:
+
+```ruby
+{
+  status: 'active',
+  users: [
+    {name: 'Joe Bloggs', email: 'joe@bloggs.com'},
+    {name: 'jane Bloggs', email: 'jane@bloggs.com', title: 'CEO'}
+  ],
+  owner: {
+    name: 'Olivia Owner',
+    email: 'olivia@owner.com'
+  }
+}
+```
+
 ## Use cases
 
 ### In Rails
 
+You can use one-level param definitions in GET actions
+
 ```ruby
 def index
   @search = OrdersSearch.new(params)
@@ -190,6 +229,29 @@ def index
 end
 ```
 
+You can use nested definitions on POST/PUT actions, for example as part of your own strategy objects.
+
+```ruby
+def create
+  @payload = AccountPayload.new(params)
+  if @payload.save
+    render json: AccountSerializer.new(@payload.order)
+  else
+    render json: ErrorSerializer.new(@payload.errors), status: 422
+  end
+end
+```
+
+You can also use the `#schema` metadata to build Hypermedia "actions" or forms.
+
+```ruby
+# /accounts/new.json
+def new
+  @payload = AccountPayload.new
+  render json: JsonSchemaSerializer.new(@payload.schema)
+end
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/lib/parametric/hash.rb

@@ -1,36 +1,38 @@
+require 'forwardable'
 module Parametric
-  module Hash
-
-    def self.included(base)
-      base.send(:include, Params)
-      base.send(:include, Enumerable)
-      base.extend Forwardable
-      base.send(:def_delegators, :params,
-        :[],
-        :[]=,
-        :each,
-        :each_value,
-        :each_key,
-        :each_pair,
-        :keys,
-        :values,
-        :values_at,
-        :fetch,
-        :size,
-        :to_hash,
-        :merge,
-        :merge!,
-        :replace,
-        :update,
-        :has_key?,
-        :key?,
-        :key,
-        :select,
-        :select!,
-        :delete,
-        :store
-      )
-    end
+  class Hash
+    include Params
+    include Enumerable
+    extend ::Forwardable
+    def_delegators(:params,
+      :[],
+      :[]=,
+      :each,
+      :each_value,
+      :each_key,
+      :each_pair,
+      :keys,
+      :values,
+      :values_at,
+      :fetch,
+      :size,
+      :to_hash,
+      :merge,
+      :merge!,
+      :replace,
+      :update,
+      :has_key?,
+      :key?,
+      :key,
+      :select,
+      :select!,
+      :delete,
+      :store,
+      :inspect,
+      :stringify_keys,
+      :symbolize_keys
+    )
 
   end
+
 end

data/lib/parametric/params.rb

@@ -1,3 +1,4 @@
+require 'ostruct'
 module Parametric
 
   class ParamsHash < Hash
@@ -21,19 +22,19 @@ module Parametric
 
     def available_params
       @available_params ||= params.each_with_object(ParamsHash.new) do |(k,v),memo|
-        memo[k] = v if Utils.present?(v)
+        if Utils.present?(v)
+          memo[k] = v.respond_to?(:available_params) ? v.available_params : v
+        end
       end
     end
 
     def schema
       @schema ||= params.each_with_object({}) do |(k,v),memo|
-        memo[k] = {
-          value: Utils.value(v),
-          label: self.class._allowed_params[k][:label],
-          multiple: !!self.class._allowed_params[k][:multiple]
-        }
-        memo[k][:match] = self.class._allowed_params[k][:match].to_s if self.class._allowed_params[k].has_key?(:match)
-        memo[k][:options] = self.class._allowed_params[k][:options] if self.class._allowed_params[k].has_key?(:options)
+        is_nested = v.kind_of?(Parametric::Hash)
+        attrs = self.class._allowed_params[k].dup
+        attrs[:value] = is_nested ? v : Utils.value(v)
+        attrs[:schema] = v.schema if is_nested
+        memo[k] = OpenStruct.new(attrs)
       end
     end
 
@@ -41,13 +42,13 @@ module Parametric
 
     def _reduce(raw_params)
       self.class._allowed_params.each_with_object(ParamsHash.new) do |(key,options),memo|
-        policy = Policies::Policy.new(raw_params[key], options)
+        policy = Policies::Policy.new((raw_params.has_key?(key) ? raw_params[key] : []), options)
+        policy = policy.wrap(Policies::NestedPolicy)   if options[:nested]
         policy = policy.wrap(Policies::MultiplePolicy) if options[:multiple]
         policy = policy.wrap(Policies::OptionsPolicy)  if options[:options]
         policy = policy.wrap(Policies::MatchPolicy)    if options[:match]
         policy = policy.wrap(Policies::DefaultPolicy)  if options.has_key?(:default)
         policy = policy.wrap(Policies::SinglePolicy)   unless options[:multiple]
-
         memo[key] = policy.value
       end
     end
@@ -57,8 +58,13 @@ module Parametric
         @allowed_params ||= {}
       end
 
-      def param(field_name, label = '', opts = {})
+      def param(field_name, label = '', opts = {}, &block)
         opts[:label] = label
+        if block_given?
+          nested = Class.new(Parametric::Hash)
+          nested.instance_eval &block
+          opts[:nested] = nested
+        end
         _allowed_params[field_name] = opts
       end
     end

data/lib/parametric/policies.rb

@@ -12,7 +12,7 @@ module Parametric
       end
 
       def value
-        Array(@value)
+        [@value].flatten
       end
 
       protected
@@ -22,7 +22,7 @@ module Parametric
     class DefaultPolicy < Policy
       def value
         v = decorated.value
-        v.any? ? v : Array(options[:default])
+        v.size > 0 ? v : Array(options[:default])
       end
     end
 
@@ -36,6 +36,14 @@ module Parametric
       end
     end
 
+    class NestedPolicy < Policy
+      def value
+        decorated.value.map do |v|
+          options[:nested].new(v)
+        end
+      end
+    end
+
     class SinglePolicy < Policy
       def value
         decorated.value.first

data/lib/parametric/version.rb

@@ -1,3 +1,3 @@
 module Parametric
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/spec/nested_params_spec.rb

@@ -0,0 +1,90 @@
+require 'spec_helper'
+
+describe Parametric do
+
+  describe Parametric::Params do
+
+    let(:klass) do
+      Class.new do
+        include Parametric::Params
+        param :name, 'User name'
+        param :tags, 'Tags', multiple: true, default: 'defaulttag'
+        param :lala, 'Lala' do
+          param :foo, 'foo'
+        end
+        param :account, 'Account' do
+          param :name, 'Account name'
+          param :admin, 'Admin user' do
+            param :name, 'User name'
+          end
+          param :shop, 'Shop' do
+            param :url, 'Shop url', default: 'http://google.com'
+          end
+        end
+        param :variants, 'Product variants', multiple: true do
+          param :name, 'variant name', default: 'default'
+          param :price
+          param :tags, 'Variant tags', multiple: true
+        end
+      end
+    end
+
+    let(:subject) do
+      klass.new({
+        foo: 'bar',
+        name: 'user1',
+        account: {
+          name: 'account1',
+          lala: 1,
+          admin: {
+            name: 'Joe Bloggs'
+          }
+        },
+        variants: [
+          {name: 'red', price: 10},
+          {price: 11, tags: 'foo,bar'}
+        ]
+      })
+    end
+
+    describe '#params' do
+      it 'filters nested objects' do
+        expect(subject.params.has_key?(:foo)).to be_false
+        expect(subject.params[:name]).to eql('user1')
+        expect(subject.params[:account][:name]).to eql('account1')
+        expect(subject.params[:account].has_key?(:lala)).to be_false
+        expect(subject.params[:account][:admin][:name]).to eql('Joe Bloggs')
+      end
+
+      it 'nullifies nested objects that were not passed' do
+        expect(subject.params[:account].has_key?(:shop)).to be_true
+        expect(subject.params[:account][:shop]).to be_nil
+      end
+      
+      it 'filters nested :multiple into arrays of objects' do
+        expect(subject.params[:variants].size).to eql(2)
+        expect(subject.params[:variants][0][:name]).to eql('red')
+        expect(subject.params[:variants][0][:price]).to eql(10)
+        expect(subject.params[:variants][0][:tags]).to match_array([])
+        expect(subject.params[:variants][1][:name]).to eql('default')
+        expect(subject.params[:variants][1][:price]).to eql(11)
+        expect(subject.params[:variants][1][:tags]).to match_array(['foo', 'bar'])
+      end
+    end
+
+    describe '#available_params' do
+      it 'does not include key for nested objects that were not passed' do
+        expect(subject.available_params.has_key?(:lala)).to be_false
+        expect(subject.available_params[:account].has_key?(:shop)).to be_false
+      end
+    end
+
+    describe '#schema' do
+      it 'includes nested param schemas' do
+        expect(subject.schema[:account].schema[:name].value).to eql('account1')
+        expect(subject.schema[:account].schema[:name].label).to eql('Account name')
+        expect(subject.schema[:account].schema[:admin].schema[:name].value).to eql('Joe Bloggs')
+      end
+    end
+  end
+end

data/spec/parametric_spec.rb

@@ -5,7 +5,7 @@ describe Parametric do
     Parametric::VERSION.should_not be_nil
   end
 
-  describe Parametric do
+  describe Parametric::Params do
 
     let(:klass) do
       Class.new do
@@ -18,6 +18,7 @@ describe Parametric do
         param :country, 'country', options: ['UK', 'CL', 'JPN']
         param :email, 'email', match: /\w+@\w+\.\w+/
         param :emails, 'emails', match: /\w+@\w+\.\w+/, multiple: true, default: 'default@email.com'
+        param :available, 'available', default: true
       end
     end
 
@@ -44,8 +45,12 @@ describe Parametric do
         klass.new(email: 'my@email').params[:email].should be_nil
       end
 
+      it 'defaults work for false values' do
+        klass.new(email: 'my@email').params[:email].should be_nil
+      end
+
       it 'does set value if it does :match' do
-        klass.new(email: 'my@email.com').params[:email].should == 'my@email.com'
+        klass.new(available: false).params[:available].should be_false
       end
 
       it 'only sets value for :multiple values that :match' do
@@ -101,7 +106,7 @@ describe Parametric do
       let(:subject) { klass.new(foo: 'bar', name: 'lala', per_page: 20, status: 'four', emails: 'one@email.com,two@email.com') }
 
       it 'only includes declared params with values or defaults' do
-        subject.available_params.keys.sort.should == [:emails, :name, :page, :per_page]
+        subject.available_params.keys.sort.should == [:available, :emails, :name, :page, :per_page]
         subject.available_params[:emails].should == ['one@email.com', 'two@email.com']
         subject.available_params[:name].should == 'lala'
         subject.available_params[:per_page].should == 20
@@ -119,46 +124,45 @@ describe Parametric do
       let(:subject) { klass.new(foo: 'bar', name: 'lala', per_page: 20, status: 'four') }
 
       it 'returns full param definitions with populated value' do
-        regexp = /\w+@\w+\.\w+/.to_s
+        regexp = /\w+@\w+\.\w+/
 
-        subject.schema[:name][:label].should == 'User name'
-        subject.schema[:name][:value].should == 'lala'
+        subject.schema[:name].label.should == 'User name'
+        subject.schema[:name].value.should == 'lala'
 
-        subject.schema[:page][:label].should == 'page number'
-        subject.schema[:page][:value].should == 1
+        subject.schema[:page].label.should == 'page number'
+        subject.schema[:page].value.should == 1
 
-        subject.schema[:per_page][:label].should == 'items per page'
-        subject.schema[:per_page][:value].should == 20
+        subject.schema[:per_page].label.should == 'items per page'
+        subject.schema[:per_page].value.should == 20
 
-        subject.schema[:status][:label].should == 'status'
-        subject.schema[:status][:value].should == ''
-        subject.schema[:status][:options].should == ['one', 'two', 'three']
-        subject.schema[:status][:multiple].should be_true
+        subject.schema[:status].label.should == 'status'
+        subject.schema[:status].value.should == ''
+        subject.schema[:status].options.should == ['one', 'two', 'three']
+        subject.schema[:status].multiple.should be_true
 
-        subject.schema[:piped_status][:label].should == 'status with pipes'
-        subject.schema[:piped_status][:value].should == ''
-        subject.schema[:piped_status][:multiple].should be_true
+        subject.schema[:piped_status].label.should == 'status with pipes'
+        subject.schema[:piped_status].value.should == ''
+        subject.schema[:piped_status].multiple.should be_true
 
-        subject.schema[:country][:label].should == 'country'
-        subject.schema[:country][:value].should == ''
-        subject.schema[:country][:options].should == ['UK', 'CL', 'JPN']
+        subject.schema[:country].label.should == 'country'
+        subject.schema[:country].value.should == ''
+        subject.schema[:country].options.should == ['UK', 'CL', 'JPN']
 
-        subject.schema[:email][:label].should == 'email'
-        subject.schema[:email][:value].should == ''
-        subject.schema[:email][:match].should == regexp
+        subject.schema[:email].label.should == 'email'
+        subject.schema[:email].value.should == ''
+        subject.schema[:email].match.should == regexp
 
-        subject.schema[:emails][:label].should == 'emails'
-        subject.schema[:emails][:value].should == 'default@email.com'
-        subject.schema[:emails][:multiple].should be_true
-        subject.schema[:emails][:match].should == regexp
+        subject.schema[:emails].label.should == 'emails'
+        subject.schema[:emails].value.should == 'default@email.com'
+        subject.schema[:emails].multiple.should be_true
+        subject.schema[:emails].match.should == regexp
       end
     end
   end
 
   describe Parametric::Hash do
     let(:klass) do
-      Class.new do
-        include Parametric::Hash
+      Class.new(Parametric::Hash) do
         param :name, 'User name'
         param :page, 'page number', default: 1
         param :per_page, 'items per page', default: 50
@@ -185,8 +189,8 @@ describe Parametric do
     end
 
     it 'has #schema' do
-      subject.schema[:name][:label].should == 'User name'
-      subject.schema[:name][:value].should == 'Ismael'
+      subject.schema[:name].label.should == 'User name'
+      subject.schema[:name].value.should == 'Ismael'
     end
   end
 end

metadata

@@ -1,65 +1,55 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: parametric
-version: !ruby/object:Gem::Version
-  version: 0.0.2
+version: !ruby/object:Gem::Version 
+  version: 0.0.3
 platform: ruby
-authors:
+authors: 
 - Ismael Celis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-18 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
+
+date: 2014-04-03 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
   name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '1.5'
-  type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
     - - ~>
-      - !ruby/object:Gem::Version
-        version: '1.5'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+      - !ruby/object:Gem::Version 
+        version: "1.5"
   type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rake
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - &id003 
+      - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
   type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-description: Useful for modelling search or form objects, white-listed query parameters
-  and safe parameter defaults.
-email:
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    requirements: 
+    - *id003
+  type: :development
+  version_requirements: *id004
+description: Useful for modelling search or form objects, white-listed query parameters and safe parameter defaults.
+email: 
 - ismaelct@gmail.com
 executables: []
+
 extensions: []
+
 extra_rdoc_files: []
-files:
+
+files: 
 - .gitignore
 - .rspec
 - .travis.yml
@@ -74,33 +64,34 @@ files:
 - lib/parametric/utils.rb
 - lib/parametric/version.rb
 - parametric.gemspec
+- spec/nested_params_spec.rb
 - spec/parametric_spec.rb
 - spec/spec_helper.rb
-homepage: ''
-licenses:
+homepage: ""
+licenses: 
 - MIT
 metadata: {}
+
 post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
-  requirements:
-  - - '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-required_rubygems_version: !ruby/object:Gem::Requirement
-  requirements:
-  - - '>='
-    - !ruby/object:Gem::Version
-      version: '0'
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - *id003
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - *id003
 requirements: []
+
 rubyforge_project: 
-rubygems_version: 2.0.3
+rubygems_version: 2.0.5
 signing_key: 
 specification_version: 4
-summary: DSL for declaring allowed parameters with options, regexp patern and default
-  values.
-test_files:
+summary: DSL for declaring allowed parameters with options, regexp patern and default values.
+test_files: 
+- spec/nested_params_spec.rb
 - spec/parametric_spec.rb
 - spec/spec_helper.rb
+has_rdoc: