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