{"id":20550197,"url":"https://github.com/dnmfarrell/data-formvalidator","last_synced_at":"2025-04-14T11:17:04.840Z","repository":{"id":47088091,"uuid":"80074800","full_name":"dnmfarrell/Data-FormValidator","owner":"dnmfarrell","description":null,"archived":false,"fork":false,"pushed_at":"2023-01-24T19:21:25.000Z","size":3145,"stargazers_count":3,"open_issues_count":3,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-14T11:17:04.118Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dnmfarrell.png","metadata":{"files":{"readme":"README.pod","changelog":"Changes","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-26T01:11:20.000Z","updated_at":"2023-04-11T15:19:48.000Z","dependencies_parsed_at":"2023-02-14T00:40:20.231Z","dependency_job_id":null,"html_url":"https://github.com/dnmfarrell/Data-FormValidator","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnmfarrell%2FData-FormValidator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnmfarrell%2FData-FormValidator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnmfarrell%2FData-FormValidator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnmfarrell%2FData-FormValidator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dnmfarrell","download_url":"https://codeload.github.com/dnmfarrell/Data-FormValidator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248868767,"owners_count":21174758,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-16T02:23:48.915Z","updated_at":"2025-04-14T11:17:04.780Z","avatar_url":"https://github.com/dnmfarrell.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"=pod\n\n=head1 NAME\n\nData::FormValidator - Validates user input (usually from an HTML form) based\non input profile.\n\n=head1 SYNOPSIS\n\n use Data::FormValidator;\n\n my $results = Data::FormValidator-\u003echeck(\\%input_hash, \\%dfv_profile);\n\n if ($results-\u003ehas_invalid or $results-\u003ehas_missing) {\n     # do something with $results-\u003einvalid, $results-\u003emissing\n     # or  $results-\u003emsgs\n }\n else {\n     # do something with $results-\u003evalid\n }\n\n\n=head1 DESCRIPTION\n\nData::FormValidator's main aim is to make input validation expressible in a\nsimple format.\n\nData::FormValidator lets you define profiles which declare the\nrequired and optional fields and any constraints they might have.\n\nThe results are provided as an object which makes it easy to handle\nmissing and invalid results, return error messages about which constraints\nfailed, or process the resulting valid data.\n\n\n=cut\n\n=head1 VALIDATING INPUT\n\n=head2 check()\n\n my $results = Data::FormValidator-\u003echeck(\\%input_hash, \\%dfv_profile);\n\nC\u003ccheck\u003e is the recommended method to use to validate forms. It returns its results as a\nL\u003cData::FormValidator::Results|Data::FormValidator::Results\u003e object.  A\ndeprecated method C\u003cvalidate\u003e is also available, returning its results as an\narray described below.\n\n use Data::FormValidator;\n my $results = Data::FormValidator-\u003echeck(\\%input_hash, \\%dfv_profile);\n\nHere, C\u003ccheck()\u003e is used as a class method, and takes two required parameters.\n\nThe first a reference to the data to be be validated. This can either be a hash\nreference, or a CGI.pm-like object. In particular, the object must have a param()\nmethod that works like the one in CGI.pm does. CGI::Simple and Apache::Request\nobjects are known to work in particular. Note that if you use a hash reference,\nmultiple values for a single key should be presented as an array reference.\n\nThe second argument is a reference to the profile you are validating.\n\n=head2 validate()\n\n    my( $valids, $missings, $invalids, $unknowns ) =\n        Data::FormValidator-\u003evalidate( \\%input_hash, \\%dfv_profile);\n\nC\u003cvalidate()\u003e provides a deprecated alternative to C\u003ccheck()\u003e. It has the same input\nsyntax, but returns a four element array, described as follows\n\n=over\n\n=item valids\n\nThis is a hash reference to the valid fields which were submitted in\nthe data. The data may have been modified by the various filters specified.\n\n=item missings\n\nThis is a reference to an array which contains the name of the missing\nfields. Those are the fields that the user forget to fill or filled\nwith spaces. These fields may comes from the I\u003crequired\u003e list or the\nI\u003cdependencies\u003e list.\n\n=item invalids\n\nThis is a reference to an array which contains the name of the fields which\nfailed one or more of their constraint checks. If there are no invalid fields,\nan empty arrayref will be returned.\n\nFields defined with multiple constraints will have an array ref returned in the\n@invalids array instead of a string. The first element in this array is the\nname of the field, and the remaining fields are the names of the failed\nconstraints.\n\n=item unknowns\n\nThis is a list of fields which are unknown to the profile. Whether or\nnot this indicates an error in the user input is application\ndependent.\n\n=back\n\n=head2 new()\n\nUsing C\u003cnew()\u003e is only needed for advanced usage, including these cases:\n\n=over\n\n=item o\n\nLoading more than one profile at a time. Then you can select the profile you\nwant by name later with C\u003ccheck()\u003e. Here's an example:\n\n my $dfv = Data::FormValidator-\u003enew({\n    profile_1 =\u003e { # usual profile definition here },\n    profile_2 =\u003e { # another profile definition },\n });\n\n\nAs illustrated, multiple profiles are defined through a hash ref whose keys point\nto profile definitions.\n\nYou can also load several profiles from a file, by defining several profiles as shown above\nin an external file. Then just pass in the name of the file:\n\n my $dfv = Data::FormValidator-\u003enew('/path/to/profiles.pl');\n\nIf the input profile is specified as a file name, the profiles will be reread\neach time that the disk copy is modified.\n\nNow when calling C\u003ccheck()\u003e, you just need to supply the profile name:\n\n my $results = $dfv-\u003echeck(\\%input_hash,'profile_1');\n\n=item o\n\nApplying defaults to more than one input profile. There are some parts\nof the validation profile that you might like to re-use for many form\nvalidations.\n\nTo facilitate this, C\u003cnew()\u003e takes a second argument, a hash reference. Here\nthe usual input profile definitions can be made. These will act as defaults for\nany subsequent calls to C\u003ccheck()\u003e on this object.\n\nCurrently the logic for this is very simple. Any definition of a key in your\nvalidation profile will completely overwrite your default value.\n\nThis means you can't define two keys for C\u003cconstraint_regexp_map\u003e and expect\nthey will always be there. This kind of feature may be added in the future.\n\nThe exception here is definitions for your C\u003cmsgs\u003e key. You will safely  be\nable to define some defaults for the top level keys within C\u003cmsgs\u003e and not have\nthem clobbered just because C\u003cmsgs\u003e was defined in a validation profile.\n\nOne way to use this feature is to create your own sub-class that always provides\nyour defaults to C\u003cnew()\u003e.\n\nAnother option is to create your own wrapper routine which provides these defaults to\nC\u003cnew()\u003e.  Here's an example of a routine you might put in a\nL\u003cCGI::Application|CGI::Application\u003e super-class to make use of this feature:\n\n # Always use the built-in CGI object as the form data\n # and provide some defaults to new constructor\n sub check_form {\n     my $self = shift;\n     my $profile = shift\n        || die 'check_form: missing required profile';\n\n     require Data::FormValidator;\n     my $dfv = Data::FormValidator-\u003enew({},{\n        # your defaults here\n     });\n     return $dfv-\u003echeck($self-\u003equery,$profile);\n }\n\n\n=back\n\n\n=cut\n\n=head1 INPUT PROFILE SPECIFICATION\n\nAn input profile is a hash reference containing one or more of the following\nkeys.\n\nHere is a very simple input profile. Examples of more advanced options are\ndescribed below.\n\n    use Data::FormValidator::Constraints qw(:closures);\n\n    my $profile = {\n        optional =\u003e [qw( company\n                         fax\n                         country )],\n\n        required =\u003e [qw( fullname\n                         phone\n                         email\n                         address )],\n\n        constraint_methods =\u003e {\n            email =\u003e email(),\n        }\n    };\n\n\nThat defines some fields as optional, some as required, and defines that the\nfield named 'email' must pass the constraint named 'email'.\n\nHere is a complete list of the keys available in the input profile, with\nexamples of each.\n\n=head2 required\n\nThis is an array reference which contains the name of the fields which are\nrequired. Any fields in this list which are not present or contain only\nspaces will be reported as missing.\n\n=head2 required_regexp\n\n required_regexp =\u003e qr/city|state|zipcode/,\n\nThis is a regular expression used to specify additional field names for which values\nwill be required.\n\n=head2 require_some\n\n require_some =\u003e {\n    # require any two fields from this group\n    city_or_state_or_zipcode =\u003e [ 2, qw/city state zipcode/ ],\n }\n\nThis is a reference to a hash which defines groups of fields where 1 or more\nfields from the group should be required, but exactly which fields doesn't\nmatter. The keys in the hash are the group names.  These are returned as\n\"missing\" unless the required number of fields from the group has been filled\nin. The values in this hash are array references. The first element in this\narray should be the number of fields in the group that is required. If the\nfirst field in the array is not an a digit, a default of \"1\" will be used.\n\n=head2 optional\n\n optional =\u003e [qw/meat coffee chocolate/],\n\nThis is an array reference which contains the name of optional fields.\nThese are fields which MAY be present and if they are, they will be\nchecked for valid input. Any fields not in optional or required list\nwill be reported as unknown.\n\n=head2 optional_regexp\n\n optional_regexp =\u003e qr/_province$/,\n\nThis is a regular expression used to specify additional fields which are\noptional. For example, if you wanted all fields names that begin with I\u003cuser_\u003e\nto be optional, you could use the regular expression, /^user_/\n\n=head2 dependencies\n\n dependencies   =\u003e {\n\n    # If cc_no is entered, make cc_type and cc_exp required\n    \"cc_no\" =\u003e [ qw( cc_type cc_exp ) ],\n\n    # if pay_type eq 'check', require check_no\n    \"pay_type\" =\u003e {\n        check =\u003e [ qw( check_no ) ],\n     }\n\n    # if cc_type is VISA or MASTERCARD require CVV\n    \"cc_type\" =\u003e sub {\n        my $dfv  = shift;\n        my $type = shift;\n\n        return [ 'cc_cvv' ] if ($type eq \"VISA\" || $type eq \"MASTERCARD\");\n        return [ ];\n    },\n },\n\nThis is for the case where an optional field has other requirements.  The\ndependent fields can be specified with an array reference.\n\nIf the dependencies are specified with a hash reference then the additional\nconstraint is added that the optional field must equal a key for the\ndependencies to be added.\n\nIf the dependencies are specified as a code reference then the code will be\nexecuted to determine the dependent fields.  It is passed two parameters,\nthe object and the value of the field, and it should return an array reference\ncontaining the list of dependent fields.\n\nAny fields in the dependencies list that are missing when the target is present\nwill be reported as missing.\n\n=head2 dependency_groups\n\n dependency_groups  =\u003e {\n     # if either field is filled in, they all become required\n     password_group =\u003e [qw/password password_confirmation/],\n }\n\nThis is a hash reference which contains information about groups of\ninterdependent fields. The keys are arbitrary names that you create and\nthe values are references to arrays of the field names in each group.\n\n=head2 dependencies_regexp\n\n dependencies_regexp =\u003e {\n    qr/Line\\d+\\_ItemType$/ =\u003e sub {\n       my $dfv = shift;\n       my $itemtype = shift;\n       my $field = shift;\n\n       if ($type eq 'NeedsBatteries') {\n          my ($prefix, $suffix) = split(/\\_/, $field);\n\n          return([$prefix . '_add_batteries]);\n       } else {\n          return([]);\n       }\n    },\n },\n\nThis is a regular expression used to specify additional fields which are\ndependent. For example, if you wanted to add dependencies for all fields which\nmeet a certain criteria (such as multiple items in a shopping cart) where you\ndo not know before hand how many of such fields you may have.\n\n=head2 dependent_optionals\n\n dependent_optionals =\u003e {\n    # If delivery_address is specified then delivery_notes becomes optional\n    \"delivery_address\" =\u003e [ qw( delivery_notes ) ],\n\n    # if delivery_type eq 'collection', collection_notes becomes optional\n    \"delivery_type\" =\u003e {\n       collection =\u003e [ qw( collection_notes ) ],\n    }\n\n    # if callback_type is \"phone\" or \"email\" then additional_notes becomes optional\n    \"callback_type\" =\u003e sub {\n       my $dfv = shift;\n       my $type = shift;\n\n       if ($type eq 'phone' || $type eq 'email') {\n          return(['additional_notes']);\n       } else {\n          return([]);\n       }\n    },\n },\n\nThis is for the case where an optional field can trigger other optional fields.\nThe dependent optional fields can be specified with an array reference.\n\nIf the dependent optional fields are specified with a hash reference, then an\nadditional constraint is added that the optional field must equal a key for the\nadditional optional fields to be added.\n\nIf the dependent optional fields are specified as a code reference then the\ncode will be executed to determine the additional optional fields. It is passed\ntwo parameters, the object and the value of the field, and it should return an\narray reference containing the list of additional optional fields.\n\n=head2 dependent_require_some\n\n dependent_require_some =\u003e {\n    # require any fields from this group if AddressID is \"new\"\n    AddressID =\u003e sub {\n       my $dfv = shift;\n       my $value = shift;\n\n       if ($value eq 'new') {\n          return({\n             house_name_or_number =\u003e [ 1, 'HouseName', 'HouseNumber' ],\n          });\n       } else {\n          return;\n       }\n    },\n }\n\nSometimes a field will need to trigger additional dependencies but you only\nrequire some of the fields. You cannot set them all to be dependent as you\nmight only have some of them, and you cannot set them all to be optional as\nyou must have some of them. This method allows you to specify this in a\nsimilar way to the equire_some method but dependent upon other values. In\nthe example above if the AddressID submitted is \"new\" then at least 1 of\nHouseName and HouseNumber must also be supplied. See require_some for the\nvalid options for the return.\n\n=head2 defaults\n\n defaults =\u003e {\n     country =\u003e \"USA\",\n },\n\nThis is a hash reference where keys are field names and\nvalues are defaults to use if input for the field is missing.\n\nThe values can be code refs which will be used to calculate the\nvalue if needed. These code refs will be passed in the DFV::Results\nobject as the only parameter.\n\nThe defaults are set shortly before the constraints are applied, and\nwill be returned with the other valid data.\n\n=head2 defaults_regexp_map\n\n  defaults_regexp_map =\u003e {\n      qr/^opt_/ =\u003e 1,\n  },\n\nThis is a hash reference that maps  regular expressions to default values to\nuse for matching optional or required fields.\n\nIt's useful if you have generated many checkbox fields with the similar names.\nSince checkbox fields submit nothing at all when they are not checked, it's\nuseful to set defaults for them.\n\nNote that it doesn't make sense to use a default for a field handled by\nC\u003coptional_regexp\u003e or C\u003crequired_regexp\u003e.  When the field is not submitted,\nthere is no way to know that it should be optional or required, and thus there's\nno way to know that a default should be set for it.\n\n=head2 filters\n\n # trim leading and trailing whitespace on all fields\n filters       =\u003e ['trim'],\n\nThis is a reference to an array of filters that will be applied to ALL optional\nand required fields, B\u003cbefore\u003e any constraints are applied.\n\nThis can be the name of a built-in filter\n(trim,digit,etc) or an anonymous subroutine which should take one parameter,\nthe field value and return the (possibly) modified value.\n\nFilters modify the data returned through the results object, so use them carefully.\n\nSee L\u003cData::FormValidator::Filters\u003e for details on the built-in filters.\n\n=head2 field_filters\n\n field_filters =\u003e {\n     cc_no =\u003e ['digit'],\n },\n\nA hash ref with field names as keys. Values are array references of built-in\nfilters to apply (trim,digit,etc) or an anonymous subroutine which should take\none parameter, the field value and return the (possibly) modified value.\n\nFilters are applied B\u003cbefore\u003e any constraints are applied.\n\nSee L\u003cData::FormValidator::Filters\u003e for details on the built-in filters.\n\n=head2 field_filter_regexp_map\n\n field_filter_regexp_map =\u003e {\n     # Upper-case the first letter of all fields that end in \"_name\"\n     qr/_name$/    =\u003e ['ucfirst'],\n },\n\n'field_filter_regexp_map' is used to apply filters to fields that match a\nregular expression.  This is a hash reference where the keys are the regular\nexpressions to use and the values are references to arrays of filters which\nwill be applied to specific input fields. Just as with 'field_filters', you\ncan you use a built-in filter or use a coderef to supply your own.\n\n=head2 constraint_methods\n\n use Data::FormValidator::Constraints qw(:closures);\n\n constraint_methods =\u003e {\n    cc_no      =\u003e cc_number({fields =\u003e ['cc_type']}),\n    cc_type    =\u003e cc_type(),\n    cc_exp     =\u003e cc_exp(),\n  },\n\nA hash ref which contains the constraints that will be used to check whether or\nnot the field contains valid data.\n\nB\u003cNote:\u003e To use the built-in constraints, they need to first be loaded into your\nname space using the syntax above. (Unless you are using the old C\u003cconstraints\u003e key,\ndocumented in L\u003cBACKWARDS COMPATIBILITY\u003e).\n\nThe keys in this hash are field names. The values can be any of the following:\n\n=over\n\n=item o\n\nA named constraint.\n\nB\u003cExample\u003e:\n\n my_zipcode_field     =\u003e zip(),\n\nSee L\u003cData::FormValidator::Constraints\u003e for the details of which\nbuilt-in constraints that are available.\n\n\n=item o\n\nA perl regular expression\n\nB\u003cExample\u003e:\n\n my_zipcode_field   =\u003e qr/^\\d{5}$/, # match exactly 5 digits\n\nIf this field is named in C\u003cuntaint_constraint_fields\u003e or C\u003cuntaint_regexp_map\u003e,\nor C\u003cuntaint_all_constraints\u003e is effective, be aware of the following: If you\nwrite your own regular expressions and only match part of the string then\nyou'll only get part of the string in the valid hash. It is a good idea to\nwrite you own constraints like /^regex$/. That way you match the whole string.\n\n=item o\n\na subroutine reference, to supply custom code\n\nThis will check the input and return true or false depending on the input's validity.\nBy default, the constraint function receives a L\u003cData::FormValidator::Results\u003e\nobject as its first argument, and the value to be validated as the second.  To\nvalidate a field based on more inputs than just the field itself, see\nL\u003cVALIDATING INPUT BASED ON MULTIPLE FIELDS\u003e.\n\nB\u003cExamples\u003e:\n\n # Notice the use of 'pop'--\n # the object is the first arg passed to the method\n # while the value is the second, and last arg.\n my_zipcode_field =\u003e sub { my $val = pop;  return $val =~ '/^\\d{5}$/' },\n\n # OR you can reference a subroutine, which should work like the one above\n my_zipcode_field =\u003e \\\u0026my_validation_routine,\n\n # An example of setting the constraint name.\n my_zipcode_field =\u003e sub {\n    my ($dfv, $val) = @_;\n    $dfv-\u003eset_current_constraint_name('my_constraint_name');\n    return $val =~ '/^\\d{5}$/'\n },\n\n=item o\n\nan array reference\n\nAn array reference is used to apply multiple constraints to a single\nfield. Any of the above options are valid entries the array.\nSee L\u003cMULTIPLE CONSTRAINTS\u003e below.\n\nFor more details see L\u003cVALIDATING INPUT BASED ON MULTIPLE FIELDS\u003e.\n\n=back\n\n=head2 constraint_method_regexp_map\n\n use Data::FormValidator::Constraints qw(:closures);\n\n # In your profile.\n constraint_method_regexp_map =\u003e {\n     # All fields that end in _postcode have the 'postcode' constraint applied.\n     qr/_postcode$/    =\u003e postcode(),\n },\n\nA hash ref where the keys are the regular expressions to\nuse and the values are the constraints to apply.\n\nIf one or more constraints have already been defined for a given field using\nC\u003cconstraint_methods\u003e, C\u003cconstraint_method_regexp_map\u003e will add an additional\nconstraint for that field for each regular expression that matches.\n\n=head2 untaint_all_constraints\n\n untaint_all_constraints =\u003e 1,\n\nIf this field is set, all form data that passes a constraint will be untainted.\nThe untainted data will be returned in the valid hash.  Untainting is based on\nthe pattern match used by the constraint.  Note that some constraint routines\nmay not provide untainting.\n\nSee L\u003cWriting your own constraint routines|Data::FormValidator::Constraints/\"WRITING YOUR OWN CONSTRAINT ROUTINES\"\u003e for more information.\n\nThis is overridden by C\u003cuntaint_constraint_fields\u003e and C\u003cuntaint_regexp_map\u003e.\n\n=head2 untaint_constraint_fields\n\n untaint_constraint_fields =\u003e [qw(zipcode state)],\n\nSpecifies that one or more fields will be untainted if they pass their\nconstraint(s). This can be set to a single field name or an array reference of\nfield names. The untainted data will be returned in the valid hash.\n\nThis overrides the untaint_all_constraints flag.\n\n=head2 untaint_regexp_map\n\n untaint_regexp_map =\u003e [qr/some_field_\\d/],\n\nSpecifies that certain fields will be untainted if they pass their constraints\nand match one of the regular expressions supplied. This can be set to a single\nregex, or an array reference of regexes. The untainted data will be returned\nin the valid hash.\n\nThe above example would untaint the fields named C\u003csome_field_1\u003e, and C\u003csome_field_2\u003e\nbut not C\u003csome_field\u003e.\n\nThis overrides the untaint_all_constraints flag.\n\n=head2 missing_optional_valid\n\n missing_optional_valid =\u003e 1\n\nThis can be set to a true value to cause optional fields with empty values to\nbe included in the valid hash. By default they are not included-- this is the\nhistorical behavior.\n\nThis is an important flag if you are using the contents of an \"update\" form to\nupdate a record in a database. Without using the option, fields that have been\nset back to \"blank\" may fail to get updated.\n\n=head2 validator_packages\n\n # load all the constraints and filters from these modules\n validator_packages =\u003e [qw(Data::FormValidator::Constraints::Upload)],\n\nThis key is used to define other packages which contain constraint routines or\nfilters.  Set this key to a single package name, or an arrayref of several. All\nof its constraint and filter routines  beginning with 'match_', 'valid_' and\n'filter_' will be imported into Data::FormValidator.  This lets you reference\nthem in a constraint with just their name, just like built-in routines.  You\ncan even override the provided validators.\n\nSee L\u003cWriting your own constraint routines|Data::FormValidator::Constraints/\"WRITING YOUR OWN CONSTRAINT ROUTINES\"\u003e\ndocumentation for more information\n\n=head2 msgs\n\nThis key is used to define parameters related to formatting error messages\nreturned to the user.\n\nBy default, invalid fields have the message \"Invalid\" associated with them\nwhile missing fields have the message \"Missing\" associated with them.\n\nIn the simplest case, nothing needs to be defined here, and the default values\nwill be used.\n\nThe default formatting applied is designed for display in an XHTML web page.\nThat formatting is as followings:\n\n    \u003cspan style=\"color:red;font-weight:bold\" class=\"dfv_errors\"\u003e* %s\u003c/span\u003e\n\nThe C\u003c%s\u003e will be replaced with the message. The effect is that the message\nwill appear in bold red with an asterisk before it. This style can be overridden by simply\ndefining \"dfv_errors\" appropriately in a style sheet, or by providing a new format string.\n\nHere's a more complex example that shows how to provide your own default message strings, as well\nas providing custom messages per field, and handling multiple constraints:\n\n msgs =\u003e {\n\n     # set a custom error prefix, defaults to none\n     prefix=\u003e 'error_',\n\n     # Set your own \"Missing\" message, defaults to \"Missing\"\n     missing =\u003e 'Not Here!',\n\n     # Default invalid message, default's to \"Invalid\"\n     invalid =\u003e 'Problematic!',\n\n     # message separator for multiple messages\n     # Defaults to ' '\n     invalid_separator =\u003e ' \u003cbr /\u003e ',\n\n     # formatting string, default given above.\n     format =\u003e 'ERROR: %s',\n\n     # Error messages, keyed by constraint name\n     # Your constraints must be named to use this.\n     constraints =\u003e {\n                     'date_and_time' =\u003e 'Not a valid time format',\n                     # ...\n     },\n\n     # This token will be included in the hash if there are\n     # any errors returned. This can be useful with templating\n     # systems like HTML::Template\n     # The 'prefix' setting does not apply here.\n     # defaults to undefined\n     any_errors =\u003e 'some_errors',\n }\n\nThe hash that's prepared can be retrieved through the C\u003cmsgs\u003e method\ndescribed in the L\u003cData::FormValidator::Results\u003e documentation.\n\n=head2 msgs - callback\n\nI\u003cThis is a new feature. While it expected to be forward-compatible, it hasn't\nyet received the testing the rest of the API has.\u003e\n\nIf the built-in message generation doesn't suit you, it is also possible to\nprovide your own by specifying a code reference:\n\n msgs  =\u003e  \\\u0026my_msgs_callback\n\nThis will be called as a L\u003cData::FormValidator::Results\u003e method.  It may\nreceive as arguments an additional hash reference of control parameters,\ncorresponding to the key names usually used in the C\u003cmsgs\u003e area of the\nprofile. You can ignore this information if you'd like.\n\nIf you have an alternative error message handler you'd like to share, stick in\nthe C\u003cData::FormValidator::ErrMsgs\u003e name space and upload it to CPAN.\n\n=head2 debug\n\nThis method is used to print details about what is going on to STDERR.\n\nCurrently only level '1' is used. It provides information about which\nfields matched constraint_regexp_map.\n\n=head2 A shortcut for array refs\n\nA number of parts of the input profile specification include array references\nas their values.  In any of these places, you can simply use a string if you\nonly need to specify one value. For example, instead of\n\n filters =\u003e [ 'trim' ]\n\nyou can simply say\n\n filters =\u003e 'trim'\n\n=head2 A note on regular expression formats\n\nIn addition to using the preferred method of defining regular expressions\nusing C\u003cqr\u003e, a deprecated style of defining them as strings is also supported.\n\nPreferred:\n\n qr/this is great/\n\nDeprecated, but supported\n\n 'm/this still works/'\n\n=head1 VALIDATING INPUT BASED ON MULTIPLE FIELDS\n\nYou can pass more than one value into a constraint routine.  For that, the\nvalue of the constraint should be a hash reference. If you are creating your\nown routines, be sure to read the section labeled\nL\u003cWRITING YOUR OWN CONSTRAINT ROUTINES\u003e,\nin the Data::FormValidator::Constraints documentation.  It describes\na newer and more flexible syntax.\n\nUsing the original syntax, one key should be named C\u003cconstraint\u003e and should\nhave a value set to the reference of the subroutine or the name of a built-in\nvalidator.  Another required key is C\u003cparams\u003e. The value of the C\u003cparams\u003e key\nis a reference to an array of the other elements to use in the validation. If\nthe element is a scalar, it is assumed to be a field name. The field is known\nto Data::FormValidator, the value will be filtered through any defined filters\nbefore it is passed in.  If the value is a reference, the reference is passed\ndirectly to the routine.  Don't forget to include the name of the field to\ncheck in that list, if you are using this syntax.\n\nB\u003cExample\u003e:\n\n cc_no  =\u003e {\n     constraint  =\u003e \"cc_number\",\n     params         =\u003e [ qw( cc_no cc_type ) ],\n },\n\n\n=head1 MULTIPLE CONSTRAINTS\n\nMultiple constraints can be applied to a single field by defining the value of\nthe constraint to be an array reference. Each of the values in this array can\nbe any of the constraint types defined above.\n\nWhen using multiple constraints it is important to return the name of the\nconstraint that failed so you can distinguish between them. To do that,\neither use a named constraint, or use the hash ref method of defining a\nconstraint and include a C\u003cname\u003e key with a value set to the name of your\nconstraint.  Here's an example:\n\n  my_zipcode_field =\u003e [\n      'zip',\n      {\n        constraint_method =\u003e  '/^406/',\n        name              =\u003e  'starts_with_406',\n      }\n  ],\n\nYou can use an array reference with a single constraint in it if you just want\nto have the name of your failed constraint returned in the above fashion.\n\nRead about the C\u003cvalidate()\u003e function above to see how multiple constraints\nare returned differently with that method.\n\n\n=cut\n\n=pod\n\n=head1 ADVANCED VALIDATION\n\nFor even more advanced validation, you will likely want to read the\ndocumentation for other modules in this distribution, linked below. Also keep\nin mind that the  Data::FormValidator profile structure is just another data\nstructure. There is no reason why it needs to be defined statically. The\nprofile could also be built on the fly with custom Perl code.\n\n=head1 BACKWARDS COMPATIBILITY\n\n=head2 validate()\n\n    my( $valids, $missings, $invalids, $unknowns ) =\n        Data::FormValidator-\u003evalidate( \\%input_hash, \\%dfv_profile);\n\nC\u003cvalidate()\u003e provides a deprecated alternative to C\u003ccheck()\u003e. It has the same input\nsyntax, but returns a four element array, described as follows\n\n=over\n\n=item valids\n\nThis is a hash reference to the valid fields which were submitted in\nthe data. The data may have been modified by the various filters specified.\n\n=item missings\n\nThis is a reference to an array which contains the name of the missing\nfields. Those are the fields that the user forget to fill or filled\nwith spaces. These fields may comes from the I\u003crequired\u003e list or the\nI\u003cdependencies\u003e list.\n\n=item invalids\n\nThis is a reference to an array which contains the name of the fields\nwhich failed one or more of their constraint checks.\n\nFields defined with multiple constraints will have an array ref returned in the\n@invalids array instead of a string. The first element in this array is the\nname of the field, and the remaining fields are the names of the failed\nconstraints.\n\n=item unknowns\n\nThis is a list of fields which are unknown to the profile. Whether or\nnot this indicates an error in the user input is application\ndependent.\n\n=back\n\n=head2 constraints (profile key)\n\nThis is a supported but deprecated profile key. Using C\u003cconstraint_methods\u003e is\nrecommended instead, which provides a simpler, more versatile interface.\n\n constraints =\u003e {\n    cc_no      =\u003e {\n        constraint  =\u003e \"cc_number\",\n        params        =\u003e [ qw( cc_no cc_type ) ],\n    },\n    cc_type    =\u003e \"cc_type\",\n    cc_exp    =\u003e \"cc_exp\",\n  },\n\nA hash ref which contains the constraints that\nwill be used to check whether or not the field contains valid data.\n\nThe keys in this hash are field names. The values can be any of the following:\n\n=over\n\n=item o\n\nA named constraint.\n\nB\u003cExample\u003e:\n\n my_zipcode_field     =\u003e 'zip',\n\nSee L\u003cData::FormValidator::Constraints\u003e for the details of which\nbuilt-in constraints that are available.\n\n=back\n\n=head2 hashref style of specifying constraints\n\nUsing a hash reference to specify a constraint is an older technique\nused to name a constraint or supply multiple parameters.\n\nBoth of these interface issues are now better addressed with C\u003cconstraint_methods\u003e\nand C\u003c$self-\\\u003ename_this('foo')\u003e.\n\n # supply multiple parameters\n cc_no  =\u003e {\n     constraint  =\u003e \"cc_number\",\n     params      =\u003e [ qw( cc_no cc_type ) ],\n },\n\n # name a constraint, useful for returning error messages\n last_name =\u003e {\n     name =\u003e \"ends_in_name\",\n     constraint =\u003e qr/_name$/,\n },\n\nUsing a hash reference for a constraint permits the passing of multiple\narguments. Required arguments are C\u003cconstraint\u003e or C\u003cconstraint_method\u003e.\nOptional arguments are C\u003cname\u003e and C\u003cparams\u003e.\n\nA C\u003cname\u003e on a constraints 'glues' the constraint to its error message\nin the validator profile (refer C\u003cmsgs\u003e section below). If no C\u003cname\u003e is\ngiven then it will default to the value of C\u003cconstraint\u003e or\nC\u003cconstraint_method\u003e IF they are NOT a CODE ref or a RegExp ref.\n\nThe C\u003cparams\u003e value is a reference to an array of the parameters to pass\nto the constraint method.\nIf an element of the C\u003cparams\u003e list is a scalar, it is assumed to be naming\na key of the %input_hash and that value is passed to the routine.\nIf the parameter is a reference, then it is treated literally and passed\nunchanged to the routine.\n\nIf you are using the older C\u003cconstraint\u003e over\nthe new C\u003cconstraint_method\u003e then don't forget to include the name of the\nfield to check in the C\u003cparams\u003e list. C\u003cconstraint_method\u003e provides access\nto this value via the C\u003cget_current_*\u003e methods\n(refer L\u003cData::FormValidator::Constraints\u003e)\n\nFor more details see L\u003cVALIDATING INPUT BASED ON MULTIPLE FIELDS\u003e.\n\n=head2 constraint_regexp_map (profile key)\n\nThis is a supported by deprecated profile key. Using\nC\u003cconstraint_methods_regexp_map\u003e is recommended instead.\n\n constraint_regexp_map =\u003e {\n     # All fields that end in _postcode have the 'postcode' constraint applied.\n     qr/_postcode$/    =\u003e 'postcode',\n },\n\nA hash ref where the keys are the regular expressions to\nuse and the values are the constraints to apply.\n\nIf one or more constraints have already been defined for a given field using\n\"constraints\", constraint_regexp_map will add an additional constraint for that\nfield for each regular expression that matches.\n\n=head1 SEE ALSO\n\nB\u003cOther modules in this distribution:\u003e\n\nL\u003cData::FormValidator::Constraints|Data::FormValidator::Constraints\u003e\n\nL\u003cData::FormValidator::Constraints::Dates|Data::FormValidator::Constraints::Dates\u003e\n\nL\u003cData::FormValidator::Constraints::Upload|Data::FormValidator::Constraints::Upload\u003e\n\nL\u003cData::FormValidator::ConstraintsFactory|Data::FormValidator::ConstraintsFactory\u003e\n\nL\u003cData::FormValidator::Filters|Data::FormValidator::Filters\u003e\n\nL\u003cData::FormValidator::Results|Data::FormValidator::Results\u003e\n\nB\u003cA sample application by the maintainer:\u003e\n\nValidating Web Forms with Perl, L\u003chttp://mark.stosberg.com/Tech/perl/form-validation/\u003e\n\nB\u003cRelated modules:\u003e\n\nL\u003cData::FormValidator::Tutorial|Data::FormValidator::Tutorial\u003e\n\nL\u003cData::FormValidator::Util::HTML|Data::FormValidator::Util::HTML\u003e\n\nL\u003cCGI::Application::Plugin::ValidateRM|CGI::Application::Plugin::ValidateRM\u003e, a\nCGI::Application \u0026 Data::FormValidator glue module\n\nL\u003cHTML::Template::Associate::FormValidator|HTML::Template::Associate::FormValidator\u003e is designed\nto make some kinds of integration with HTML::Template easier.\n\nL\u003cParams::Validate|Params::Validate\u003e is useful for validating function parameters.\n\nL\u003cRegexp::Common|Regexp::Common\u003e,\nL\u003cData::Types|Data::Types\u003e,\nL\u003cData::Verify|Data::Verify\u003e,\nL\u003cEmail::Valid|Email::Valid\u003e,\nL\u003cString::Checker|String::Checker\u003e,\nL\u003cCGI::ArgChecker|CGI::ArgChecker\u003e,\nL\u003cCGI::FormMagick::Validator|CGI::FormMagick::Validator\u003e,\nL\u003cCGI::Validate|CGI::Validate\u003e\n\nB\u003cDocument Translations:\u003e\n\nJapanese: L\u003chttp://perldoc.jp/docs/modules/\u003e\n\nB\u003cDistributions which include Data::FormValidator\u003e\n\nFreeBSD includes a port named B\u003cp5-Data-FormValidator\u003e\n\nDebian GNU/Linux includes a port named B\u003clibdata-formvalidator-perl\u003e\n\n=head1 CREDITS\n\nSome of those input validation functions have been taken from MiniVend\nby Michael J. Heins.\n\nThe credit card checksum validation was taken from contribution by Bruce\nAlbrecht to the MiniVend program.\n\n=head1 BUGS\n\nBug reports and patches are welcome. Reports which include a failing Test::More\nstyle test are helpful will receive priority.\n\nL\u003chttp://rt.cpan.org/NoAuth/Bugs.html?Dist=Data-FormValidator\u003e\n\n=head1 CONTRIBUTING\n\nThis project is managed using the darcs source control system (\nhttp://www.darcs.net/ ). You can browse, pull and fork the repo here:\n\nhttp://hub.darcs.net/markstos/Data--FormValidator\n\nB\u003cSupport Mailing List\u003e\n\nIf you have any questions, comments, or feature suggestions, post them to the\nsupport mailing list!  To join the mailing list, visit\n\nL\u003chttp://lists.sourceforge.net/lists/listinfo/cascade-dataform\u003e\n\nMessages about DFV sent directly to the maintainer may be redirected here.\n\n=head1 AUTHOR\n\nCurrently maintained by David Farrell \u003cdfarrell@cpan.org\u003e\n\nParts Copyright 2001-2006 by Mark Stosberg \u003cmark at summersault.com\u003e, (previous maintainer)\n\nCopyright (c) 1999 Francis J. Lacoste and iNsu Innovations Inc.  All rights reserved.\n(Original Author)\n\nParts Copyright 1996-1999 by Michael J. Heins \u003cmike@heins.net\u003e\n\nParts Copyright 1996-1999 by Bruce Albrecht  \u003cbruce.albrecht@seag.fingerhut.com\u003e\n\n=head1 LICENSE\n\nThis program is free software; you can redistribute it and/or modify\nit under the terms as perl itself.\n\n\n=cut\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnmfarrell%2Fdata-formvalidator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdnmfarrell%2Fdata-formvalidator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnmfarrell%2Fdata-formvalidator/lists"}