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 | BEGIN@13 | Params::Validate::
1 | 1 | 1 | 26µs | 26µs | BEGIN@6 | Params::Validate::
1 | 1 | 1 | 8µs | 8µs | BEGIN@12 | Params::Validate::
1 | 1 | 1 | 8µs | 53µs | BEGIN@15 | Params::Validate::
1 | 1 | 1 | 7µs | 22µs | BEGIN@11 | Params::Validate::
1 | 1 | 1 | 6µs | 14µs | BEGIN@9 | Params::Validate::
1 | 1 | 1 | 6µs | 8µs | BEGIN@8 | Params::Validate::
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 | 2 | 4µ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 | 1 | 400ns | $ENV{PARAMS_VALIDATE_IMPLEMENTATION} = 'PP' if $ENV{PV_TEST_PERL}; | ||
65 | |||||
66 | 1 | 4µs | 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__ |