ParamChecker¶ ↑

ParamChecker is a small Ruby library for validating and casting string parameters. It is for example a handy way to check GET/POST parameters in Rails or Sinatra.

Installation¶ ↑

gem install param_checker

or add ParamChecker to your Gemfile

gem 'param_checker'

and afterwards (when using the Gemfile) execute

bundle install

Usage¶ ↑

Include the ParamChecker module where ever you like. I usually put it into my Rails ApplicationController.rb

class ApplicationController < ActionController::Base
  include ParamChecker
end

You can then simply call for example check_string(params[:name], "Mia", :allowed => ["foo", "bar"]) in every controller.

Instead of including the module you could also call all methods of the module directly, like

ParamChecker.check_string(params[:name], "Mia", ["foo", "bar"])

ParamChecker uses five methods:

check_integer(param, default, options)
check_float(param, default, options)
check_string(param, default, options)
check_symbol(param, default, options)
check_boolean(param, default, options)

where the function parameters are:

• param: The string parameter to check.

• default: The value that will be returned when param does not pass the check.

• options: Function specific options to check param against:

  • :min, :max in check_integer and </tt>check_float<tt>: The minimum and maximum allowed values of param. If it is not provided then no range is checked at all.

  • :allowed in check_string and check_symbol: Represents the allowed values of param. It can be either a regular expression, a string (resp. a symbol for check_symbol), or an array of strings (resp. an array of symbols for check_symbol).

  • :true and :false in check_boolean: Represents the allowed string values for true and false. Default is :true => [“1”, “true”] and :false => [“0”, “false”].

All methods return the casted value (check_integer returns an integer, check_symbol returns a symbol, and so on).

Examples¶ ↑

Below are some simple examples how to use ParamChecker:

# Check if per_page parameter is a valid integer representation, ensure that it is bigger than 1 and smaller than 100 and return its integer value. Otherwise return 10.
page = check_integer(params[:per_page], 10, :min => 1, :max => 100)

# If field parameter is equal to "name" or "address" then return it, otherwise return "name".
field = check_string(params[:field], "name", :allowed => ["name", "address"])

# Return the boolean if params[:accepted] is a valid string representation of a boolean and return false otherwise.
accepted = check_boolean(params[:accepted], false)

# Custom boolean string representation values.
accepted = check_boolean(params[:accepted], false, :true => ["yep", "yes"], :false => ["nope", "no"])

Alternative usage¶ ↑

Since version 0.3 you can also extend your Hash or HashWithIndifferentAccess with ParamChecker::HashExt. This will allow you to directly call the ParamChecker methods on the params hash:

params.check(type, keys, default, options)

type can be:

• :i or :integer calls check_integer internally

• :f or :float calls check_float internally

• :s or :string calls check_string internally

• :sym or :symbol calls check_symbol internally

• :b or :boolean calls check boolean internally

params_key can be either an array of keys or just one key to access the hash.

Examples¶ ↑

# Checks params[:page] and returns the integer representation if valid.
params.check(:i, :page, 5, :min => 1)

# Check params[:company][:name] and returns "Comparilla" if invalid.
params.check(:s, [:company, :name], "Comparilla")

# Does exactly the same.
params.check(:string, [:company, :name], "Comparilla")

Testing¶ ↑

ParamChecker uses RSpec for testing and has a rake task for executing the provided specs

rake spec

Copyright © 2010-2011 Kai Schlamp (www.medihack.org), released under the MIT license