.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Data::FormValidator::Constraints 3pm"
.TH Data::FormValidator::Constraints 3pm "2017-10-24" "perl v5.26.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Data::FormValidator::Constraints \- Basic sets of constraints on input profile.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Data::FormValidator::Constraints qw(:closures);
.Ve
.PP
In an Data::FormValidator profile:
.PP
.Vb 10
\&    constraint_methods => {
\&        email   => email(),
\&        phone   => american_phone(),
\&        first_names =>  {
\&           constraint_method => FV_max_length(3),
\&           name => \*(Aqmy_custom_name\*(Aq,
\&       },
\&    },
\&    msgs => {
\&       constraints => {
\&            my_custom_name => \*(AqMy message\*(Aq,
\&       },
\&    },
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
These are the builtin constraints that can be specified by name in the input
profiles.
.PP
Be sure to check out the \s-1SEE ALSO\s0 section for even more pre-packaged
constraints you can use.
.SS "FV_length_between(1,23)"
.IX Subsection "FV_length_between(1,23)"
.SS "FV_max_length(23)"
.IX Subsection "FV_max_length(23)"
.SS "\fIFV_min_length\fP\|(1)"
.IX Subsection "FV_min_length"
.Vb 5
\&  use Data::FormValidator::Constraints qw(
\&    FV_length_between
\&    FV_min_length
\&    FV_max_length
\&  );
\&
\&  constraint_methods => {
\&
\&    # specify a min and max, inclusive
\&    last_name        => FV_length_between(1,23),
\&
\&  }
.Ve
.PP
Specify a length constraint for a field.
.PP
These constraints have a different naming convention because they are higher-order
functions. They take input and return a code reference to a standard constraint
method. A constraint name of \f(CW\*(C`length_between\*(C'\fR, \f(CW\*(C`min_length\*(C'\fR, or \f(CW\*(C`max_length\*(C'\fR will be set,
corresponding to the function name you choose.
.PP
The checks are all inclusive, so a max length of '100' will allow the length 100.
.PP
Length is measured in perl characters as opposed to bytes or anything else.
.PP
This constraint \fIwill\fR untaint your data if you have untainting turned on. However,
a length check alone may not be enough to insure the safety of the data you are receiving.
Using additional constraints to check the data is encouraged.
.SS "FV_eq_with"
.IX Subsection "FV_eq_with"
.Vb 1
\&  use Data::FormValidator::Constraints qw( FV_eq_with );
\&
\&  constraint_methods => {
\&    password  => FV_eq_with(\*(Aqpassword_confirm\*(Aq),
\&  }
.Ve
.PP
Compares the current field to another field.
A constraint name of \f(CW\*(C`eq_with\*(C'\fR will be set.
.SS "FV_num_values"
.IX Subsection "FV_num_values"
.Vb 1
\&    use Data::FormValidator::Constraints qw ( FV_num_values );
\&
\&    constraint_methods => {
\&        attachments => FV_num_values(4),
\&    }
.Ve
.PP
Checks the number of values in the array named by this param.
Note that this is useful for making sure that only one value was passed for a
given param (by supplying a size argument of 1).
A constraint name of \f(CW\*(C`num_values\*(C'\fR will be set.
.SS "FV_num_values_between"
.IX Subsection "FV_num_values_between"
.Vb 1
\&    use Data::FormValidator::Constraints qw ( FV_num_values_between );
\&
\&    constraint_methods => {
\&        attachments => FV_num_values_between(1,4),
\&    }
.Ve
.PP
Checks that the number of values in the array named by this param is between
the supplied bounds (inclusively).
A constraint name of \f(CW\*(C`num_values_between\*(C'\fR will be set.
.SS "email"
.IX Subsection "email"
Checks if the email \s-1LOOKS LIKE\s0 an email address. This should be sufficient
99% of the time.
.PP
Look elsewhere if you want something super fancy that matches every possible variation
that is valid in the \s-1RFC,\s0 or runs out and checks some \s-1MX\s0 records.
.SS "state_or_province"
.IX Subsection "state_or_province"
This one checks if the input correspond to an american state or a canadian
province.
.SS "state"
.IX Subsection "state"
This one checks if the input is a valid two letter abbreviation of an
American state.
.SS "province"
.IX Subsection "province"
This checks if the input is a two letter Canadian province
abbreviation.
.SS "zip_or_postcode"
.IX Subsection "zip_or_postcode"
This constraints checks if the input is an American zipcode or a
Canadian postal code.
.SS "postcode"
.IX Subsection "postcode"
This constraints checks if the input is a valid Canadian postal code.
.SS "zip"
.IX Subsection "zip"
This input validator checks if the input is a valid american zipcode :
5 digits followed by an optional mailbox number.
.SS "phone"
.IX Subsection "phone"
This one checks if the input looks like a phone number, (if it
contains at least 6 digits.)
.SS "american_phone"
.IX Subsection "american_phone"
This constraints checks if the number is a possible North American style
of phone number : (\s-1XXX\s0) XXX-XXXX. It has to contains 7 or more digits.
.SS "cc_number"
.IX Subsection "cc_number"
This constraint references the value of a credit card type field.
.PP
.Vb 3
\& constraint_methods => {
\&    cc_no      => cc_number({fields => [\*(Aqcc_type\*(Aq]}),
\&  }
.Ve
.PP
The number is checked only for plausibility, it checks if the number could
be valid for a type of card by checking the checksum and looking at the number
of digits and the number of digits of the number.
.PP
This functions is only good at catching typos. \s-1IT DOESN\s0'T
\&\s-1CHECK IF THERE IS AN ACCOUNT ASSOCIATED WITH THE NUMBER.\s0
.SS "cc_exp"
.IX Subsection "cc_exp"
This one checks if the input is in the format \s-1MM/YY\s0 or \s-1MM/YYYY\s0 and if
the \s-1MM\s0 part is a valid month (1\-12) and if that date is not in the past.
.SS "cc_type"
.IX Subsection "cc_type"
This one checks if the input field starts by M(asterCard), V(isa),
A(merican express) or D(iscovery).
.SS "ip_address"
.IX Subsection "ip_address"
This checks if the input is formatted like a dotted decimal \s-1IP\s0 address (v4).
For other kinds of \s-1IP\s0 address method, See Regexp::Common::net which provides
several more options. \*(L"\s-1REGEXP::COMMON SUPPORT\*(R"\s0 explains how we easily integrate
with Regexp::Common.
.SH "RENAMING BUILT-IN CONSTAINTS"
.IX Header "RENAMING BUILT-IN CONSTAINTS"
If you'd like, you can rename any of the built-in constraints. Just define the constraint_method and name
in a hashref, like this:
.PP
.Vb 6
\&        constraint_methods => {
\&            first_names =>  {
\&                constraint_method => FV_max_length(3),
\&                name => \*(Aqcustom_length\*(Aq,
\&            }
\&        },
.Ve
.SH "REGEXP::COMMON SUPPORT"
.IX Header "REGEXP::COMMON SUPPORT"
Data::FormValidator also includes built-in support for using any of regular expressions
in Regexp::Common as named constraints. Simply use the name of regular expression you want.
This works whether you want to untaint the data or not. For example:
.PP
.Vb 1
\& use Data::FormValidator::Constraints qw(:regexp_common);
\&
\& constraint_methods => {
\&    my_ip_address => FV_net_IPv4(),
\&
\&    # An example with parameters
\&    other_ip      => FV_net_IPv4(\-sep=>\*(Aq \*(Aq),
\& }
.Ve
.PP
Notice that the routines are named with the prefix \*(L"\s-1FV_\*(R"\s0 instead of \*(L"\s-1RE_\*(R"\s0 now.
This is simply a visual cue that these are slightly modified versions. We've made
a wrapper for each Regexp::Common routine so that it can be used as a named constraint
like this.
.PP
Be sure to check out the Regexp::Common syntax for how its syntax works. It
will make more sense to add future regular expressions to Regexp::Common rather
than to Data::FormValidator.
.SH "PROCEDURAL INTERFACE"
.IX Header "PROCEDURAL INTERFACE"
You may also call these functions directly through the procedural interface by
either importing them directly or importing the whole \fI:validators\fR group.
This is useful if you want to use the built-in validators out of the usual
profile specification interface.
.PP
For example, if you want to access the \fIemail\fR validator
directly, you could either do:
.PP
.Vb 3
\&    use Data::FormValidator::Constraints (qw/valid_email/);
\&    or
\&    use Data::FormValidator::Constraints (:validators);
\&
\&    if (valid_email($email)) {
\&      # do something with the email address
\&    }
.Ve
.PP
Notice that when you call validators directly, you'll need to prefix the
validator name with \*(L"valid_\*(R"
.PP
Each validator also has a version that returns the untainted value if
the validation succeeded. You may call these functions directly
through the procedural interface by either importing them directly or
importing the \fI:matchers\fR group. For example if you want to untaint a
value with the \fIemail\fR validator directly you may:
.PP
.Vb 6
\&    if ($email = match_email($email)) {
\&        system("echo $email");
\&    }
\&    else {
\&        die "Unable to validate email";
\&    }
.Ve
.PP
Notice that when you call validators directly and want them to return an
untainted value, you'll need to prefix the validator name with \*(L"match_\*(R"
.SH "WRITING YOUR OWN CONSTRAINT ROUTINES"
.IX Header "WRITING YOUR OWN CONSTRAINT ROUTINES"
.SS "New School Constraints Overview"
.IX Subsection "New School Constraints Overview"
This is the current recommended way to write constraints. See also \*(L"Old School Constraints\*(R".
.PP
The most flexible way to create constraints to use closures\*(-- a normal seeming
outer subroutine which returns a customized \s-1DFV\s0 method subroutine as a result.
It's easy to do. These \*(L"constraint methods\*(R" can be named whatever you like, and
imported normally into the name space where the profile is located.
.PP
Let's look at an example.
.PP
.Vb 4
\&  # Near your profile
\&  # Of course, you don\*(Aqt have to export/import if your constraints are in the same
\&  # package as the profile.
\&  use My::Constraints \*(Aqcoolness\*(Aq;
\&
\&  # In your profile
\&  constraint_methods => {
\&    email            => email(),
\&    prospective_date => coolness( 40, 60,
\&        {fields => [qw/personality smarts good_looks/]}
\&    ),
\&  }
.Ve
.PP
Let's look at how this complex \f(CW\*(C`coolness\*(C'\fR constraint method works. The
interface asks for users to define minimum and maximum coolness values, as
well as declaring three data field names that we should peek into to look
their values.
.PP
Here's what the code might look like:
.PP
.Vb 5
\&  sub coolness {
\&    my ($min_cool,$max_cool, $attrs) = @_;
\&    my ($personality,$smarts,$looks) = @{ $attrs\->{fields} } if $attrs\->{fields};
\&    return sub {
\&        my $dfv = shift;
\&
\&        # Name it to refer to in the \*(Aqmsgs\*(Aq system.
\&        $dfv\->name_this(\*(Aqcoolness\*(Aq);
\&
\&        # value of \*(Aqprospective_date\*(Aq parameter
\&        my $val = $dfv\->get_current_constraint_value();
\&
\&        # get other data to refer to
\&        my $data = $dfv\->get_filtered_data;
\&
\&        my $has_all_three = ($data\->{$personality} && $data\->{$smarts} && $data\->{$looks});
\&        return ( ($val >= $min_cool) && ($val <= $max_cool) && $has_all_three );
\&    }
\&  }
.Ve
.SS "Old School Constraints"
.IX Subsection "Old School Constraints"
Here is documentation on how old school constraints are created. These are
supported, but the new school style documented above is recommended.
.PP
See also the \f(CW\*(C`validator_packages\*(C'\fR option in the input profile, for loading
sets of old school constraints from other packages.
.PP
Old school constraint routines are named two ways. Some are named with the
prefix \f(CW\*(C`match_\*(C'\fR while others start with \f(CW\*(C`valid_\*(C'\fR. The difference is that the
\&\f(CW\*(C`match_\*(C'\fR routines are built to untaint the data and return a safe version of
it if it validates, while \f(CW\*(C`valid_\*(C'\fR routines simply return a true value if the
validation succeeds and false otherwise.
.PP
It is preferable to write \f(CW\*(C`match_\*(C'\fR routines that untaint data for the extra
security benefits. Plus, Data::FormValidator will \s-1AUTOLOAD\s0 a \f(CW\*(C`valid_\*(C'\fR version
if anyone tries to use it, so you only need to write one routine to cover both
cases.
.PP
Usually constraint routines only need one input, the value being specified.
However, sometimes more than one value is needed.
.PP
\&\fBExample\fR:
.PP
.Vb 4
\&        image_field  => {
\&            constraint_method  => \*(Aqmax_image_dimensions\*(Aq,
\&            params => [\e100,\e200],
\&        },
.Ve
.PP
Using that syntax, the first parameter that will be passed to the routine is
the Data::FormValidator object. The remaining parameters will come from the
\&\f(CW\*(C`params\*(C'\fR array. Strings will be replaced by the values of fields with the same names,
and references will be passed directly.
.PP
In addition to \f(CW\*(C`constraint_method\*(C'\fR, there is also an even older technique using
the name \f(CW\*(C`constraint\*(C'\fR instead. Routines that are designed to work with
\&\f(CW\*(C`constraint\*(C'\fR \fIdon't\fR have access to Data::FormValidator object, which
means users need to pass in the name of the field being validated. Besides
adding unnecessary syntax to the user interface, it won't work in conjunction
with \f(CW\*(C`constraint_regexp_map\*(C'\fR.
.SS "Methods available for use inside of constraints"
.IX Subsection "Methods available for use inside of constraints"
A few useful methods to use on the Data::FormValidator::Results object are
available to you to use inside of your routine.
.PP
\fI\fIget_input_data()\fI\fR
.IX Subsection "get_input_data()"
.PP
Returns the raw input data. This may be a \s-1CGI\s0 object if that's what
was used in the constraint routine.
.PP
\&\fBExamples:\fR
.PP
.Vb 2
\& # Raw and uncensored
\& my $data = $self\->get_input_data;
\&
\& # tamed to be a hashref, if it wasn\*(Aqt already
\& my $data = $self\->get_input_data( as_hashref => 1 );
.Ve
.PP
\fI\fIget_filtered_data()\fI\fR
.IX Subsection "get_filtered_data()"
.PP
.Vb 1
\& my $data = $self\->get_filtered_data;
.Ve
.PP
Returns the valid filtered data as a hashref, regardless of whether
it started out as a \s-1CGI\s0.pm compatible object. Multiple values are
expressed as array references.
.PP
\fI\fIget_current_constraint_field()\fI\fR
.IX Subsection "get_current_constraint_field()"
.PP
Returns the name of the current field being tested in the constraint.
.PP
\&\fBExample\fR:
.PP
.Vb 1
\& my $field = $self\->get_current_constraint_field;
.Ve
.PP
This reduces the number of parameters that need to be passed into the routine
and allows multi-valued constraints to be used with \f(CW\*(C`constraint_regexp_map\*(C'\fR.
.PP
For complete examples of multi-valued constraints, see Data::FormValidator::Constraints::Upload
.PP
\fI\fIget_current_constraint_value()\fI\fR
.IX Subsection "get_current_constraint_value()"
.PP
Returns the name of the current value being tested in the constraint.
.PP
\&\fBExample\fR:
.PP
.Vb 1
\& my $value = $self\->get_current_constraint_value;
.Ve
.PP
This reduces the number of parameters that need to be passed into the routine
and allows multi-valued constraints to be used with \f(CW\*(C`constraint_regexp_map\*(C'\fR.
.PP
\fI\fIget_current_constraint_name()\fI\fR
.IX Subsection "get_current_constraint_name()"
.PP
Returns the name of the current constraint being applied
.PP
\&\fBExample\fR:
.PP
.Vb 1
\& my $value = $self\->get_current_constraint_name;
.Ve
.PP
This is useful for building a constraint on the fly based on its name.
It's used internally as part of the interface to the Regexp::Commmon
regular expressions.
.PP
\fI\fIuntainted_constraint_value()\fI\fR
.IX Subsection "untainted_constraint_value()"
.PP
.Vb 1
\&   return $dfv\->untainted_constraint_value($match);
.Ve
.PP
If you have written a constraint which untaints, use this method to return the
untainted result. It will prepare the right result whether the user has requested
untainting or not.
.PP
\fI\fIname_this()\fI\fR
.IX Subsection "name_this()"
.PP
\fI\fIset_current_constraint_name()\fI\fR
.IX Subsection "set_current_constraint_name()"
.PP
Sets the name of the current constraint being applied.
.PP
\&\fBExample\fR:
.PP
.Vb 9
\& sub my_constraint {
\&    my @outer_params = @_;
\&    return sub {
\&        my $dfv = shift;
\&        $dfv\->set_current_constraint_name(\*(Aqmy_constraint\*(Aq);
\&        my @params = @outer_params;
\&        # do something constraining here...
\&    }
\& }
.Ve
.PP
By returning a closure which uses this method,  you can build an advanced named
constraint in your profile, before you actually have access to the \s-1DFV\s0 object
that will be used later. See Data::FormValidator::Constraints::Upload for an
example.
.PP
\&\f(CW\*(C`name_this\*(C'\fR is a provided as a shorter synonym.
.PP
The \f(CW\*(C`meta()\*(C'\fR method may also be useful to communicate meta data that
may have been found. See Data::FormValidator::Results for documentation
of that method.
.SH "BACKWARDS COMPATIBILITY"
.IX Header "BACKWARDS COMPATIBILITY"
Prior to Data::FormValidator 4.00, constraints were specified a bit differently.
This older style is still supported.
.PP
It was not necessary to explicitly load some constraints into your name space,
and the names were given as strings, like this:
.PP
.Vb 10
\&    constraints  => {
\&        email         => \*(Aqemail\*(Aq,
\&        fax           => \*(Aqamerican_phone\*(Aq,
\&        phone         => \*(Aqamerican_phone\*(Aq,
\&        state         => \*(Aqstate\*(Aq,
\&        my_ip_address => \*(AqRE_net_IPv4\*(Aq,
\&        other_ip => {
\&            constraint => \*(AqRE_net_IPv4\*(Aq,
\&            params => [ \e\*(Aq\-sep\*(Aq=> \e\*(Aq \*(Aq ],
\&        },
\&        my_cc_no      => {
\&            constraint => \*(Aqcc_number\*(Aq,
\&            params => [qw/cc_no cc_type/],
\&        }
\&    },
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.SS "Constraints available in other modules"
.IX Subsection "Constraints available in other modules"
.IP "Data::FormValidator::Constraints::Upload \- validate the bytes, format and dimensions of file uploads" 4
.IX Item "Data::FormValidator::Constraints::Upload - validate the bytes, format and dimensions of file uploads"
.PD 0
.IP "Data::FormValidator::Constraints::DateTime \- A newer DateTime constraint module. May save you a step of transforming the date into a more useful format after it's validated." 4
.IX Item "Data::FormValidator::Constraints::DateTime - A newer DateTime constraint module. May save you a step of transforming the date into a more useful format after it's validated."
.IP "Data::FormValidator::Constraints::Dates \- the original \s-1DFV\s0 date constraint module. Try the newer one first!" 4
.IX Item "Data::FormValidator::Constraints::Dates - the original DFV date constraint module. Try the newer one first!"
.IP "Data::FormValidator::Constraints::Japanese \- Japan-specific constraints" 4
.IX Item "Data::FormValidator::Constraints::Japanese - Japan-specific constraints"
.IP "Data::FormValidator::Constraints::MethodsFactory \- a useful collection of tools generate more complex constraints. Recommended!" 4
.IX Item "Data::FormValidator::Constraints::MethodsFactory - a useful collection of tools generate more complex constraints. Recommended!"
.PD
.SS "Related modules in this package"
.IX Subsection "Related modules in this package"
.IP "Data::FormValidator::Filters \- transform data before constraints are applied" 4
.IX Item "Data::FormValidator::Filters - transform data before constraints are applied"
.PD 0
.ie n .IP "Data::FormValidator::ConstraintsFactory \- This is a historical collection of constraints that suffer from cumbersome names. They are worth reviewing though\*(-- ""make_and_constraint"" will allow one to validate against a list of constraints and shortcircuit if the first one fails. That's perfect if the second constraint depends on the first one having passed. For a modern version of this toolkit, see Data::FormValidator::Constraints::MethodsFactory." 4
.el .IP "Data::FormValidator::ConstraintsFactory \- This is a historical collection of constraints that suffer from cumbersome names. They are worth reviewing though\*(-- \f(CWmake_and_constraint\fR will allow one to validate against a list of constraints and shortcircuit if the first one fails. That's perfect if the second constraint depends on the first one having passed. For a modern version of this toolkit, see Data::FormValidator::Constraints::MethodsFactory." 4
.IX Item "Data::FormValidator::ConstraintsFactory - This is a historical collection of constraints that suffer from cumbersome names. They are worth reviewing though make_and_constraint will allow one to validate against a list of constraints and shortcircuit if the first one fails. That's perfect if the second constraint depends on the first one having passed. For a modern version of this toolkit, see Data::FormValidator::Constraints::MethodsFactory."
.IP "Data::FormValidator" 4
.IX Item "Data::FormValidator"
.PD
.SH "CREDITS"
.IX Header "CREDITS"
Some of those input validation functions have been taken from MiniVend
by Michael J. Heins
.PP
The credit card checksum validation was taken from contribution by
Bruce Albrecht to the MiniVend program.
.SH "AUTHORS"
.IX Header "AUTHORS"
.Vb 4
\&    Francis J. Lacoste
\&    Michael J. Heins
\&    Bruce Albrecht
\&    Mark Stosberg
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1999 iNsu Innovations Inc.
All rights reserved.
.PP
Parts Copyright 1996\-1999 by Michael J. Heins
Parts Copyright 1996\-1999 by Bruce Albrecht
Parts Copyright 2005\-2009 by Mark Stosberg
.PP
This program is free software; you can redistribute it and/or modify
it under the terms as perl itself.