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