/usr/share/perl5/Data/FormValidator/Constraints.pm is in libdata-formvalidator-perl 4.81-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 | #
# Constraints.pm - Standard constraints for use in Data::FormValidator.
#
# This file is part of Data::FormValidator.
#
# Author: Francis J. Lacoste
# Maintainer: Mark Stosberg <mark@summersault.com>
#
# Copyright (C) 1999,2000 iNsu Innovations Inc.
# Copyright (C) 2001 Francis J. Lacoste
# Parts Copyright 1996-1999 by Michael J. Heins
# Parts Copyright 1996-1999 by Bruce Albrecht
#
# Parts of this module are based on work by
# Bruce Albrecht, contributed to MiniVend.
#
# Parts also based on work by Michael J. Heins
#
# This program is free software; you can redistribute it and/or modify
# it under the terms same terms as perl itself.
#
package Data::FormValidator::Constraints;
use base 'Exporter';
use strict;
our $AUTOLOAD;
our $VERSION = 4.81;
BEGIN {
use Carp;
my @closures = (qw/
american_phone
cc_exp
cc_number
cc_type
email
ip_address
phone
postcode
province
state
state_or_province
zip
zip_or_postcode/);
# This be optimized with some of the voodoo that CGI.pm
# uses to AUTOLOAD dynamic functions.
for my $func (@closures) {
# cc_number is defined statically
unless ($func eq 'cc_number') {
# Notice we have to escape some characters
# in the subroutine, which is really a string here.
local $SIG{__DIE__} = \&confess;
my $code = qq!
sub $func {
return sub {
my \$dfv = shift;
use Scalar::Util ();
die "first arg to $func was not an object. Must be called as a constraint_method."
unless ( Scalar::Util::blessed(\$dfv) && \$dfv->can('name_this') );
\$dfv->name_this('$func') unless \$dfv->get_current_constraint_name();
no strict 'refs';
return &{"match_$func"}(\@_);
}
}
!;
eval "package Data::FormValidator::Constraints; $code";
die "couldn't create $func: $@" if $@;
}
}
my @FVs = (qw/
FV_length_between
FV_min_length
FV_max_length
FV_eq_with
FV_num_values
FV_num_values_between
/);
our @EXPORT_OK = (
@closures,
@FVs,
qw(
valid_american_phone
valid_cc_exp
valid_cc_number
valid_cc_type
valid_email
valid_ip_address
valid_phone
valid_postcode
valid_province
valid_state
valid_state_or_province
valid_zip
valid_zip_or_postcode
match_american_phone
match_cc_exp
match_cc_number
match_cc_type
match_email
match_ip_address
match_phone
match_postcode
match_province
match_state
match_state_or_province
match_zip
match_zip_or_postcode)
);
our %EXPORT_TAGS = (
# regexp common is correctly empty here, because we handle the case on the fly with the import function below.
regexp_common => [],
closures => [ @closures, @FVs ],
validators => [qw/
valid_american_phone
valid_cc_exp
valid_cc_number
valid_cc_type
valid_email
valid_ip_address
valid_phone
valid_postcode
valid_province
valid_state
valid_state_or_province
valid_zip
valid_zip_or_postcode
/],
matchers => [qw/
match_american_phone
match_cc_exp
match_cc_number
match_cc_type
match_email
match_ip_address
match_phone
match_postcode
match_province
match_state
match_state_or_province
match_zip
match_zip_or_postcode
/],
);
sub import {
# This is Regexp::Common support.
# Here we are handling cases that look like this:
#
# my_field => FV_foo_bar(-zoo=>'queue'),
if (grep { m/^:regexp_common$/ } @_) {
require Regexp::Common;
import Regexp::Common 'RE_ALL';
for my $sub (grep { m/^RE_/} keys %Data::FormValidator::Constraints:: ) {
no strict 'refs';
my $new_name = $sub;
$new_name =~ s/^RE_/FV_/;
*{caller() . "::$new_name"} = sub {
my @params = @_;
return sub {
my $dfv = shift;
$dfv->name_this($new_name) unless $dfv->get_current_constraint_name();
no strict "refs";
my $re = &$sub(-keep=>1,@params);
my ($match) = ($dfv->get_current_constraint_value =~ qr/^($re)$/);
return $dfv->untainted_constraint_value($match);
}
}
}
}
Data::FormValidator::Constraints->export_to_level(1,@_);
}
}
# sub DESTROY {}
=pod
=head1 NAME
Data::FormValidator::Constraints - Basic sets of constraints on input profile.
=head1 SYNOPSIS
use Data::FormValidator::Constraints qw(:closures);
In an Data::FormValidator profile:
constraint_methods => {
email => email(),
phone => american_phone(),
first_names => {
constraint_method => FV_max_length(3),
name => 'my_custom_name',
},
},
msgs => {
constraints => {
my_custom_name => 'My message',
},
},
=head1 DESCRIPTION
These are the builtin constraints that can be specified by name in the input
profiles.
Be sure to check out the SEE ALSO section for even more pre-packaged
constraints you can use.
=cut
sub AUTOLOAD {
my $name = $AUTOLOAD;
no strict qw/refs/;
$name =~ m/^(.*::)(valid_|RE_)(.*)/;
my ($pkg,$prefix,$sub) = ($1,$2,$3);
#warn "hello! my ($pkg,$prefix,$sub) = ($1,$2,$3);";
# Since all the valid_* routines are essentially identical we're
# going to generate them dynamically from match_ routines with the same names.
if ((defined $prefix) and ($prefix eq 'valid_')) {
return defined &{$pkg.'match_' . $sub}(@_);
}
}
=head2 FV_length_between(1,23)
=head2 FV_max_length(23)
=head2 FV_min_length(1)
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),
}
Specify a length constraint for a field.
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 C<length_between>, C<min_length>, or C<max_length> will be set,
corresponding to the function name you choose.
The checks are all inclusive, so a max length of '100' will allow the length 100.
Length is measured in perl characters as opposed to bytes or anything else.
This constraint I<will> 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.
=cut
sub FV_length_between {
my ($min,$max) = @_;
if (not (defined $min and defined $max)) {
croak "min and max are required";
}
return sub {
my ($dfv,$value) = @_;
$dfv->name_this('length_between') unless $dfv->get_current_constraint_name();
return undef if ( ( length($value) > $max ) || ( length($value) < $min) );
# Use a regexp to untaint
$value=~/(.*)/s;
return $dfv->untainted_constraint_value($1);
}
}
sub FV_max_length {
my ($max) = @_;
croak "max is required" unless defined $max;
return sub {
my ($dfv,$value) = @_;
$dfv->name_this('max_length') unless $dfv->get_current_constraint_name();
return undef if ( length($value) > $max );
# Use a regexp to untaint
$value=~/(.*)/s;
return $dfv->untainted_constraint_value($1);
}
}
sub FV_min_length {
my ($min) = @_;
croak "min is required" unless defined $min;
return sub {
my ($dfv,$value) = @_;
$dfv->name_this('min_length') unless $dfv->get_current_constraint_name();
return undef if ( length($value) < $min );
# Use a regexp to untaint
$value=~/(.*)/s;
return $dfv->untainted_constraint_value($1);
}
}
=head2 FV_eq_with
use Data::FormValidator::Constraints qw( FV_eq_with );
constraint_methods => {
password => FV_eq_with('password_confirm'),
}
Compares the current field to another field.
A constraint name of C<eq_with> will be set.
=cut
sub FV_eq_with {
my ($other_field) = @_;
return sub {
my $dfv = shift;
$dfv->name_this('eq_with') unless $dfv->get_current_constraint_name();
my $curr_val = $dfv->get_current_constraint_value;
my $data = $dfv->get_filtered_data;
# Sometimes the data comes through both ways...
my $other_val = (ref $data->{$other_field}) ? $data->{$other_field}[0] : $data->{$other_field};
return ($curr_val eq $other_val);
}
}
=head2 FV_num_values
use Data::FormValidator::Constraints qw ( FV_num_values );
constraint_methods => {
attachments => FV_num_values(4),
}
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 C<num_values> will be set.
=cut
sub FV_num_values {
my $size = shift || croak 'size argument is required';
return sub {
my $dfv = shift;
$dfv->name_this('num_values');
my $param = $dfv->get_current_constraint_field();
my $value = $dfv->get_filtered_data()->{$param};
# If there's an arrayref of values provided, test the number of them found
# against the number of them of required
if (defined $value and ref $value eq 'ARRAY') {
my $num_values_found = scalar @$value;
return ($num_values_found == $size);
}
# If a size of 1 was requested, there was not an arrayref of values,
# there must be exactly one value.
elsif ($size == 1) {
return 1;
}
# Any other case is failure.
else {
return 0;
}
}
}
=head2 FV_num_values_between
use Data::FormValidator::Constraints qw ( FV_num_values_between );
constraint_methods => {
attachments => FV_num_values_between(1,4),
}
Checks that the number of values in the array named by this param is between
the supplied bounds (inclusively).
A constraint name of C<num_values_between> will be set.
=cut
sub FV_num_values_between {
my ($min, $max) = @_;
croak 'min and max arguments are required' unless $min && $max;
return sub {
my $dfv = shift;
$dfv->name_this('num_values_between');
my $param = $dfv->get_current_constraint_field();
my $value = $dfv->get_filtered_data()->{$param};
my $num_values = scalar @$value;
return ($num_values >= $min) && ($num_values <= $max) if ref $value eq 'ARRAY';
return 1 if $min == 0 && $max >= 2; # scalar, size could be 1
return 0; # scalar, size can't be 1
}
}
=head2 email
Checks if the email LOOKS LIKE an email address. This should be sufficient
99% of the time.
Look elsewhere if you want something super fancy that matches every possible variation
that is valid in the RFC, or runs out and checks some MX records.
=cut
# Many of the following validators are taken from
# MiniVend 3.14. (http://www.minivend.com)
# Copyright 1996-1999 by Michael J. Heins <mike@heins.net>
sub match_email {
my $in_email = shift;
require Email::Valid;
my $valid_email;
# The extra check that the result matches the input prevents
# an address like this from being considered valid: Joe Smith <joe@smith.com>
if ( ($valid_email = Email::Valid->address($in_email) )
and ($valid_email eq $in_email)) {
return $valid_email;
}
else {
return undef;
}
}
my $state = <<EOF;
AL AK AZ AR CA CO CT DE FL GA HI ID IL IN IA KS KY LA ME MD
MA MI MN MS MO MT NE NV NH NJ NM NY NC ND OH OK OR PA PR RI
SC SD TN TX UT VT VA WA WV WI WY DC AP FP FPO APO GU VI
EOF
my $province = <<EOF;
AB BC MB NB NF NL NS NT NU ON PE QC SK YT YK
EOF
=head2 state_or_province
This one checks if the input correspond to an american state or a canadian
province.
=cut
sub match_state_or_province {
my $match;
if ($match = match_state(@_)) {
return $match;
}
else {
return match_province(@_);
}
}
=head2 state
This one checks if the input is a valid two letter abbreviation of an
American state.
=cut
sub match_state {
my $val = shift;
if ($state =~ /\b($val)\b/i) {
return $1;
}
else { return undef; }
}
=head2 province
This checks if the input is a two letter Canadian province
abbreviation.
=cut
sub match_province {
my $val = shift;
if ($province =~ /\b($val)\b/i) {
return $1;
}
else { return undef; }
}
=head2 zip_or_postcode
This constraints checks if the input is an American zipcode or a
Canadian postal code.
=cut
sub match_zip_or_postcode {
my $match;
if ($match = match_zip(@_)) {
return $match;
}
else {
return match_postcode(@_)
};
}
=pod
=head2 postcode
This constraints checks if the input is a valid Canadian postal code.
=cut
sub match_postcode {
my $val = shift;
#$val =~ s/[_\W]+//g;
if ($val =~ /^([ABCEGHJKLMNPRSTVXYabceghjklmnprstvxy][_\W]*\d[_\W]*[A-Za-z][_\W]*[- ]?[_\W]*\d[_\W]*[A-Za-z][_\W]*\d[_\W]*)$/) {
return $1;
}
else { return undef; }
}
=head2 zip
This input validator checks if the input is a valid american zipcode :
5 digits followed by an optional mailbox number.
=cut
sub match_zip {
my $val = shift;
if ($val =~ /^(\s*\d{5}(?:[-]\d{4})?\s*)$/) {
return $1;
}
else { return undef; }
}
=head2 phone
This one checks if the input looks like a phone number, (if it
contains at least 6 digits.)
=cut
sub match_phone {
my $val = shift;
if ($val =~ /^((?:\D*\d\D*){6,})$/) {
return $1;
}
else { return undef; }
}
=head2 american_phone
This constraints checks if the number is a possible North American style
of phone number : (XXX) XXX-XXXX. It has to contains 7 or more digits.
=cut
sub match_american_phone {
my $val = shift;
if ($val =~ /^((?:\D*\d\D*){7,})$/) {
return $1;
}
else { return undef; }
}
=head2 cc_number
This constraint references the value of a credit card type field.
constraint_methods => {
cc_no => cc_number({fields => ['cc_type']}),
}
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.
This functions is only good at catching typos. IT DOESN'T
CHECK IF THERE IS AN ACCOUNT ASSOCIATED WITH THE NUMBER.
=cut
# This one is taken from the contributed program to
# MiniVend by Bruce Albrecht
# XXX raise exception on bad/missing params?
sub cc_number {
my $attrs = shift;
return undef unless $attrs && ref($attrs) eq 'HASH'
&& exists $attrs->{fields} && ref($attrs->{fields}) eq 'ARRAY';
my ($cc_type_field) = @{ $attrs->{fields} };
return undef unless $cc_type_field;
return sub {
my $dfv = shift;
my $data = $dfv->get_filtered_data;
return match_cc_number(
$dfv->get_current_constraint_value,
$data->{$cc_type_field}
);
};
}
sub match_cc_number {
my ( $the_card, $card_type ) = @_;
my $orig_card = $the_card; #used for return match at bottom
my ($index, $digit, $product);
my $multiplier = 2; # multiplier is either 1 or 2
my $the_sum = 0;
return undef if length($the_card) == 0;
# check card type
return undef unless $card_type =~ /^[admv]/i;
return undef if ($card_type =~ /^v/i && substr($the_card, 0, 1) ne "4") ||
($card_type =~ /^m/i && substr($the_card, 0, 1) ne "5") ||
($card_type =~ /^d/i && substr($the_card, 0, 4) ne "6011") ||
($card_type =~ /^a/i && substr($the_card, 0, 2) ne "34" &&
substr($the_card, 0, 2) ne "37");
# check for valid number of digits.
$the_card =~ s/\s//g; # strip out spaces
return undef if $the_card !~ /^\d+$/;
$digit = substr($the_card, 0, 1);
$index = length($the_card)-1;
return undef if ($digit == 3 && $index != 14) ||
($digit == 4 && $index != 12 && $index != 15) ||
($digit == 5 && $index != 15) ||
($digit == 6 && $index != 13 && $index != 15);
# calculate checksum.
for ($index--; $index >= 0; $index --)
{
$digit=substr($the_card, $index, 1);
$product = $multiplier * $digit;
$the_sum += $product > 9 ? $product - 9 : $product;
$multiplier = 3 - $multiplier;
}
$the_sum %= 10;
$the_sum = 10 - $the_sum if $the_sum;
# return whether checksum matched.
if ($the_sum == substr($the_card, -1)) {
if ($orig_card =~ /^([\d\s]*)$/) { return $1; }
else { return undef; }
}
else {
return undef;
}
}
=head2 cc_exp
This one checks if the input is in the format MM/YY or MM/YYYY and if
the MM part is a valid month (1-12) and if that date is not in the past.
=cut
sub match_cc_exp {
my $val = shift;
my ($matched_month, $matched_year);
my ($month, $year) = split('/', $val);
return undef if $month !~ /^(\d+)$/;
$matched_month = $1;
return undef if $year !~ /^(\d+)$/;
$matched_year = $1;
return undef if $month <1 || $month > 12;
$year += ($year < 70) ? 2000 : 1900 if $year < 1900;
my @now=localtime();
$now[5] += 1900;
return undef if ($year < $now[5]) || ($year == $now[5] && $month <= $now[4]);
return "$matched_month/$matched_year";
}
=head2 cc_type
This one checks if the input field starts by M(asterCard), V(isa),
A(merican express) or D(iscovery).
=cut
sub match_cc_type {
my $val = shift;
if ($val =~ /^([MVAD].*)$/i) { return $1; }
else { return undef; }
}
=head2 ip_address
This checks if the input is formatted like a dotted decimal IP address (v4).
For other kinds of IP address method, See L<Regexp::Common::net> which provides
several more options. L<REGEXP::COMMON SUPPORT> explains how we easily integrate
with Regexp::Common.
=cut
# contributed by Juan Jose Natera Abreu <jnatera@net-uno.net>
sub match_ip_address {
my $val = shift;
if ($val =~ m/^((\d+)\.(\d+)\.(\d+)\.(\d+))$/) {
if
(($2 >= 0 && $2 <= 255) && ($3 >= 0 && $3 <= 255) && ($4 >= 0 && $4 <= 255) && ($5 >= 0 && $5 <= 255)) {
return $1;
}
else { return undef; }
}
else { return undef; }
}
1;
__END__
=head1 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:
constraint_methods => {
first_names => {
constraint_method => FV_max_length(3),
name => 'custom_length',
}
},
=head1 REGEXP::COMMON SUPPORT
Data::FormValidator also includes built-in support for using any of regular expressions
in L<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:
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=>' '),
}
Notice that the routines are named with the prefix "FV_" instead of "RE_" 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.
Be sure to check out the L<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.
=head1 PROCEDURAL INTERFACE
You may also call these functions directly through the procedural interface by
either importing them directly or importing the whole I<:validators> group.
This is useful if you want to use the built-in validators out of the usual
profile specification interface.
For example, if you want to access the I<email> validator
directly, you could either do:
use Data::FormValidator::Constraints (qw/valid_email/);
or
use Data::FormValidator::Constraints (:validators);
if (valid_email($email)) {
# do something with the email address
}
Notice that when you call validators directly, you'll need to prefix the
validator name with "valid_"
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 I<:matchers> group. For example if you want to untaint a
value with the I<email> validator directly you may:
if ($email = match_email($email)) {
system("echo $email");
}
else {
die "Unable to validate email";
}
Notice that when you call validators directly and want them to return an
untainted value, you'll need to prefix the validator name with "match_"
=pod
=head1 WRITING YOUR OWN CONSTRAINT ROUTINES
=head2 New School Constraints Overview
This is the current recommended way to write constraints. See also L<Old School Constraints>.
The most flexible way to create constraints to use closures-- a normal seeming
outer subroutine which returns a customized DFV method subroutine as a result.
It's easy to do. These "constraint methods" can be named whatever you like, and
imported normally into the name space where the profile is located.
Let's look at an example.
# Near your profile
# Of course, you don't have to export/import if your constraints are in the same
# package as the profile.
use My::Constraints 'coolness';
# In your profile
constraint_methods => {
email => email(),
prospective_date => coolness( 40, 60,
{fields => [qw/personality smarts good_looks/]}
),
}
Let's look at how this complex C<coolness> 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.
Here's what the code might look like:
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 'msgs' system.
$dfv->name_this('coolness');
# value of 'prospective_date' 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 );
}
}
=head2 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.
See also the C<validator_packages> option in the input profile, for loading
sets of old school constraints from other packages.
Old school constraint routines are named two ways. Some are named with the
prefix C<match_> while others start with C<valid_>. The difference is that the
C<match_> routines are built to untaint the data and return a safe version of
it if it validates, while C<valid_> routines simply return a true value if the
validation succeeds and false otherwise.
It is preferable to write C<match_> routines that untaint data for the extra
security benefits. Plus, Data::FormValidator will AUTOLOAD a C<valid_> version
if anyone tries to use it, so you only need to write one routine to cover both
cases.
Usually constraint routines only need one input, the value being specified.
However, sometimes more than one value is needed.
B<Example>:
image_field => {
constraint_method => 'max_image_dimensions',
params => [\100,\200],
},
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
C<params> array. Strings will be replaced by the values of fields with the same names,
and references will be passed directly.
In addition to C<constraint_method>, there is also an even older technique using
the name C<constraint> instead. Routines that are designed to work with
C<constraint> I<don't> 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 C<constraint_regexp_map>.
=head2 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.
=head3 get_input_data()
Returns the raw input data. This may be a CGI object if that's what
was used in the constraint routine.
B<Examples:>
# Raw and uncensored
my $data = $self->get_input_data;
# tamed to be a hashref, if it wasn't already
my $data = $self->get_input_data( as_hashref => 1 );
=head3 get_filtered_data()
my $data = $self->get_filtered_data;
Returns the valid filtered data as a hashref, regardless of whether
it started out as a CGI.pm compatible object. Multiple values are
expressed as array references.
=head3 get_current_constraint_field()
Returns the name of the current field being tested in the constraint.
B<Example>:
my $field = $self->get_current_constraint_field;
This reduces the number of parameters that need to be passed into the routine
and allows multi-valued constraints to be used with C<constraint_regexp_map>.
For complete examples of multi-valued constraints, see L<Data::FormValidator::Constraints::Upload>
=head3 get_current_constraint_value()
Returns the name of the current value being tested in the constraint.
B<Example>:
my $value = $self->get_current_constraint_value;
This reduces the number of parameters that need to be passed into the routine
and allows multi-valued constraints to be used with C<constraint_regexp_map>.
=head3 get_current_constraint_name()
Returns the name of the current constraint being applied
B<Example>:
my $value = $self->get_current_constraint_name;
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 L<Regexp::Commmon>
regular expressions.
=head3 untainted_constraint_value()
return $dfv->untainted_constraint_value($match);
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.
=head3 name_this()
=head3 set_current_constraint_name()
Sets the name of the current constraint being applied.
B<Example>:
sub my_constraint {
my @outer_params = @_;
return sub {
my $dfv = shift;
$dfv->set_current_constraint_name('my_constraint');
my @params = @outer_params;
# do something constraining here...
}
}
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 DFV object
that will be used later. See Data::FormValidator::Constraints::Upload for an
example.
C<name_this> is a provided as a shorter synonym.
The C<meta()> method may also be useful to communicate meta data that
may have been found. See L<Data::FormValidator::Results> for documentation
of that method.
=head1 BACKWARDS COMPATIBILITY
Prior to Data::FormValidator 4.00, constraints were specified a bit differently.
This older style is still supported.
It was not necessary to explicitly load some constraints into your name space,
and the names were given as strings, like this:
constraints => {
email => 'email',
fax => 'american_phone',
phone => 'american_phone',
state => 'state',
my_ip_address => 'RE_net_IPv4',
other_ip => {
constraint => 'RE_net_IPv4',
params => [ \'-sep'=> \' ' ],
},
my_cc_no => {
constraint => 'cc_number',
params => [qw/cc_no cc_type/],
}
},
=head1 SEE ALSO
=head2 Constraints available in other modules
=over
=item L<Data::FormValidator::Constraints::Upload> - validate the bytes, format and dimensions of file uploads
=item L<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.
=item L<Data::FormValidator::Constraints::Dates> - the original DFV date constraint module. Try the newer one first!
=item L<Data::FormValidator::Constraints::Japanese> - Japan-specific constraints
=item L<Data::FormValidator::Constraints::MethodsFactory> - a useful collection of tools generate more complex constraints. Recommended!
=back
=head2 Related modules in this package
=over
=item L<Data::FormValidator::Filters> - transform data before constraints are applied
=item L<Data::FormValidator::ConstraintsFactory> - This is a historical collection of constraints that suffer from cumbersome names. They are worth reviewing though-- C<make_and_constraint> will allow 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 L<Data::FormValidator::Constraints::MethodsFactory>.
=item L<Data::FormValidator>
=back
=head1 CREDITS
Some of those input validation functions have been taken from MiniVend
by Michael J. Heins
The credit card checksum validation was taken from contribution by
Bruce Albrecht to the MiniVend program.
=head1 AUTHORS
Francis J. Lacoste
Michael J. Heins
Bruce Albrecht
Mark Stosberg
=head1 COPYRIGHT
Copyright (c) 1999 iNsu Innovations Inc.
All rights reserved.
Parts Copyright 1996-1999 by Michael J. Heins
Parts Copyright 1996-1999 by Bruce Albrecht
Parts Copyright 2005-2009 by Mark Stosberg
This program is free software; you can redistribute it and/or modify
it under the terms as perl itself.
=cut
|