validate.pm

1. 记录每个帖子的访问人情况

 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} } } } );

=head2 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 I<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
C<Params::Validate> will only attempt to untaint the reference itself.

=head2 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.

=head2 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 C<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.

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

=head2 Specifying defaults

If the C<validate()> or C<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 C<@_> 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.

=head1 USAGE NOTES

=head2 Validation failure

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

=head2 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 B<before> calling C<validate()> or C<validate_pos()>.
If your method expects named parameters, then this is necessary for
the C<validate()> function to actually work, otherwise C<@_> will not
be useable as a hash, because it will first have your object (or
class) B<followed> by a set of keys and values.

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

 sub method
 {
     my $self = shift;

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

=head1 "GLOBAL" OPTIONS

Because the calling syntax for the C<validate()> and C<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
B<only applied to calls originating from the package that set the
options>.

In other words, if I am in package C<Foo> and I call
C<Params::Validate::validation_options()>, those options are only in
effect when I call C<validate()> from package C<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, B<each
module must include a call to
C<Params::Validate::validation_options()>>.

=head2 Options

=over 4

=item * 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 C<validate()> or
C<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.

=item * 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.

=item * 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 C<die()> internally.  If it does not, the
validation will proceed onwards, with unpredictable results.

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

=item * 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 C<validate()> or
C<validate_pos()>.  If this option is set, then the given number of
frames are skipped instead.

=item * 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.

=item * 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 C<-foo> and C<foo> would be
considered identical.

=back

=head1 PER-INVOCATION OPTIONS

The C<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',
          );

=head1 DISABLING VALIDATION

If the environment variable C<PERL_NO_VALIDATION> is set to something
true, then validation is turned off.  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.

If you want to selectively turn validation on and off at runtime, you
can directly set the C<$Params::Validate::NO_VALIDATION> global
variable.  It is B<strongly> recommended that you B<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!

=head1 LIMITATIONS

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.

=head1 SUPPORT

For now, support questions should be sent to Dave at [e-mail].
The CVS repository is on Savannah at
https://savannah.nongnu.org/projects/p-v-perl/.

=head1 SEE ALSO

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.

=head1 AUTHORS

Dave Rolsky, <[e-mail]> and Ilya Martynov <[e-mail]>

=head1 COPYRIGHT

Copyright (c) 2004 David Rolsky.  All rights reserved.  This program
is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.

=cut