NAME
Data::Transpose::Validator - Filter and validate data.
SYNOPSIS
use Data::Transpose::Validator;
my $dtv = Data::Transpose::Validator->new();
$dtv->prepare(email => {validator => 'EmailValid',
required => 1},
password => {validator => 'PasswordPolicy',
required => 1}
);
my $form = {
email => "aklasdfasdf",
password => "1234"
};
my $clean = $dtv->transpose($form);
if ($clean) {
# the validator says it's valid, and the hashref $clean is validated
# $clean is the validated hash
} else {
my $errors = $dtv->errors; # arrayref with the errors
# old data
my $invalid_but_filtered = $dtv->transposed_data; # hashref with the data
}DESCRIPTION
This module provides an interface to validate and filter hashrefs, usually (but not necessarily) from HTML forms.
METHODS
new
The constructor. It accepts a hash as argument, with options:
stripwhite: strip leading and trailing whitespace from strings (default: true)
requireall: require all the fields of the schema (default: false)
unknown: what to do if other fields, not present in the schema, are passed.
fail: The transposing routine will die with a message stating the unknown fields
pass: The routine will accept them and return them in the validated hash
skip: The routine will ignore them and not return them in the validated hash. This is the default.
missing: what to do if an optional field is missing
pass: do nothing, don't add to the returning hash the missing keys. This is the default.
undefine: add the key with the undef value
empty: set it to the empty string;
option($option, [ $value ]);
Accessor to the options set. With an optional argument, set that option.
$dtv->option("requireall"); # get
$dtv->option(requireall => 1); # setoption_for_field($option, $field)
Accessor to get the option for this particular field. First it looks into the fields options, then into the global ones, returning the first defined value.
$dtv->option(email => "stripwhite");options
Accessor to get the list of the options
$dtv->options;
# -> requireall, stripwhite, unknownprepare(%hash) or prepare([ {}, {}, ... ])
prepare takes a hash and pass the key/value pairs to field. This method can accept an hash or an array reference. When an arrayref is passed, the output of the errors will keep the provided sorting (this is the only difference).
You can call prepare as many times you want before the transposing. Fields are added or replaced, but you could end up with messy errors if you provide duplicates, so please just don't do it (but feel free to add the fields at different time as long you don't overwrite them.
$dtv->prepare([
{ name => "country" ,
required => 1,
},
{
name => "country2",
validator => 'String'},
{
name => "email",
validator => "EmailValid"
},
]
);
or
$dtv->prepare(
country => {
required => 1,
},
country2 => {
validator => "String"
}
);
## other code here
$dtv->prepare(
email => {
validator => "EmailValid"
}
);The validator value can be an string, a hashref or a coderef.
When a string is passed, the class which will be loaded will be prefixed by Data::Transpose::Validator:: and initialized without arguments.
If a coderef is passed as value of validator, a new object Data::Transpose::Validator::Subrefs is created, with the coderef as validator.
If a hashref is passed as value of validator, it must contains the key class and optionally options as an hashref. As with the string, the class will be prefixed by Data::Transpose::Validator::, unless you pass the absolute key set to a true value.
$dtv->prepare(
email => {
validator => "EmailValid",
},
# ditto
email2 => {
validator => {
class => "EmailValid",
}
},
# tritto
email3 => {
validator => {
class => "Data::Transpose::Validator::EmailValid",
absolute => 1,
}
},
# something more elaborate
passowrd => {
validator => {
class => PasswordPolicy,
options => {
minlength => 10,
maxlength => 50,
disabled => {
username => 1,
}
}
}
}
);
field($field)
This accessor sets the various fields and their options. It's intended to be used only internally, but you can add individual fields with it
$dtv->field(email => { required => 1 });
print(Dumper($dtv->field("email"));
print(Dumper($dtv->field);With no arguments, it retrieves the hashref with all the fields, while with 1 argument retrieves the hashref of that specific field.
transpose
The main method. It validates the hash and return a validated one or nothing if there were errors.
transposed_data
Accessor to the transposed hash. This is handy if you want to retrieve the filtered data after a failure (because transpose will return undef in that case).
errors
Accessor to set or retrieve the errors (returned as an arrayref of hashes). Each element has the key field set to the fieldname and the key errors holds the the error list. This, in turn, is a list of arrays, where the first element is the error code, and the second the human format set by the module (in English). See the method belows for a more accessible way for the errors.
faulty_fields
Accessor to the list of fields where the validator detected errors.
errors_as_hashref_for_humans
Accessor to get a list of the failed checks. It returns an hashref with the keys set to the faulty fields, and the value as an arrayref to a list of the error messages.
errors_as_hashref
Same as above, but for machine processing. It returns the lists of error codes as values.
packed_errors($fieldsep, $separator)
As convenience, this metod will join the human readable strings using the second argument, and introduced by the name of the field concatenated to the first argument. Example with the defaults (colon and comma):
password: Wrong length, No special characters, No letters in the
password, Found common password, Not enough different characters,
Found common patterns: 1234
country: My error
email2: rfc822In scalar context it returns a string, in list context returns the errors as an array, so you still can process it easily.
field_is_required($field)
Check if the field is required. Return true unconditionally if the option requireall is set. If not, look into the schema and return the value provided in the schema.
reset_self
Clear all the internal data stored during validations, to make the reusing of the transposing possible.
This is called by transpose before doing any other operation
EXPORT
None by default.
SEE ALSO
AUTHOR
Marco Pessotto, <melmothx@gmail.com>
COPYRIGHT AND LICENSE
Copyright (C) 2013 by Marco Pessotto
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.