Rack::Param

Parameter checking and validation for Rack::Request. Originally designed to be used with Sansom, but it also works with Rack.

Installation

Add this line to your application's Gemfile:

gem "rack-param"

And then execute:

$ bundle

Or install it through gem:

$ gem install rack-param

Usage

For example:

require "rack/param"

r = Rack::Request env # pass your env
r.param :positive, Integer, :min => 0, :required => true

Now, r.params should contain a single entry, regardless of the original request's parameters.

{ "positive" => <some Integer> }

Rack::Param patches Rack::Request#params to contain only the validated parameters, in coerced form. If you want the original parameters hash, use the Rack::Request#raw_params method.

Rules

Rules are a way of making sure parameters are valid. Rather than type them yourself, use the rules below to

Rule	Argument	Default	Description
`:greater_than`	`Numeric`	none	Self explanatory.
`:less_than`	`Numeric`	none	Self explanatory.
`:min`	`Numeric`	none	Greater than or equal to.
`:max`	`Numeric`	none	Less than or equal to.
`:length`	`Numeric`	none	Self explanatory.
`:min_length`	`Numeric`	none	Greater than or equal to, using the parameter's length.
`:max_length`	`Numeric`	none	Less than or equal to, using the parameter's length.
`:in`	Responds to `include?`	none	Less than or equal to, using the parameter's length.
`:regex`	Responds to `match`	none	Self explanatory.
`:validator`	Responds to `call` with a single argument. Returns `true` or `false`	none	If the argument returns something truthy or `true`, this rule is true.

There are also a couple options used to control parameter checking.

Option	Argument	Default	Description
`:error_message`	`String`	depends on rule	The message to be used when a `Rack::ParameterError` is raised. It has a specific format: `$` is the parameter and `#` is the argument. (ex "Invalid token: $")
`:coerce`	`true`/`false`	`true`	Whether or not rack-param coerces the parameter.
`:required`	`true`/`false`	`false`	Whether or not the parameter is required.
`:default`	`Object`	`none`	If the parameter doesn't exist, this value takes its place. It should be a fully coerced value.
`:transform`	Responds to `call` with a single argument. Returns a new value.	`none`	Called to transform a coerced value.

Custom Types & Coercion

Have a custom type that you want to be able to coerce a value? Write a function whose name is the same as your class. It should take one argument, a String. In fact, most classes already have this (like Integer())

class Money
   ...
end

# somewhere in the global scope (or in `Kernel`)
def Money str
  # turn str into a `Money` and return it
end

Custom Rules

You can create custom rules! This is done by adding Rule objects to the Hash Rack::Request.rules.

# the error message (first arg of Rack::Rule.rule)
# is in the same format as the option :error_message above
Rack::Request.rules[:something] = Rack::Rule.rule "error message" do |parameter, argument| 
  # return true or false
end

Contributing

Fork it ( https://github.com/sansomrb/rack-param/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

Your changes must pass the rspec test suite.

rack-param

Development