Profile of /usr/local/lib/perl5/site_perl/5.10.1/darwin-2level/Params/Validate.pm

← Index
NYTProf Performance Profile «block view•line view•sub view»
For 05.Domain_and_Item.t
Run on Tue May 4 17:21:41 2010
Reported on Tue May 4 17:22:49 2010

File | /usr/local/lib/perl5/site_perl/5.10.1/darwin-2level/Params/Validate.pm
Statements Executed | 21
Statement Execution Time | 327µs

Subroutines — ordered by exclusive time
Calls | P | F | Exclusive Time | Inclusive Time | Subroutine
--- | --- | --- | --- | --- | ---
1 | 1 | 1 | 414µs | 714µs | Params::Validate::::BEGIN@5Params::Validate::BEGIN@5
1 | 1 | 1 | 10µs | 38µs | Params::Validate::::BEGIN@6Params::Validate::BEGIN@6
1 | 1 | 1 | 6µs | 99µs | Params::Validate::::BEGIN@7Params::Validate::BEGIN@7

Call graph for these subroutines as a Graphviz dot language file.

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 BEGIN {
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 use Exporter; # 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 use vars qw( $VERSION @ISA @EXPORT @EXPORT_OK # 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