parameters_schema 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ab3f9f1e20eec3092c2362e52e002e974c51b2ba
-  data.tar.gz: a9c817c713fa10529286f629d576d5eb09673879
+  metadata.gz: 14b2e93c33b07b2beb454f9b604f4f77e96da0e6
+  data.tar.gz: 64bb0eaf552948ddb687625ece733d4f8a08fe38
 SHA512:
-  metadata.gz: 68980a8ff4bf48844160bc378a7f572fed2b25c49f6f35ef8f26e667c66dd8a6a0a0cf46559e0624afbe507da3a78c4c8d681540b4ac9ff977ab6ef4e4875a17
-  data.tar.gz: b90a54e7fee674a137305a0c958197b814756f4fe8bfe1fb1e49c95df31d433ca4b10bc2127e52679d50be3bb3a6af4bb3ee3d8c6edbacc85753695a3d46a108
+  metadata.gz: a2eb862ee2b536e377f0177b70ca983f6b618fab0222fe89bf423ae4228eef6f5db87e4d8cde5defec8814d7a5180e6997198abe0ed016b0b3037573ff5ccdbc
+  data.tar.gz: 269810eec92651bbd6701a9df474cbd394b87a1428f2e417091aef4896ddc409d8baf1f9a5c05096901e821441564667ad540475679a67e73c09657dead4e605

data/Gemfile

@@ -1,4 +1,5 @@
 source 'http://rubygems.org'
 
+gem 'rake'
 gem 'minitest'
-gem 'activesupport'
+gem 'activesupport'

data/README.md

@@ -1,10 +1,8 @@
 # Parameters Schema
 
