Stefan Hornburg (Racke) > Data-Transpose-0.0004 > Data::Transpose::Validator

Download:
Data-Transpose-0.0004.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Source   Latest Release: Data-Transpose-0.0010

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); # set

option_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, unknown

prepare(%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: rfc822

In 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 ^

http://xkcd.com/936/

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.

syntax highlighting: