== Purpose

FormValidator is a form validation libary derived from Perl's
Data::FormValidator module. When you are coding a web application one of the
most tedious though crucial tasks is to validate user's input (usually
submitted by way of an HTML form). You have to check that each required field
is present and that all fields have valid data. (Does the phone input looks
like a phone number? Is that a plausible email address? Is the YY state valid?
etc.) For a simple form, this is not really a problem but as forms get more
complex and you code more of them this task becames really boring and tedious.

FormValidator lets you define profiles which declare the required fields and
their format. When you are ready to validate the user's input, you tell
FormValidator the profile to apply to the users data and you immediately know
the valid, missing, invalid, and unknown fields. Instance variables are filled
with the results of the validation run so you know which fields failed what
tests.

You are then free to use this information to build a nice display to the user
telling which fields had problems.

== Input Profile Specification

To create a FormValidator object, do one of the following:
    # profile data will be fed in from a hash
    fv = FormValidator.new
    # profile data will be read from someprofile.rb
    fv = FormValidator.new("someprofile.rb")

In the first case, a profile hash and form hash must be specified to the
validate method(see below). In the second case, the input profile is loaded
from somefile.rb, and a label would be given to the validate method to
indicate which profile to apply to the form. If this sounds confusing, see
the Usage section below, and you'll get the idea.

For all allowable profile methods, please see FormValidator::InputProfile.

== Usage

The simplest and most common usage is to specify the profile in a hash
and pass it along with the form data into the FormValidator::validate method.

=== Validate a simple form

    require "formvalidator"

    form = {
      "phone" => "home phone: (123) 456-7890",
      "zip"   => "32608-1234",
      "rogue" => "some unknown field"
    }

    profile = {
      :required      => [:name, :zip],
      :optional      => :phone,
      :filters       => :strip,
      :field_filters => { :phone => :phone },
      :constraints   => {
        :phone => :american_phone,
        :zip   => [
          :zip,
          {
            :name       => "pure_digit",
            :constraint => /^\d+$/
          }
        ]
      }
    }

    fv = FormValidator.new
    fv.validate(form, profile)
    fv.valid   # <== {"phone"=>"  (123) 456-7890"}
    fv.invalid # <== {"zip"=>["pure_digit"]}
    fv.missing # <== ["name"]
    fv.unknown # <== ["rogue"]

=== Validate from a file

    require "formvalidator"

    form = {
      "phone" => "home phone: (123) 456-7890",
      "zip"   => "32608-1234",
      "rogue" => "some unknown field"
    }

    fv = FormValidator.new("profile_file.rb")
    fv.validate(form, :testinfo)

    Contents of profile_file.rb
    {
    :testinfo =>
      {
        :required    => [:name, :zip],
        :optional    => [:arr, :phone],
        :filters     => :strip,
        :field_filters => { :phone => :phone },
        :constraints => {
          :phone => :american_phone,
          :zip => [
                    :zip,
                    {
                      :name       => "pure_digit",
                      :constraint => /^\d+$/
                    }
                  ]
        }
      }
    }

When placing profile data in a separate file, you must tag each profile
with a label such as testinfo in the example above. This allows multiple
profiles to be stored in a single file for easy access.

== Credits

FormValidator is written by Travis Whitton and is based on Perl's
Data::FormValidator, which was written by Francis J. Lacoste. The credit
card validation portion was adapted from MiniVend, which is written by
Bruce Albrecht.
