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

1. Fork it ( https://github.com/sansomrb/rack-param/fork )
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 a new Pull Request

Your changes must pass the rspec test suite.