Profile of Params/Validate.pm

← Index
NYTProf Performance Profile «block view•line view•sub view»
For xt/tapper-mcp-scheduler-with-db-longrun.t
Run on Tue May 22 17:18:39 2012
Reported on Tue May 22 17:22:36 2012

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

Subroutines
Calls | P | F | Exclusive Time | Inclusive Time | Subroutine
--- | --- | --- | --- | --- | ---
1 | 1 | 1 | 229µs | 322µs | Params::Validate::::BEGIN@13Params::Validate::BEGIN@13
1 | 1 | 1 | 26µs | 26µs | Params::Validate::::BEGIN@6Params::Validate::BEGIN@6
1 | 1 | 1 | 8µs | 8µs | Params::Validate::::BEGIN@12Params::Validate::BEGIN@12
1 | 1 | 1 | 8µs | 53µs | Params::Validate::::BEGIN@15Params::Validate::BEGIN@15
1 | 1 | 1 | 7µs | 22µs | Params::Validate::::BEGIN@11Params::Validate::BEGIN@11
1 | 1 | 1 | 6µs | 14µs | Params::Validate::::BEGIN@9Params::Validate::BEGIN@9
1 | 1 | 1 | 6µs | 8µs | Params::Validate::::BEGIN@8Params::Validate::BEGIN@8

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 | 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 use 5.008001; # 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 use strict; # 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 use warnings; # 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 use Exporter; # 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 use Module::Implementation; # 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 use Params::Validate::Constants; # 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 use vars qw( $NO_VALIDATION %OPTIONS $options ); # 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__