EXPORT

The module always exports the validate() and validate_pos() functions.

It also has an additional function available for export, "validate_with", which can be used to validate any type of parameters, and set various options on a per-invocation basis.

In addition, it can export the following constants, which are used as part of the type checking. These are "SCALAR", "ARRAYREF", "HASHREF", "CODEREF", "GLOB", "GLOBREF", and "SCALARREF", "UNDEF", "OBJECT", "BOOLEAN", and "HANDLE". These are explained in the section on Type Validation.

The constants are available via the export tag ":types". There is also an ":all" tag which includes all of the constants as well as the validation_options() function.

Mandatory/Optional Parameters

If you just want to specify that some parameters are mandatory and others are optional, this can be done very simply.

For a subroutine expecting named parameters, you would do this:

validate( @_, { foo => 1, bar => 1, baz => 0 } );

This says that the "foo" and "bar" parameters are mandatory and that the "baz" parameter is optional. The presence of any other parameters will cause an error.

For a subroutine expecting positional parameters, you would do this:

validate_pos( @_, 1, 1, 0, 0 );

This says that you expect at least 2 and no more than 4 parameters. If you have a subroutine that has a minimum number of parameters but can take any maximum number, you can do this:

validate_pos( @_, 1, 1, (0) x (@_ - 2) );

This will always be valid as long as at least two parameters are given. A similar construct could be used for the more complex validation parameters described further on.

Please note that this:

validate_pos( @_, 1, 1, 0, 1, 1 );

makes absolutely no sense, so don't do it. Any zeros must come at the end of the validation specification.

In addition, if you specify that a parameter can have a default, then it is considered optional.

Type Validation

This module supports the following simple types, which can be exported as constants:

• SCALAR

  A scalar which is not a reference, such as 10 or 'hello'. A parameter that is undefined is not treated as a scalar. If you want to allow undefined values, you will have to specify "SCALAR | UNDEF".

• ARRAYREF

  An array reference such as "[1, 2, 3]" or "\@foo".

• HASHREF

  A hash reference such as "{ a => 1, b => 2 }" or "\%bar".

• CODEREF

  A subroutine reference such as "\&foo_sub" or "sub { print "hello" }".

• GLOB

  This one is a bit tricky. A glob would be something like *FOO, but not "\*FOO", which is a glob reference. It should be noted that this trick:

  my $fh = do { local *FH; };
  

  makes $fh a glob, not a glob reference. On the other hand, the return value from "Symbol::gensym" is a glob reference. Either can be used as a file or directory handle.

• GLOBREF

  A glob reference such as "\*FOO". See the GLOB entry above for more details.

• SCALARREF

  A reference to a scalar such as "\$x".

• UNDEF

  An undefined value

• OBJECT

  A blessed reference.

• BOOLEAN

  This is a special option, and is just a shortcut for "UNDEF | SCALAR".

• HANDLE

  This option is also special, and is just a shortcut for "GLOB | GLOBREF". However, it seems likely that most people interested in either globs or glob references are likely to really be interested in whether the parameter in question could be a valid file or directory handle.

To specify that a parameter must be of a given type when using named parameters, do this:

validate(
    @_, {
        foo => { type => SCALAR },
        bar => { type => HASHREF }
    }
);

If a parameter can be of more than one type, just use the bitwise or ("|") operator to combine them.

