| Filename | /2home/ss5/perl5/perlbrew/perls/perl-5.12.3/lib/site_perl/5.12.3/x86_64-linux/Params/Validate.pm |
| Statements | Executed 34 statements in 624µs |
| Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
|---|---|---|---|---|---|
| 1 | 1 | 1 | 229µs | 322µs | Params::Validate::BEGIN@13 |
| 1 | 1 | 1 | 26µs | 26µs | Params::Validate::BEGIN@6 |
| 1 | 1 | 1 | 8µs | 8µs | Params::Validate::BEGIN@12 |
| 1 | 1 | 1 | 8µs | 53µs | Params::Validate::BEGIN@15 |
| 1 | 1 | 1 | 7µs | 22µs | Params::Validate::BEGIN@11 |
| 1 | 1 | 1 | 6µs | 14µs | Params::Validate::BEGIN@9 |
| 1 | 1 | 1 | 6µs | 8µs | Params::Validate::BEGIN@8 |
| Line | State ments |
Time on line |
Calls | Time in subs |
Code |
|---|---|---|---|---|---|
| 1 | package Params::Validate; | ||||
| 2 | { | ||||
| 3 | 2 | 900ns | $Params::Validate::VERSION = '1.06'; | ||
| 4 | } | ||||
| 5 | |||||
| 6 | 3 | 34µs | 1 | 26µs | # spent 26µs within Params::Validate::BEGIN@6 which was called:
# once (26µs+0s) by Test::Fixture::DBIC::Schema::BEGIN@7 at line 6 # spent 26µs making 1 call to Params::Validate::BEGIN@6 |
| 7 | |||||
| 8 | 3 | 15µs | 2 | 10µs | # spent 8µs (6+2) within Params::Validate::BEGIN@8 which was called:
# once (6µs+2µs) by Test::Fixture::DBIC::Schema::BEGIN@7 at line 8 # spent 8µs making 1 call to Params::Validate::BEGIN@8
# spent 2µs making 1 call to strict::import |
| 9 | 3 | 15µs | 2 | 22µs | # spent 14µs (6+8) within Params::Validate::BEGIN@9 which was called:
# once (6µs+8µs) by Test::Fixture::DBIC::Schema::BEGIN@7 at line 9 # spent 14µs making 1 call to Params::Validate::BEGIN@9
# spent 8µs making 1 call to warnings::import |
| 10 | |||||
| 11 | 3 | 16µs | 2 | 38µs | # spent 22µs (7+16) within Params::Validate::BEGIN@11 which was called:
# once (7µs+16µs) by Test::Fixture::DBIC::Schema::BEGIN@7 at line 11 # spent 22µs making 1 call to Params::Validate::BEGIN@11
# spent 16µs making 1 call to Exporter::import |
| 12 | 3 | 22µs | 1 | 8µs | # spent 8µs within Params::Validate::BEGIN@12 which was called:
# once (8µs+0s) by Test::Fixture::DBIC::Schema::BEGIN@7 at line 12 # spent 8µs making 1 call to Params::Validate::BEGIN@12 |
| 13 | 3 | 77µs | 2 | 388µs | # spent 322µs (229+94) within Params::Validate::BEGIN@13 which was called:
# once (229µs+94µs) by Test::Fixture::DBIC::Schema::BEGIN@7 at line 13 # spent 322µs making 1 call to Params::Validate::BEGIN@13
# spent 66µs making 1 call to Exporter::import |
| 14 | |||||
| 15 | 3 | 390µs | 2 | 98µs | # spent 53µs (8+45) within Params::Validate::BEGIN@15 which was called:
# once (8µs+45µs) by Test::Fixture::DBIC::Schema::BEGIN@7 at line 15 # spent 53µs making 1 call to Params::Validate::BEGIN@15
# spent 45µs making 1 call to vars::import |
| 16 | |||||
| 17 | 1 | 5µs | our @ISA = 'Exporter'; | ||
| 18 | |||||
| 19 | 1 | 3µs | my %tags = ( | ||
| 20 | types => [ | ||||
| 21 | qw( | ||||
| 22 | SCALAR | ||||
| 23 | ARRAYREF | ||||
| 24 | HASHREF | ||||
| 25 | CODEREF | ||||
| 26 | GLOB | ||||
| 27 | GLOBREF | ||||
| 28 | SCALARREF | ||||
| 29 | HANDLE | ||||
| 30 | BOOLEAN | ||||
| 31 | UNDEF | ||||
| 32 | OBJECT | ||||
| 33 | ) | ||||
| 34 | ], | ||||
| 35 | ); | ||||
| 36 | |||||
| 37 | our %EXPORT_TAGS = ( | ||||
| 38 | 'all' => [ | ||||
| 39 | qw( validate validate_pos validation_options validate_with ), | ||||
| 40 | 1 | 12µs | map { @{ $tags{$_} } } keys %tags | ||
| 41 | ], | ||||
| 42 | %tags, | ||||
| 43 | ); | ||||
| 44 | |||||
| 45 | 1 | 8µs | our @EXPORT_OK = ( @{ $EXPORT_TAGS{all} }, 'set_options' ); | ||
| 46 | 1 | 500ns | our @EXPORT = qw( validate validate_pos ); | ||
| 47 | |||||
| 48 | 1 | 700ns | $NO_VALIDATION = $ENV{PERL_NO_VALIDATION}; | ||
| 49 | |||||
| 50 | { | ||||
| 51 | 4 | 9µs | 1 | 31µs | my $loader = Module::Implementation::build_loader_sub( # spent 31µs making 1 call to Module::Implementation::build_loader_sub |
| 52 | implementations => [ 'XS', 'PP' ], | ||||
| 53 | symbols => [ | ||||
| 54 | qw( | ||||
| 55 | validate | ||||
| 56 | validate_pos | ||||
| 57 | validate_with | ||||
| 58 | validation_options | ||||
| 59 | set_options | ||||
| 60 | ), | ||||
| 61 | ], | ||||
| 62 | ); | ||||
| 63 | |||||
| 64 | $ENV{PARAMS_VALIDATE_IMPLEMENTATION} = 'PP' if $ENV{PV_TEST_PERL}; | ||||
| 65 | |||||
| 66 | 1 | 699µs | $loader->(); # spent 699µs making 1 call to Module::Implementation::__ANON__[Module/Implementation.pm:44] | ||
| 67 | } | ||||
| 68 | |||||
| 69 | 1 | 16µs | 1; | ||
| 70 | |||||
| 71 | # ABSTRACT: Validate method/function parameters | ||||
| 72 | |||||
| - - | |||||
| 75 | =pod | ||||
| 76 | |||||
| 77 | =head1 NAME | ||||
| 78 | |||||
| 79 | Params::Validate - Validate method/function parameters | ||||
| 80 | |||||
| 81 | =head1 VERSION | ||||
| 82 | |||||
| 83 | version 1.06 | ||||
| 84 | |||||
| 85 | =head1 SYNOPSIS | ||||
| 86 | |||||
| 87 | use Params::Validate qw(:all); | ||||
| 88 | |||||
| 89 | # takes named params (hash or hashref) | ||||
| 90 | sub foo { | ||||
| 91 | validate( | ||||
| 92 | @_, { | ||||
| 93 | foo => 1, # mandatory | ||||
| 94 | bar => 0, # optional | ||||
| 95 | } | ||||
| 96 | ); | ||||
| 97 | } | ||||
| 98 | |||||
| 99 | # takes positional params | ||||
| 100 | sub bar { | ||||
| 101 | # first two are mandatory, third is optional | ||||
| 102 | validate_pos( @_, 1, 1, 0 ); | ||||
| 103 | } | ||||
| 104 | |||||
| 105 | sub foo2 { | ||||
| 106 | validate( | ||||
| 107 | @_, { | ||||
| 108 | foo => | ||||
| 109 | # specify a type | ||||
| 110 | { type => ARRAYREF }, | ||||
| 111 | bar => | ||||
| 112 | # specify an interface | ||||
| 113 | { can => [ 'print', 'flush', 'frobnicate' ] }, | ||||
| 114 | baz => { | ||||
| 115 | type => SCALAR, # a scalar ... | ||||
| 116 | # ... that is a plain integer ... | ||||
| 117 | regex => qr/^\d+$/, | ||||
| 118 | callbacks => { # ... and smaller than 90 | ||||
| 119 | 'less than 90' => sub { shift() < 90 }, | ||||
| 120 | }, | ||||
| 121 | } | ||||
| 122 | } | ||||
| 123 | ); | ||||
| 124 | } | ||||
| 125 | |||||
| 126 | sub with_defaults { | ||||
| 127 | my %p = validate( | ||||
| 128 | @_, { | ||||
| 129 | # required | ||||
| 130 | foo => 1, | ||||
| 131 | # $p{bar} will be 99 if bar is not given. bar is now | ||||
| 132 | # optional. | ||||
| 133 | bar => { default => 99 } | ||||
| 134 | } | ||||
| 135 | ); | ||||
| 136 | } | ||||
| 137 | |||||
| 138 | sub pos_with_defaults { | ||||
| 139 | my @p = validate_pos( @_, 1, { default => 99 } ); | ||||
| 140 | } | ||||
| 141 | |||||
| 142 | sub sets_options_on_call { | ||||
| 143 | my %p = validate_with( | ||||
| 144 | params => \@_, | ||||
| 145 | spec => { foo => { type => SCALAR, default => 2 } }, | ||||
| 146 | normalize_keys => sub { $_[0] =~ s/^-//; lc $_[0] }, | ||||
| 147 | ); | ||||
| 148 | } | ||||
| 149 | |||||
| 150 | =head1 DESCRIPTION | ||||
| 151 | |||||
| 152 | The Params::Validate module allows you to validate method or function | ||||
| 153 | call parameters to an arbitrary level of specificity. At the simplest | ||||
| 154 | level, it is capable of validating the required parameters were given | ||||
| 155 | and that no unspecified additional parameters were passed in. | ||||
| 156 | |||||
| 157 | It is also capable of determining that a parameter is of a specific | ||||
| 158 | type, that it is an object of a certain class hierarchy, that it | ||||
| 159 | possesses certain methods, or applying validation callbacks to | ||||
| 160 | arguments. | ||||
| 161 | |||||
| 162 | =head2 EXPORT | ||||
| 163 | |||||
| 164 | The module always exports the C<validate()> and C<validate_pos()> | ||||
| 165 | functions. | ||||
| 166 | |||||
| 167 | It also has an additional function available for export, | ||||
| 168 | C<validate_with>, which can be used to validate any type of | ||||
| 169 | parameters, and set various options on a per-invocation basis. | ||||
| 170 | |||||
| 171 | In addition, it can export the following constants, which are used as | ||||
| 172 | part of the type checking. These are C<SCALAR>, C<ARRAYREF>, | ||||
| 173 | C<HASHREF>, C<CODEREF>, C<GLOB>, C<GLOBREF>, and C<SCALARREF>, | ||||
| 174 | C<UNDEF>, C<OBJECT>, C<BOOLEAN>, and C<HANDLE>. These are explained | ||||
| 175 | in the section on L<Type Validation|Params::Validate/Type Validation>. | ||||
| 176 | |||||
| 177 | The constants are available via the export tag C<:types>. There is | ||||
| 178 | also an C<:all> tag which includes all of the constants as well as the | ||||
| 179 | C<validation_options()> function. | ||||
| 180 | |||||
| 181 | =head1 PARAMETER VALIDATION | ||||
| 182 | |||||
| 183 | The validation mechanisms provided by this module can handle both | ||||
| 184 | named or positional parameters. For the most part, the same features | ||||
| 185 | are available for each. The biggest difference is the way that the | ||||
| 186 | validation specification is given to the relevant subroutine. The | ||||
| 187 | other difference is in the error messages produced when validation | ||||
| 188 | checks fail. | ||||
| 189 | |||||
| 190 | When handling named parameters, the module will accept either a hash | ||||
| 191 | or a hash reference. | ||||
| 192 | |||||
| 193 | Subroutines expecting named parameters should call the C<validate()> | ||||
| 194 | subroutine like this: | ||||
| 195 | |||||
| 196 | validate( | ||||
| 197 | @_, { | ||||
| 198 | parameter1 => validation spec, | ||||
| 199 | parameter2 => validation spec, | ||||
| 200 | ... | ||||
| 201 | } | ||||
| 202 | ); | ||||
| 203 | |||||
| 204 | Subroutines expecting positional parameters should call the | ||||
| 205 | C<validate_pos()> subroutine like this: | ||||
| 206 | |||||
| 207 | validate_pos( @_, { validation spec }, { validation spec } ); | ||||
| 208 | |||||
| 209 | =head2 Mandatory/Optional Parameters | ||||
| 210 | |||||
| 211 | If you just want to specify that some parameters are mandatory and | ||||
| 212 | others are optional, this can be done very simply. | ||||
| 213 | |||||
| 214 | For a subroutine expecting named parameters, you would do this: | ||||
| 215 | |||||
| 216 | validate( @_, { foo => 1, bar => 1, baz => 0 } ); | ||||
| 217 | |||||
| 218 | This says that the "foo" and "bar" parameters are mandatory and that | ||||
| 219 | the "baz" parameter is optional. The presence of any other | ||||
| 220 | parameters will cause an error. | ||||
| 221 | |||||
| 222 | For a subroutine expecting positional parameters, you would do this: | ||||
| 223 | |||||
| 224 | validate_pos( @_, 1, 1, 0, 0 ); | ||||
| 225 | |||||
| 226 | This says that you expect at least 2 and no more than 4 parameters. | ||||
| 227 | If you have a subroutine that has a minimum number of parameters but | ||||
| 228 | can take any maximum number, you can do this: | ||||
| 229 | |||||
| 230 | validate_pos( @_, 1, 1, (0) x (@_ - 2) ); | ||||
| 231 | |||||
| 232 | This will always be valid as long as at least two parameters are | ||||
| 233 | given. A similar construct could be used for the more complex | ||||
| 234 | validation parameters described further on. | ||||
| 235 | |||||
| 236 | Please note that this: | ||||
| 237 | |||||
| 238 | validate_pos( @_, 1, 1, 0, 1, 1 ); | ||||
| 239 | |||||
| 240 | makes absolutely no sense, so don't do it. Any zeros must come at the | ||||
| 241 | end of the validation specification. | ||||
| 242 | |||||
| 243 | In addition, if you specify that a parameter can have a default, then | ||||
| 244 | it is considered optional. | ||||
| 245 | |||||
| 246 | =head2 Type Validation | ||||
| 247 | |||||
| 248 | This module supports the following simple types, which can be | ||||
| 249 | L<exported as constants|/EXPORT>: | ||||
| 250 | |||||
| 251 | =over 4 | ||||
| 252 | |||||
| 253 | =item * SCALAR | ||||
| 254 | |||||
| 255 | A scalar which is not a reference, such as C<10> or C<'hello'>. A | ||||
| 256 | parameter that is undefined is B<not> treated as a scalar. If you | ||||
| 257 | want to allow undefined values, you will have to specify C<SCALAR | | ||||
| 258 | UNDEF>. | ||||
| 259 | |||||
| 260 | =item * ARRAYREF | ||||
| 261 | |||||
| 262 | An array reference such as C<[1, 2, 3]> or C<\@foo>. | ||||
| 263 | |||||
| 264 | =item * HASHREF | ||||
| 265 | |||||
| 266 | A hash reference such as C<< { a => 1, b => 2 } >> or C<\%bar>. | ||||
| 267 | |||||
| 268 | =item * CODEREF | ||||
| 269 | |||||
| 270 | A subroutine reference such as C<\&foo_sub> or C<sub { print "hello" }>. | ||||
| 271 | |||||
| 272 | =item * GLOB | ||||
| 273 | |||||
| 274 | This one is a bit tricky. A glob would be something like C<*FOO>, but | ||||
| 275 | not C<\*FOO>, which is a glob reference. It should be noted that this | ||||
| 276 | trick: | ||||
| 277 | |||||
| 278 | my $fh = do { local *FH; }; | ||||
| 279 | |||||
| 280 | makes C<$fh> a glob, not a glob reference. On the other hand, the | ||||
| 281 | return value from C<Symbol::gensym> is a glob reference. Either can | ||||
| 282 | be used as a file or directory handle. | ||||
| 283 | |||||
| 284 | =item * GLOBREF | ||||
| 285 | |||||
| 286 | A glob reference such as C<\*FOO>. See the L<GLOB|GLOB> entry above | ||||
| 287 | for more details. | ||||
| 288 | |||||
| 289 | =item * SCALARREF | ||||
| 290 | |||||
| 291 | A reference to a scalar such as C<\$x>. | ||||
| 292 | |||||
| 293 | =item * UNDEF | ||||
| 294 | |||||
| 295 | An undefined value | ||||
| 296 | |||||
| 297 | =item * OBJECT | ||||
| 298 | |||||
| 299 | A blessed reference. | ||||
| 300 | |||||
| 301 | =item * BOOLEAN | ||||
| 302 | |||||
| 303 | This is a special option, and is just a shortcut for C<UNDEF | SCALAR>. | ||||
| 304 | |||||
| 305 | =item * HANDLE | ||||
| 306 | |||||
| 307 | This option is also special, and is just a shortcut for C<GLOB | | ||||
| 308 | GLOBREF>. However, it seems likely that most people interested in | ||||
| 309 | either globs or glob references are likely to really be interested in | ||||
| 310 | whether the parameter in question could be a valid file or directory | ||||
| 311 | handle. | ||||
| 312 | |||||
| 313 | =back | ||||
| 314 | |||||
| 315 | To specify that a parameter must be of a given type when using named | ||||
| 316 | parameters, do this: | ||||
| 317 | |||||
| 318 | validate( | ||||
| 319 | @_, { | ||||
| 320 | foo => { type => SCALAR }, | ||||
| 321 | bar => { type => HASHREF } | ||||
| 322 | } | ||||
| 323 | ); | ||||
| 324 | |||||
| 325 | If a parameter can be of more than one type, just use the bitwise or | ||||
| 326 | (C<|>) operator to combine them. | ||||
| 327 | |||||
| 328 | validate( @_, { foo => { type => GLOB | GLOBREF } ); | ||||
| 329 | |||||
| 330 | For positional parameters, this can be specified as follows: | ||||
| 331 | |||||
| 332 | validate_pos( @_, { type => SCALAR | ARRAYREF }, { type => CODEREF } ); | ||||
| 333 | |||||
| 334 | =head2 Interface Validation | ||||
| 335 | |||||
| 336 | To specify that a parameter is expected to have a certain set of | ||||
| 337 | methods, we can do the following: | ||||
| 338 | |||||
| 339 | validate( | ||||
| 340 | @_, { | ||||
| 341 | foo => | ||||
| 342 | # just has to be able to ->bar | ||||
| 343 | { can => 'bar' } | ||||
| 344 | } | ||||
| 345 | ); | ||||
| 346 | |||||
| 347 | ... or ... | ||||
| 348 | |||||
| 349 | validate( | ||||
| 350 | @_, { | ||||
| 351 | foo => | ||||
| 352 | # must be able to ->bar and ->print | ||||
| 353 | { can => [qw( bar print )] } | ||||
| 354 | } | ||||
| 355 | ); | ||||
| 356 | |||||
| 357 | =head2 Class Validation | ||||
| 358 | |||||
| 359 | A word of warning. When constructing your external interfaces, it is | ||||
| 360 | probably better to specify what methods you expect an object to | ||||
| 361 | have rather than what class it should be of (or a child of). This | ||||
| 362 | will make your API much more flexible. | ||||
| 363 | |||||
| 364 | With that said, if you want to validate that an incoming parameter | ||||
| 365 | belongs to a class (or child class) or classes, do: | ||||
| 366 | |||||
| 367 | validate( | ||||
| 368 | @_, | ||||
| 369 | { foo => { isa => 'My::Frobnicator' } } | ||||
| 370 | ); | ||||
| 371 | |||||
| 372 | ... or ... | ||||
| 373 | |||||
| 374 | validate( | ||||
| 375 | @_, | ||||
| 376 | # must be both, not either! | ||||
| 377 | { foo => { isa => [qw( My::Frobnicator IO::Handle )] } } | ||||
| 378 | ); | ||||
| 379 | |||||
| 380 | =head2 Regex Validation | ||||
| 381 | |||||
| 382 | If you want to specify that a given parameter must match a specific | ||||
| 383 | regular expression, this can be done with "regex" spec key. For | ||||
| 384 | example: | ||||
| 385 | |||||
| 386 | validate( | ||||
| 387 | @_, | ||||
| 388 | { foo => { regex => qr/^\d+$/ } } | ||||
| 389 | ); | ||||
| 390 | |||||
| 391 | The value of the "regex" key may be either a string or a pre-compiled | ||||
| 392 | regex created via C<qr>. | ||||
| 393 | |||||
| 394 | If the value being checked against a regex is undefined, the regex is | ||||
| 395 | explicitly checked against the empty string ('') instead, in order to | ||||
| 396 | avoid "Use of uninitialized value" warnings. | ||||
| 397 | |||||
| 398 | The C<Regexp::Common> module on CPAN is an excellent source of regular | ||||
| 399 | expressions suitable for validating input. | ||||
| 400 | |||||
| 401 | =head2 Callback Validation | ||||
| 402 | |||||
| 403 | If none of the above are enough, it is possible to pass in one or more | ||||
| 404 | callbacks to validate the parameter. The callback will be given the | ||||
| 405 | B<value> of the parameter as its first argument. Its second argument | ||||
| 406 | will be all the parameters, as a reference to either a hash or array. | ||||
| 407 | Callbacks are specified as hash reference. The key is an id for the | ||||
| 408 | callback (used in error messages) and the value is a subroutine | ||||
| 409 | reference, such as: | ||||
| 410 | |||||
| 411 | validate( | ||||
| 412 | @_, { | ||||
| 413 | foo => { | ||||
| 414 | callbacks => { | ||||
| 415 | 'smaller than a breadbox' => sub { shift() < $breadbox }, | ||||
| 416 | 'green or blue' => | ||||
| 417 | sub { $_[0] eq 'green' || $_[0] eq 'blue' } | ||||
| 418 | } | ||||
| 419 | } | ||||
| 420 | ); | ||||
| 421 | |||||
| 422 | validate( | ||||
| 423 | @_, { | ||||
| 424 | foo => { | ||||
| 425 | callbacks => { | ||||
| 426 | 'bigger than baz' => sub { $_[0] > $_[1]->{baz} } | ||||
| 427 | } | ||||
| 428 | } | ||||
| 429 | } | ||||
| 430 | ); | ||||
| 431 | |||||
| 432 | =head2 Untainting | ||||
| 433 | |||||
| 434 | If you want values untainted, set the "untaint" key in a spec hashref | ||||
| 435 | to a true value, like this: | ||||
| 436 | |||||
| 437 | my %p = validate( | ||||
| 438 | @_, { | ||||
| 439 | foo => { type => SCALAR, untaint => 1 }, | ||||
| 440 | bar => { type => ARRAYREF } | ||||
| 441 | } | ||||
| 442 | ); | ||||
| 443 | |||||
| 444 | This will untaint the "foo" parameter if the parameters are valid. | ||||
| 445 | |||||
| 446 | Note that untainting is only done if I<all parameters> are valid. | ||||
| 447 | Also, only the return values are untainted, not the original values | ||||
| 448 | passed into the validation function. | ||||
| 449 | |||||
| 450 | Asking for untainting of a reference value will not do anything, as | ||||
| 451 | C<Params::Validate> will only attempt to untaint the reference itself. | ||||
| 452 | |||||
| 453 | =head2 Mandatory/Optional Revisited | ||||
| 454 | |||||
| 455 | If you want to specify something such as type or interface, plus the | ||||
| 456 | fact that a parameter can be optional, do this: | ||||
| 457 | |||||
| 458 | validate( | ||||
| 459 | @_, { | ||||
| 460 | foo => { type => SCALAR }, | ||||
| 461 | bar => { type => ARRAYREF, optional => 1 } | ||||
| 462 | } | ||||
| 463 | ); | ||||
| 464 | |||||
| 465 | or this for positional parameters: | ||||
| 466 | |||||
| 467 | validate_pos( | ||||
| 468 | @_, | ||||
| 469 | { type => SCALAR }, | ||||
| 470 | { type => ARRAYREF, optional => 1 } | ||||
| 471 | ); | ||||
| 472 | |||||
| 473 | By default, parameters are assumed to be mandatory unless specified as | ||||
| 474 | optional. | ||||
| 475 | |||||
| 476 | =head2 Dependencies | ||||
| 477 | |||||
| 478 | It also possible to specify that a given optional parameter depends on | ||||
| 479 | the presence of one or more other optional parameters. | ||||
| 480 | |||||
| 481 | validate( | ||||
| 482 | @_, { | ||||
| 483 | cc_number => { | ||||
| 484 | type => SCALAR, | ||||
| 485 | optional => 1, | ||||
| 486 | depends => [ 'cc_expiration', 'cc_holder_name' ], | ||||
| 487 | }, | ||||
| 488 | cc_expiration { type => SCALAR, optional => 1 }, | ||||
| 489 | cc_holder_name { type => SCALAR, optional => 1 }, | ||||
| 490 | } | ||||
| 491 | ); | ||||
| 492 | |||||
| 493 | In this case, "cc_number", "cc_expiration", and "cc_holder_name" are | ||||
| 494 | all optional. However, if "cc_number" is provided, then | ||||
| 495 | "cc_expiration" and "cc_holder_name" must be provided as well. | ||||
| 496 | |||||
| 497 | This allows you to group together sets of parameters that all must be | ||||
| 498 | provided together. | ||||
| 499 | |||||
| 500 | The C<validate_pos()> version of dependencies is slightly different, | ||||
| 501 | in that you can only depend on one other parameter. Also, if for | ||||
| 502 | example, the second parameter 2 depends on the fourth parameter, then | ||||
| 503 | it implies a dependency on the third parameter as well. This is | ||||
| 504 | because if the fourth parameter is required, then the user must also | ||||
| 505 | provide a third parameter so that there can be four parameters in | ||||
| 506 | total. | ||||
| 507 | |||||
| 508 | C<Params::Validate> will die if you try to depend on a parameter not | ||||
| 509 | declared as part of your parameter specification. | ||||
| 510 | |||||
| 511 | =head2 Specifying defaults | ||||
| 512 | |||||
| 513 | If the C<validate()> or C<validate_pos()> functions are called in a list | ||||
| 514 | context, they will return a hash or containing the original parameters plus | ||||
| 515 | defaults as indicated by the validation spec. | ||||
| 516 | |||||
| 517 | If the function is not called in a list context, providing a default | ||||
| 518 | in the validation spec still indicates that the parameter is optional. | ||||
| 519 | |||||
| 520 | The hash or array returned from the function will always be a copy of | ||||
| 521 | the original parameters, in order to leave C<@_> untouched for the | ||||
| 522 | calling function. | ||||
| 523 | |||||
| 524 | Simple examples of defaults would be: | ||||
| 525 | |||||
| 526 | my %p = validate( @_, { foo => 1, bar => { default => 99 } } ); | ||||
| 527 | |||||
| 528 | my @p = validate_pos( @_, 1, { default => 99 } ); | ||||
| 529 | |||||
| 530 | In scalar context, a hash reference or array reference will be | ||||
| 531 | returned, as appropriate. | ||||
| 532 | |||||
| 533 | =head1 USAGE NOTES | ||||
| 534 | |||||
| 535 | =head2 Validation failure | ||||
| 536 | |||||
| 537 | By default, when validation fails C<Params::Validate> calls | ||||
| 538 | C<Carp::confess()>. This can be overridden by setting the C<on_fail> | ||||
| 539 | option, which is described in the L<"GLOBAL" OPTIONS|"GLOBAL" OPTIONS> | ||||
| 540 | section. | ||||
| 541 | |||||
| 542 | =head2 Method calls | ||||
| 543 | |||||
| 544 | When using this module to validate the parameters passed to a method | ||||
| 545 | call, you will probably want to remove the class/object from the | ||||
| 546 | parameter list B<before> calling C<validate()> or C<validate_pos()>. | ||||
| 547 | If your method expects named parameters, then this is necessary for | ||||
| 548 | the C<validate()> function to actually work, otherwise C<@_> will not | ||||
| 549 | be usable as a hash, because it will first have your object (or | ||||
| 550 | class) B<followed> by a set of keys and values. | ||||
| 551 | |||||
| 552 | Thus the idiomatic usage of C<validate()> in a method call will look | ||||
| 553 | something like this: | ||||
| 554 | |||||
| 555 | sub method { | ||||
| 556 | my $self = shift; | ||||
| 557 | |||||
| 558 | my %params = validate( | ||||
| 559 | @_, { | ||||
| 560 | foo => 1, | ||||
| 561 | bar => { type => ARRAYREF }, | ||||
| 562 | } | ||||
| 563 | ); | ||||
| 564 | } | ||||
| 565 | |||||
| 566 | =head2 Speeding Up Validation | ||||
| 567 | |||||
| 568 | In most cases, the validation spec will remain the same for each call to a | ||||
| 569 | subroutine. In that case, you can speed up validation by defining the | ||||
| 570 | validation spec just once, rather than on each call to the subroutine: | ||||
| 571 | |||||
| 572 | my %spec = ( ... ); | ||||
| 573 | sub foo { | ||||
| 574 | my %params = validate( @_, \%spec ); | ||||
| 575 | } | ||||
| 576 | |||||
| 577 | You can also use the C<state> feature to do this: | ||||
| 578 | |||||
| 579 | use feature 'state'; | ||||
| 580 | |||||
| 581 | sub foo { | ||||
| 582 | state %spec = ( ... ); | ||||
| 583 | my %params = validate( @_, \%spec ); | ||||
| 584 | } | ||||
| 585 | |||||
| 586 | =head1 "GLOBAL" OPTIONS | ||||
| 587 | |||||
| 588 | Because the API for the C<validate()> and C<validate_pos()> functions does not | ||||
| 589 | make it possible to specify any options other than the validation spec, it is | ||||
| 590 | possible to set some options as pseudo-'globals'. These allow you to specify | ||||
| 591 | such things as whether or not the validation of named parameters should be | ||||
| 592 | case sensitive, for one example. | ||||
| 593 | |||||
| 594 | These options are called pseudo-'globals' because these settings are | ||||
| 595 | B<only applied to calls originating from the package that set the | ||||
| 596 | options>. | ||||
| 597 | |||||
| 598 | In other words, if I am in package C<Foo> and I call | ||||
| 599 | C<validation_options()>, those options are only in effect when I call | ||||
| 600 | C<validate()> from package C<Foo>. | ||||
| 601 | |||||
| 602 | While this is quite different from how most other modules operate, I | ||||
| 603 | feel that this is necessary in able to make it possible for one | ||||
| 604 | module/application to use Params::Validate while still using other | ||||
| 605 | modules that also use Params::Validate, perhaps with different | ||||
| 606 | options set. | ||||
| 607 | |||||
| 608 | The downside to this is that if you are writing an app with a standard | ||||
| 609 | calling style for all functions, and your app has ten modules, B<each | ||||
| 610 | module must include a call to C<validation_options()>>. You could of | ||||
| 611 | course write a module that all your modules use which uses various | ||||
| 612 | trickery to do this when imported. | ||||
| 613 | |||||
| 614 | =head2 Options | ||||
| 615 | |||||
| 616 | =over 4 | ||||
| 617 | |||||
| 618 | =item * normalize_keys => $callback | ||||
| 619 | |||||
| 620 | This option is only relevant when dealing with named parameters. | ||||
| 621 | |||||
| 622 | This callback will be used to transform the hash keys of both the | ||||
| 623 | parameters and the parameter spec when C<validate()> or | ||||
| 624 | C<validate_with()> are called. | ||||
| 625 | |||||
| 626 | Any alterations made by this callback will be reflected in the | ||||
| 627 | parameter hash that is returned by the validation function. For | ||||
| 628 | example: | ||||
| 629 | |||||
| 630 | sub foo { | ||||
| 631 | return validate_with( | ||||
| 632 | params => \@_, | ||||
| 633 | spec => { foo => { type => SCALAR } }, | ||||
| 634 | normalize_keys => | ||||
| 635 | sub { my $k = shift; $k =~ s/^-//; return uc $k }, | ||||
| 636 | ); | ||||
| 637 | |||||
| 638 | } | ||||
| 639 | |||||
| 640 | %p = foo( foo => 20 ); | ||||
| 641 | |||||
| 642 | # $p{FOO} is now 20 | ||||
| 643 | |||||
| 644 | %p = foo( -fOo => 50 ); | ||||
| 645 | |||||
| 646 | # $p{FOO} is now 50 | ||||
| 647 | |||||
| 648 | The callback must return a defined value. | ||||
| 649 | |||||
| 650 | If a callback is given then the deprecated "ignore_case" and | ||||
| 651 | "strip_leading" options are ignored. | ||||
| 652 | |||||
| 653 | =item * allow_extra => $boolean | ||||
| 654 | |||||
| 655 | If true, then the validation routine will allow extra parameters not | ||||
| 656 | named in the validation specification. In the case of positional | ||||
| 657 | parameters, this allows an unlimited number of maximum parameters | ||||
| 658 | (though a minimum may still be set). Defaults to false. | ||||
| 659 | |||||
| 660 | =item * on_fail => $callback | ||||
| 661 | |||||
| 662 | If given, this callback will be called whenever a validation check | ||||
| 663 | fails. It will be called with a single parameter, which will be a | ||||
| 664 | string describing the failure. This is useful if you wish to have | ||||
| 665 | this module throw exceptions as objects rather than as strings, for | ||||
| 666 | example. | ||||
| 667 | |||||
| 668 | This callback is expected to C<die()> internally. If it does not, the | ||||
| 669 | validation will proceed onwards, with unpredictable results. | ||||
| 670 | |||||
| 671 | The default is to simply use the Carp module's C<confess()> function. | ||||
| 672 | |||||
| 673 | =item * stack_skip => $number | ||||
| 674 | |||||
| 675 | This tells Params::Validate how many stack frames to skip when finding | ||||
| 676 | a subroutine name to use in error messages. By default, it looks one | ||||
| 677 | frame back, at the immediate caller to C<validate()> or | ||||
| 678 | C<validate_pos()>. If this option is set, then the given number of | ||||
| 679 | frames are skipped instead. | ||||
| 680 | |||||
| 681 | =item * ignore_case => $boolean | ||||
| 682 | |||||
| 683 | DEPRECATED | ||||
| 684 | |||||
| 685 | This is only relevant when dealing with named parameters. If it is | ||||
| 686 | true, then the validation code will ignore the case of parameter | ||||
| 687 | names. Defaults to false. | ||||
| 688 | |||||
| 689 | =item * strip_leading => $characters | ||||
| 690 | |||||
| 691 | DEPRECATED | ||||
| 692 | |||||
| 693 | This too is only relevant when dealing with named parameters. If this | ||||
| 694 | is given then any parameters starting with these characters will be | ||||
| 695 | considered equivalent to parameters without them entirely. For | ||||
| 696 | example, if this is specified as '-', then C<-foo> and C<foo> would be | ||||
| 697 | considered identical. | ||||
| 698 | |||||
| 699 | =back | ||||
| 700 | |||||
| 701 | =head1 PER-INVOCATION OPTIONS | ||||
| 702 | |||||
| 703 | The C<validate_with()> function can be used to set the options listed | ||||
| 704 | above on a per-invocation basis. For example: | ||||
| 705 | |||||
| 706 | my %p = validate_with( | ||||
| 707 | params => \@_, | ||||
| 708 | spec => { | ||||
| 709 | foo => { type => SCALAR }, | ||||
| 710 | bar => { default => 10 } | ||||
| 711 | }, | ||||
| 712 | allow_extra => 1, | ||||
| 713 | ); | ||||
| 714 | |||||
| 715 | In addition to the options listed above, it is also possible to set | ||||
| 716 | the option "called", which should be a string. This string will be | ||||
| 717 | used in any error messages caused by a failure to meet the validation | ||||
| 718 | spec. | ||||
| 719 | |||||
| 720 | This subroutine will validate named parameters as a hash if the "spec" | ||||
| 721 | parameter is a hash reference. If it is an array reference, the | ||||
| 722 | parameters are assumed to be positional. | ||||
| 723 | |||||
| 724 | my %p = validate_with( | ||||
| 725 | params => \@_, | ||||
| 726 | spec => { | ||||
| 727 | foo => { type => SCALAR }, | ||||
| 728 | bar => { default => 10 } | ||||
| 729 | }, | ||||
| 730 | allow_extra => 1, | ||||
| 731 | called => 'The Quux::Baz class constructor', | ||||
| 732 | ); | ||||
| 733 | |||||
| 734 | my @p = validate_with( | ||||
| 735 | params => \@_, | ||||
| 736 | spec => [ | ||||
| 737 | { type => SCALAR }, | ||||
| 738 | { default => 10 } | ||||
| 739 | ], | ||||
| 740 | allow_extra => 1, | ||||
| 741 | called => 'The Quux::Baz class constructor', | ||||
| 742 | ); | ||||
| 743 | |||||
| 744 | =head1 DISABLING VALIDATION | ||||
| 745 | |||||
| 746 | If the environment variable C<PERL_NO_VALIDATION> is set to something | ||||
| 747 | true, then validation is turned off. This may be useful if you only | ||||
| 748 | want to use this module during development but don't want the speed | ||||
| 749 | hit during production. | ||||
| 750 | |||||
| 751 | The only error that will be caught will be when an odd number of | ||||
| 752 | parameters are passed into a function/method that expects a hash. | ||||
| 753 | |||||
| 754 | If you want to selectively turn validation on and off at runtime, you | ||||
| 755 | can directly set the C<$Params::Validate::NO_VALIDATION> global | ||||
| 756 | variable. It is B<strongly> recommended that you B<localize> any | ||||
| 757 | changes to this variable, because other modules you are using may | ||||
| 758 | expect validation to be on when they execute. For example: | ||||
| 759 | |||||
| 760 | { | ||||
| 761 | local $Params::Validate::NO_VALIDATION = 1; | ||||
| 762 | |||||
| 763 | # no error | ||||
| 764 | foo( bar => 2 ); | ||||
| 765 | } | ||||
| 766 | |||||
| 767 | # error | ||||
| 768 | foo( bar => 2 ); | ||||
| 769 | |||||
| 770 | sub foo { | ||||
| 771 | my %p = validate( @_, { foo => 1 } ); | ||||
| 772 | ...; | ||||
| 773 | } | ||||
| 774 | |||||
| 775 | But if you want to shoot yourself in the foot and just turn it off, go | ||||
| 776 | ahead! | ||||
| 777 | |||||
| 778 | =head1 LIMITATIONS | ||||
| 779 | |||||
| 780 | Right now there is no way (short of a callback) to specify that | ||||
| 781 | something must be of one of a list of classes, or that it must possess | ||||
| 782 | one of a list of methods. If this is desired, it can be added in the | ||||
| 783 | future. | ||||
| 784 | |||||
| 785 | Ideally, there would be only one validation function. If someone | ||||
| 786 | figures out how to do this, please let me know. | ||||
| 787 | |||||
| 788 | =head1 SUPPORT | ||||
| 789 | |||||
| 790 | Please submit bugs and patches to the CPAN RT system at | ||||
| 791 | http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Params%3A%3AValidate or | ||||
| 792 | via email at bug-params-validate@rt.cpan.org. | ||||
| 793 | |||||
| 794 | Support questions can be sent to Dave at autarch@urth.org. | ||||
| 795 | |||||
| 796 | =head1 DONATIONS | ||||
| 797 | |||||
| 798 | If you'd like to thank me for the work I've done on this module, | ||||
| 799 | please consider making a "donation" to me via PayPal. I spend a lot of | ||||
| 800 | free time creating free software, and would appreciate any support | ||||
| 801 | you'd care to offer. | ||||
| 802 | |||||
| 803 | Please note that B<I am not suggesting that you must do this> in order | ||||
| 804 | for me to continue working on this particular software. I will | ||||
| 805 | continue to do so, inasmuch as I have in the past, for as long as it | ||||
| 806 | interests me. | ||||
| 807 | |||||
| 808 | Similarly, a donation made in this way will probably not make me work | ||||
| 809 | on this software much more, unless I get so many donations that I can | ||||
| 810 | consider working on free software full time, which seems unlikely at | ||||
| 811 | best. | ||||
| 812 | |||||
| 813 | To donate, log into PayPal and send money to autarch@urth.org or use | ||||
| 814 | the button on this page: | ||||
| 815 | L<http://www.urth.org/~autarch/fs-donation.html> | ||||
| 816 | |||||
| 817 | =head1 AUTHOR | ||||
| 818 | |||||
| 819 | Dave Rolsky, <autarch@urth.org> and Ilya Martynov <ilya@martynov.org> | ||||
| 820 | |||||
| 821 | =head1 COPYRIGHT AND LICENSE | ||||
| 822 | |||||
| 823 | This software is Copyright (c) 2012 by Dave Rolsky and Ilya Martynov. | ||||
| 824 | |||||
| 825 | This is free software, licensed under: | ||||
| 826 | |||||
| 827 | The Artistic License 2.0 (GPL Compatible) | ||||
| 828 | |||||
| 829 | =cut | ||||
| 830 | |||||
| 831 | |||||
| 832 | __END__ |