-## *"A strict API is the best kind of API."*
+This gem is an alternative to **[strong_parameters](https://github.com/rails/strong_parameters)** to validate data at the controller level.
 
-In this line of thought, **[strong_parameters](https://github.com/rails/strong_parameters)** lacks a few awesome validations that this gem provide.
-
-For example, let's say you want your operation `create` to require a `Fixnum` parameter between 1 and 99. With strong_parameters, you're out of luck. With this gem, you simply write in your controller:
+For example, let's say you want your operation `create` to require a `Fixnum` parameter between `1` and `99`:
 ``` ruby
 class Api::PeopleController < Api::BaseController
   def create
@@ -12,7 +10,7 @@ class Api::PeopleController < Api::BaseController
       param :age, type: Fixnum, allow: (1..99)
     end
 
-    # Do something with the validated parameters.
+    @person = Person.create!(validated_params)
   end
 end
 ```
@@ -20,30 +18,57 @@ end
 So when you use this controller:
 ``` ruby
 > app.post 'api/people', age: 12  # validated_params = { age: 12 }
-> app.post 'api/people', age: 100 # throws a ParameterSchema::InvalidParameters 
+> app.post 'api/people', age: 100 # throws a ParameterSchema::InvalidParameters
 ```
 
-## Why use this gem instead of strong_parameters
+## Why use this gem instead of *strong_parameters*:
 
-* You prefer a procedural approach (via a DSL) over a declarative one.
-* You want more control over the parameters of your API, at the type and format level.
-* You want to do things differently, you darn hipster ;)
+* You want more control over the parameters of your API, at the *type* and *format* level.
+* You want a strict API that will only accept well-formed requests.
+* You don't grasp the *strong_parameters* syntax and wants something more like a DSL.
+* You want to validate data outside of Rails.
 
 ## Installation
 
-Add in your Gemfile:
+Add in your `Gemfile`:
 ``` ruby
 gem 'parameters_schema'
 ```
 
-Add in your project:
+Add in your project (not required for Rails):
 ``` ruby
 require 'parameters_schema'
 ```
 
+## Quick start
+
+Read this then _Integrate with Rails_ if you want to use this gem quickly.
+
+Let's take the example at the beginning of this README, with more details:
+
+``` ruby
+class Api::PeopleController < Api::BaseController
+  def create
+    # 1. For each request, you define a schema (i.e. the parameters of the request).
+    schema = ParametersSchema::Schema.new do
+      param :age, type: Fixnum, allow: (1..99)
+    end
+
+    # 2. When a user makes a request, you validate it against the schema.
+    # - When the request is invalid, an exception is raised.
+    # - When the request is valid, you receive a sanitized hash.
+    validated_params = schema.validate!(params)
+
+    @person = Person.create!(validated_params)
+  end
+end
+```
+
+Now, _Integrate with Rails_ gives pointers on how to simplify all this.
+
 ## Schema
 
-The schema is the heart of this gem.  It provides a simple DSL to express an operation's parameters.
+The schema is the heart of this gem. With a simple DSL, you define the parameters of a request.
 
 Creating a schema:
 ``` ruby
@@ -52,16 +77,18 @@ schema = ParametersSchema::Schema.new do
   # ... but an empty schema is also valid.
 end
 ```
+
 Validating parameters against a schema:
 ``` ruby
 params = { potatoe: 'Eramosa' }
-schema.validate!(params) 
+schema.validate!(params)
 ```
 
 The minimal representation of a parameter is:
 ``` ruby
 param :potatoe
 ```
+
 This represents a `required` parameter of type `String` accepting any characters and which doesn't allow nil or empty values.
 
 The valid options for a parameter are:
@@ -75,7 +102,7 @@ The valid options for a parameter are:
 
 ### Parameter types
 
-The available types are: 
+The available types are:
 ``` ruby
 * String
 * Symbol
@@ -137,9 +164,9 @@ end
 
 ### The `allow` and `deny` options
 
-By default, the value of a parameter can be any one in the spectrum of a type, with the exception of nil and empty. The `allow` and `deny` options can be used to further refine the accepted values.
+By default, the value of a parameter can be any one in the spectrum of a type, with the exception of `nil` and empty. The `allow` and `deny` options can be used to further refine the accepted values.
 
-To accept nil or empty values:
+To accept `nil` or empty values:
 ``` ruby
 param :potatoe, allow: :nil
 # => accepts nil, 'Kennebec' but not ''.
@@ -150,7 +177,7 @@ param :potatoe, allow: :empty
 param :potatoe, allow: [:nil, :empty]
 # => accepts nil, '' and 'Kennebec'
 ```
-Of course, this *nil* or *empty* restriction doesn't make sense for all the types so it will only be applied when it does.
+Of course, this `nil` or `empty` restriction doesn't make sense for all the types so it will only be applied when it does.
 
 To accept predefined values:
 ``` ruby
@@ -220,12 +247,13 @@ The possible error codes are (in the order the are validated):
 
 ## Integrate with Rails
 
-This gem can be used outside of Rails but was created with Rails in mind. For example, the parameters `controller, action, format` are skipped by default (see Options section to override this behavior) and the parameters are defined in a `Hash`. However, this gem doesn't insinuate itself in your project so you must manually add it in your controllers or anywhere else that make sense to you. Here is a little recipe to add validation in your API pipeline:
+This gem can be used outside of Rails but was created with Rails in mind. For example, the parameters `controller`, `action` and `format` are skipped by default (see Options section to override this behavior) and the parameters are defined in a `Hash`. However, this gem doesn't insinuate itself in your project so you must manually add it in your controllers or anywhere else that make sense to you. Here is a little recipe to add validation in your API pipeline:
 
 In the base controller of your API, add this **helper**:
 ``` ruby
     # Validate the parameters of an action, using a schema.
     # Returns the validated parameters and throw exceptions on invalid input.
+    # Note: this helper could be refined to cache the schemas.
     def validate_params(&parameters_schema)
       schema = ParametersSchema::Schema.new(&parameters_schema)
       schema.validate!(params)
@@ -274,10 +302,19 @@ Available options:
 
 Yes, please. Bug fixes, new features, refactoring, unit tests. Send your precious pull requests.
 
+### Developing this gem
+
+1. Fork this repository.
+2. Clone your fork.
+3. (Optional) Prepare it with `rbenv` or `RVM`. Ex: `echo 2.3.0 > .ruby-version`.
+4. `bundle install` to install the gems.
+5. `rake test` to launch the tests suite.
+6. Make your changes and send me pull requests.
+
 ### Ideas
 
 * Array of arrays of ...
-* Min/Max for numeric values
+* `min` and `max` options for numeric values (instead of `allow: (min..max)`)
 * More `allow` options
 * Better refine error codes
 

data/lib/parameters_schema/core_ext.rb

@@ -12,7 +12,6 @@ class Object
   #
   def numeric?
     return true if self.kind_of?(Numeric)
-    return true if self.to_s =~ /^\d+$/
     Float(self)
     true
   rescue

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parameters_schema
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Jodi Giordano
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-03 00:00:00.000000000 Z
+date: 2016-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -69,7 +69,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.6
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Strict schema for request parameters