Партнёры:
Хостинг:
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_pos( @_, 1, { default => 99 } );
}
sub sets_options_on_call
{
my %p = validate_with
( params => \@_,
spec => { foo => { type SCALAR, default => 2 } },
normalize_keys => sub { $_[0] =~ s/^-//; lc $_[0] },
);
}
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.
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.
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 } );
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.
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.
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 } );
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 ) ] } } );
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!
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.
validate( @_,
{ foo =>
{ callbacks =>
{ 'smaller than a breadbox' => sub { shift() < $breadbox },
'green or blue' =>
sub { $_[0] eq 'green' || $_[0] eq 'blue' } } } );
validate( @_,
{ foo =>
{ callbacks =>
{ 'bigger than baz' => sub { $_[0] > $_[1]->{baz} } } } } );
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.
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.
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.
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.
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 } } );
}
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()".
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 than the deprecated ``ignore_case'' and ``strip_leading'' options are ignored.
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.
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.
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.
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',
);
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.
If you want to selectively turn validation on and off at runtime, you can directly set the $Params::Validate::NO_VALIDATION global variable. It is strongly recommended that you localize any changes to this variable, because other modules you are using may expect validation to be on when they execute. For example:
{
local $Params::Validate::NO_VALIDATION = 1;
# no error
foo( bar => 2 );
}
# error foo( bar => 2 );
sub foo
{
my %p = validate( @_, { foo => 1 } );
...
}
But if you want to shoot yourself in the foot and just turn it off, go ahead!
Ideally, there would be only one validation function. If someone figures out how to do this, please let me know.
The code repository is at https://svn.urth.org/svn/Params-Validate/
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.
|
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |