Params::Validate - Validate method/function parameters |
Params::Validate - Validate method/function parameters
use Params::Validate qw(:all);
# takes named params (hash or hashref) sub foo { validate( @_, { foo => 1, # mandatory bar => 0, # optional } ); }
# takes positional params sub bar { # first two are mandatory, third is optional validate_pos( @_, 1, 1, 0 ); }
sub foo2 { validate( @_, { foo => # specify a type { type => ARRAYREF },
bar => # specify an interface { can => [ 'print', 'flush', 'frobnicate' ] },
baz => { type => SCALAR, # a scalar ... # ... that is a plain integer ... regex => qr/^\d+$/, callbacks => { # ... and smaller than 90 'less than 90' => sub { shift() < 90 }, }, } } ); }
sub with_defaults { my %p = validate( @_, { foo => 1, # required # $p{bar} will be 99 if bar is not # given. bar is now optional. bar => { default => 99 } } ); }
sub pos_with_defaults { my @p = validate( @_, 1, { default => 99 } ); }
sub sets_options_on_call { my %p = validate_with ( params => \@_, spec => { foo => { type SCALAR, default => 2 } }, ignore_case => 1, strip_leading => '-', ); }
The Params::Validate module allows you to validate method or function call parameters to an arbitrary level of specificity. At the simplest level, it is capable of validating the required parameters were given and that no unspecified additional parameters were passed in.
It is also capable of determining that a parameter is of a specific type, that it is an object of a certain class hierarchy, that it possesses certain methods, or applying validation callbacks to arguments.
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.
The validation mechanisms provided by this module can handle both named or positional parameters. For the most part, the same features are available for each. The biggest difference is the way that the validation specification is given to the relevant subroutine. The other difference is in the error messages produced when validation checks fail.
When handling named parameters, the module is capable of handling either a hash or a hash reference transparently.
Subroutines expecting named parameters should call the validate
subroutine like this:
validate( @_, { parameter1 => validation spec, parameter2 => validation spec, ... } );
Subroutines expecting positional parameters should call the
validate_pos
subroutine like this:
validate_pos( @_, { validation spec }, { validation spec } );
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.
This module supports the following simple types, which can be exported as constants:
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
.
[1, 2, 3]
or \@foo
.
{ a =
1, b => 2 }> or \%bar
.
\&foo_sub
or sub { print "hello" }
.
*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.
\*FOO
. See the GLOB entry above
for more details.
\$x
.
UNDEF | SCALAR
.
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 questoin 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 } );
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 ) ] } } );
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( @_, { foo => { isa => [ qw( My::Frobnicator IO::Handle ) ] } } ); # must be both, not either!
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
.
The Regexp::Common
module on CPAN is an excellent source of regular
expressions suitable for validating input.
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 sole argument. 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 { $_[0] eq 'green' || $_[0] eq 'blue' } } } );
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.
If the validate
or validate_pos
functions are called in a list
context, they will return an array or hash 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( @_, 1, { default => 99 } );
In scalar context, a hash reference or array reference will be returned, as appropriate.
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.
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
contain a hash, but rather your object (or class) followed by a
hash.
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 } } ); }
Because the calling syntax for the validate
and validate_pos
functions does not make it possible to specify any options other than
the the validation spec, it is possible to set some options as
pseudo-'globals'. These allow you to specify such things as whether
or not the validation of named parameters should be case sensitive,
for one example.
These options are called pseudo-'globals' because these settings are only applied to calls originating from the package that set the options.
In other words, if I am in package Foo
and I call
Params::Validate::validation_options
, those options are only in
effect when I call validate
from package Foo
.
While this is quite different from how most other modules operate, I feel that this is necessary in able to make it possible for one module/application to use Params::Validate while still using other modules that also use Params::Validate, perhaps with different options set.
The downside to this is that if you are writing an app with a standard
calling style for all functions, and your app has ten modules, each
module must include a call to Params::Validate::validation_options
.
When this is turned on, we have to copy more data around internally, leading to a potential speed impact.
-foo
and foo
would be
considered identical.
When this is turned on, we have to copy more data around internally, leading to a potential speed impact.
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.
validate
or validate_pos
.
If this option is set, then the given number of frames are skipped
instead.
The validate_with
function can be used to set the options listed above on
a per-invocation basis. For example:
my %p = validate_with ( params => \@_, spec => { foo => { type => SCALAR }, bar => { default => 10 } }, allow_extra => 1, );
In addition to the options listed above, it is also possible to set
the option called
, which should be a string. This string will be
used in any error messages caused by a failure to meet the validation
spec.
This subroutine will validate named parameters as a hash if the
spec
parameter is a hash reference. If it is an array reference,
the parameters are assumed to be positional.
my %p = validate_with ( params => \@_, spec => { foo => { type => SCALAR }, bar => { default => 10 } }, allow_extra => 1, called => 'The Quux::Baz class constructor', );
my @p = validate_with ( params => \@_, spec => [ { type => SCALAR }, { default => 10 } ], allow_extra => 1, called => 'The Quux::Baz class constructor', );
If the environment variable PERL_NO_VALIDATION
is set to something
true, then all calls to the validation functions are turned into
no-ops. This may be useful if you only want to use this module during
development but don't want the speed hit during production.
The only error that will be caught will be when an odd number of parameters are passed into a function/method that expects a hash.
This environment value is checked only when the module is first loaded. You cannot change it after the module has loaded.
Right now there is no way (short of a callback) to specify that something must be of one of a list of classes, or that it must possess one of a list of methods. If this is desired, it can be added in the future.
Ideally, there would be only one validation function. If someone figures out how to do this, please let me know.
Getargs::Long - similar capabilities with a different interface. If you like what Params::Validate does but not its 'feel' try this one instead.
Carp::Assert and Class::Contract - other modules in the general spirit of validating that certain things are true before/while/after executing actual program code.
Dave Rolsky, <autarch@urth.org> and Ilya Martynov <ilya@martynov.org>
Params::Validate - Validate method/function parameters |