validate( @_, { foo => { type => GLOB | GLOBREF } );

For positional parameters, this can be specified as follows:

validate_pos( @_, { type => SCALAR | ARRAYREF }, { type => CODEREF } );

Interface Validation

To specify that a parameter is expected to have a certain set of methods, we can do the following:

   validate(
       @_, {
           foo =>
               # just has to be able to ->bar
               { can => 'bar' }
       }
   );
... or ...
   validate(
       @_, {
           foo =>
               # must be able to ->bar and ->print
               { can => [qw( bar print )] }
       }
   );

Class Validation

A word of warning. When constructing your external interfaces, it is probably better to specify what methods you expect an object to have rather than what class it should be of (or a child of). This will make your API much more flexible.

With that said, if you want to validate that an incoming parameter belongs to a class (or child class) or classes, do:

   validate(
       @_,
       { foo => { isa => 'My::Frobnicator' } }
   );
... or ...
   validate(
       @_,
       # must be both, not either!
       { foo => { isa => [qw( My::Frobnicator IO::Handle )] } }
   );

Regex Validation

If you want to specify that a given parameter must match a specific regular expression, this can be done with "regex" spec key. For example:

validate(
    @_,
    { foo => { regex => qr/^\d+$/ } }
);

The value of the "regex" key may be either a string or a pre-compiled regex created via "qr".

If the value being checked against a regex is undefined, the regex is explicitly checked against the empty string ('') instead, in order to avoid "Use of uninitialized value" warnings.

The "Regexp::Common" module on CPAN is an excellent source of regular expressions suitable for validating input.

Callback Validation

If none of the above are enough, it is possible to pass in one or more callbacks to validate the parameter. The callback will be given the value of the parameter as its first argument. Its second argument will be all the parameters, as a reference to either a hash or array. Callbacks are specified as hash reference. The key is an id for the callback (used in error messages) and the value is a subroutine reference, such as:

validate(
    @_,
    {
        foo => {
            callbacks => {
                'smaller than a breadbox' => sub { shift() < $breadbox },
                'green or blue'           => sub {
                    return 1 if $_[0] eq 'green' || $_[0] eq 'blue';
                    die "$_[0] is not green or blue!";
                }
            }
        }
    }
);
validate(
    @_, {
        foo => {
            callbacks => {
                'bigger than baz' => sub { $_[0] > $_[1]->{baz} }
            }
        }
    }
);

The callback should return a true value if the value is valid. If not, it can return false or die. If you return false, a generic error message will be thrown by "Params::Validate".

If your callback dies instead you can provide a custom error message. If the callback dies with a plain string, this string will be appended to an exception message generated by "Params::Validate". If the callback dies with a reference (blessed or not), then this will be rethrown as-is by "Params::Validate".

Untainting

If you want values untainted, set the "untaint" key in a spec hashref to a true value, like this:

my %p = validate(
    @_, {
        foo => { type => SCALAR, untaint => 1 },
        bar => { type => ARRAYREF }
    }
);

This will untaint the "foo" parameter if the parameters are valid.

Note that untainting is only done if all parameters are valid. Also, only the return values are untainted, not the original values passed into the validation function.

Asking for untainting of a reference value will not do anything, as "Params::Validate" will only attempt to untaint the reference itself.

Mandatory/Optional Revisited

If you want to specify something such as type or interface, plus the fact that a parameter can be optional, do this:

validate(
    @_, {
        foo => { type => SCALAR },
        bar => { type => ARRAYREF, optional => 1 }
    }
);

or this for positional parameters:

validate_pos(
    @_,
    { type => SCALAR },
    { type => ARRAYREF, optional => 1 }
);

By default, parameters are assumed to be mandatory unless specified as optional.

Dependencies

It also possible to specify that a given optional parameter depends on the presence of one or more other optional parameters.

validate(
    @_, {
        cc_number => {
            type     => SCALAR,
            optional => 1,
            depends  => [ 'cc_expiration', 'cc_holder_name' ],
        },
        cc_expiration  => { type => SCALAR, optional => 1 },
        cc_holder_name => { type => SCALAR, optional => 1 },
    }
);

In this case, "cc_number", "cc_expiration", and "cc_holder_name" are all optional. However, if "cc_number" is provided, then "cc_expiration" and "cc_holder_name" must be provided as well.

This allows you to group together sets of parameters that all must be provided together.

The validate_pos() version of dependencies is slightly different, in that you can only depend on one other parameter. Also, if for example, the second parameter 2 depends on the fourth parameter, then it implies a dependency on the third parameter as well. This is because if the fourth parameter is required, then the user must also provide a third parameter so that there can be four parameters in total.

"Params::Validate" will die if you try to depend on a parameter not declared as part of your parameter specification.

Specifying defaults

If the validate() or validate_pos() functions are called in a list context, they will return a hash or containing the original parameters plus defaults as indicated by the validation spec.

If the function is not called in a list context, providing a default in the validation spec still indicates that the parameter is optional.

The hash or array returned from the function will always be a copy of the original parameters, in order to leave @_ untouched for the calling function.

Simple examples of defaults would be:

my %p = validate( @_, { foo => 1, bar => { default => 99 } } );
my @p = validate_pos( @_, 1, { default => 99 } );

In scalar context, a hash reference or array reference will be returned, as appropriate.

Validation failure

By default, when validation fails "Params::Validate" calls Carp::confess(). This can be overridden by setting the "on_fail" option, which is described in the "GLOBAL" OPTIONS section.

Method calls

When using this module to validate the parameters passed to a method call, you will probably want to remove the class/object from the parameter list before calling validate() or validate_pos(). If your method expects named parameters, then this is necessary for the validate() function to actually work, otherwise @_ will not be usable as a hash, because it will first have your object (or class) followed by a set of keys and values.

Thus the idiomatic usage of validate() in a method call will look something like this:

sub method {
    my $self = shift;
    my %params = validate(
        @_, {
            foo => 1,
            bar => { type => ARRAYREF },
        }
    );
}

Speeding Up Validation

In most cases, the validation spec will remain the same for each call to a subroutine. In that case, you can speed up validation by defining the validation spec just once, rather than on each call to the subroutine:

my %spec = ( ... );
sub foo {
    my %params = validate( @_, \%spec );
}

You can also use the "state" feature to do this:

use feature 'state';
sub foo {
    state $spec = { ... };
    my %params = validate( @_, $spec );
}

Options

• normalize_keys => $callback

  This option is only relevant when dealing with named parameters.

  This callback will be used to transform the hash keys of both the parameters and the parameter spec when validate() or validate_with() are called.

  Any alterations made by this callback will be reflected in the parameter hash that is returned by the validation function. For example:

  sub foo {
      return validate_with(
          params => \@_,
          spec   => { foo => { type => SCALAR } },
          normalize_keys =>
              sub { my $k = shift; $k =~ s/^-//; return uc $k },
      );
  }
  %p = foo( foo => 20 );
  # $p{FOO} is now 20
  %p = foo( -fOo => 50 );
  # $p{FOO} is now 50
  

  The callback must return a defined value.

  If a callback is given then the deprecated "ignore_case" and "strip_leading" options are ignored.

• allow_extra => $boolean

  If true, then the validation routine will allow extra parameters not named in the validation specification. In the case of positional parameters, this allows an unlimited number of maximum parameters (though a minimum may still be set). Defaults to false.

• on_fail => $callback

  If given, this callback will be called whenever a validation check fails. It will be called with a single parameter, which will be a string describing the failure. This is useful if you wish to have this module throw exceptions as objects rather than as strings, for example.

  This callback is expected to die() internally. If it does not, the validation will proceed onwards, with unpredictable results.

  The default is to simply use the Carp module's confess() function.

• stack_skip => $number

  This tells Params::Validate how many stack frames to skip when finding a subroutine name to use in error messages. By default, it looks one frame back, at the immediate caller to validate() or validate_pos(). If this option is set, then the given number of frames are skipped instead.

• ignore_case => $boolean

  DEPRECATED

  This is only relevant when dealing with named parameters. If it is true, then the validation code will ignore the case of parameter names. Defaults to false.

• strip_leading => $characters

  DEPRECATED

  This too is only relevant when dealing with named parameters. If this is given then any parameters starting with these characters will be considered equivalent to parameters without them entirely. For example, if this is specified as '-', then "-foo" and "foo" would be considered identical.