blib/lib/Params/Check/Faster.pm

filter: Statementstmt 92.4% 159 / 172 Branchbran 81.4% 70 / 86 Conditioncond 72.2% 39 / 54 MC/DCmcdc 48.2% 14 / 29 Subroutinesub 100% 15 / 15 Podpod 100% 3 / 3 totaltotal 83.5% 300 / 359 CC 68 SCAR 34.4
CC
68
Cov
86%
check
50.3
_store_var
14.3
allow
8.1
CRAP 31.2
↑ Summary
1 package Params::Check::Faster;
2  
3 1 ▶use 5.006; #warnings.pm
Subroutine BEGIN: called CC=1 SCAR=0.0
4 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 1 ▶use Carp qw[carp croak];
Subroutine BEGIN: called CC=1 SCAR=0.0
7 1 ▶use Locale::Maketext::Simple Style => 'gettext';
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 1 ▶BEGIN {
Subroutine BEGIN: called CC=2 SCAR=6.9
10 1 ▶ use Exporter ();
Subroutine BEGIN: called CC=1 SCAR=0.0
11 1 ▶ use vars qw[ @ISA $VERSION @EXPORT_OK $VERBOSE $ALLOW_UNKNOWN
Subroutine BEGIN: called CC=1 SCAR=0.0
12 $STRICT_TYPE $STRIP_LEADING_DASHES $NO_DUPLICATES
13 $PRESERVE_CASE $ONLY_ALLOW_DEFINED $WARNINGS_FATAL
14 $SANITY_CHECK_TEMPLATE $CALLER_DEPTH $_ERROR_STRING
15 1 ];
16  
17 1 @ISA = qw[ Exporter ];
18 1 @EXPORT_OK = qw[check allow last_error];
19  
20 1 $VERSION = '0.04';
21 1 ▶ $VERBOSE = $^W ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$^W ? : 0 1 1
22 1 $NO_DUPLICATES = 0;
23 1 $STRIP_LEADING_DASHES = 0;
24 1 $STRICT_TYPE = 0;
25 1 $ALLOW_UNKNOWN = 0;
26 1 $PRESERVE_CASE = 0;
27 1 $ONLY_ALLOW_DEFINED = 0;
28 1 $SANITY_CHECK_TEMPLATE = 1;
29 1 $WARNINGS_FATAL = 0;
30 1 $CALLER_DEPTH = 0;
31 }
32  
33 1 my %known_keys = map { $_ => 1 }
34 qw| required allow default strict_type no_override
35 store defined |;
36  
37 =pod
38  
39 =head1 NAME
40  
41 Params::Check::Faster - A generic input parsing/checking mechanism. Reimplementation of Params::Check.
42  
43 =head1 SYNOPSIS
44  
45 use Params::Check::Faster qw[check allow last_error];
46  
47 sub fill_personal_info {
48 my %hash = @_;
49 my $x;
50  
51 my $tmpl = {
52 firstname => { required => 1, defined => 1 },
53 lastname => { required => 1, store => \$x },
54 gender => { required => 1,
55 allow => [qr/M/i, qr/F/i],
56 },
57 married => { allow => [0,1] },
58 age => { default => 21,
59 allow => qr/^\d+$/,
60 },
61  
62 phone => { allow => [ sub { return 1 if /$valid_re/ },
63 '1-800-PERL' ]
64 },
65 id_list => { default => [],
66 strict_type => 1
67 },
68 employer => { default => 'NSA', no_override => 1 },
69 };
70  
71 ### check() returns a hashref of parsed args on success ###
72 my $parsed_args = check( $tmpl, \%hash, $VERBOSE )
73 or die qw[Could not parse arguments!];
74  
75 ... other code here ...
76 }
77  
78 my $ok = allow( $colour, [qw|blue green yellow|] );
79  
80 my $error = Params::Check::Faster::last_error();
81  
82  
83 =head1 DESCRIPTION
84  
85 Params::Check::Faster is a generic input parsing/checking mechanism.
86  
87 This module is a faster reimplementation of Params::Check. It should be 100%
88 compatible. It might be merged with Params::Check at some point, after its author (kane) has reviewed it and is happy with merging it.
89  
90 It allows you to validate input via a template. The only requirement
91 is that the arguments must be named.
92  
93 Params::Check::Faster can do the following things for you:
94  
95 =over 4
96  
97 =item *
98  
99 Convert all keys to lowercase
100  
101 =item *
102  
103 Check if all required arguments have been provided
104  
105 =item *
106  
107 Set arguments that have not been provided to the default
108  
109 =item *
110  
111 Weed out arguments that are not supported and warn about them to the
112 user
113  
114 =item *
115  
116 Validate the arguments given by the user based on strings, regexes,
117 lists or even subroutines
118  
119 =item *
120  
121 Enforce type integrity if required
122  
123 =back
124  
125 Most of Params::Check::Faster's power comes from its template, which we'll
126 discuss below:
127  
128 =head1 Template
129  
130 As you can see in the synopsis, based on your template, the arguments
131 provided will be validated.
132  
133 The template can take a different set of rules per key that is used.
134  
135 The following rules are available:
136  
137 =over 4
138  
139 =item default
140  
141 This is the default value if none was provided by the user.
142 This is also the type C<strict_type> will look at when checking type
143 integrity (see below).
144  
145 =item required
146  
147 A boolean flag that indicates if this argument was a required
148 argument. If marked as required and not provided, check() will fail.
149  
150 =item strict_type
151  
152 This does a C<ref()> check on the argument provided. The C<ref> of the
153 argument must be the same as the C<ref> of the default value for this
154 check to pass.
155  
156 This is very useful if you insist on taking an array reference as
157 argument for example.
158  
159 =item defined
160  
161 If this template key is true, enforces that if this key is provided by
162 user input, its value is C<defined>. This just means that the user is
163 not allowed to pass C<undef> as a value for this key and is equivalent
164 to:
165 allow => sub { defined $_[0] && OTHER TESTS }
166  
167 =item no_override
168  
169 This allows you to specify C<constants> in your template. ie, they
170 keys that are not allowed to be altered by the user. It pretty much
171 allows you to keep all your C<configurable> data in one place; the
172 C<Params::Check::Faster> template.
173  
174 =item store
175  
176 This allows you to pass a reference to a scalar, in which the data
177 will be stored:
178  
179 my $x;
180 my $args = check(foo => { default => 1, store => \$x }, $input);
181  
182 This is basically shorthand for saying:
183  
184 my $args = check( { foo => { default => 1 } }, $input );
185 my $x = $args->{foo};
186  
187 It works for arrays or hash reference too. You can write :
188  
189 my @array;
190 my %hash;
191 my $args = check(foo => { default => [ 1 ], store => \@array },
192 bar => { default => { answer => 42 }, store => \%hash },
193 $input);
194  
195 And @array and %hash contains directly the corresponding array or hash dereferenced.
196  
197  
198 You can alter the global variable $Params::Check::Faster::NO_DUPLICATES to
199 control whether the C<store>'d key will still be present in your
200 result set. See the L<Global Variables> section below.
201  
202 =item allow
203  
204 A set of criteria used to validate a particular piece of data if it
205 has to adhere to particular rules.
206  
207 See the C<allow()> function for details.
208  
209 =back
210  
211 =head1 Functions
212  
213 =head2 check( \%tmpl, \%args, [$verbose] );
214  
215 This function is not exported by default, so you'll have to ask for it
216 via:
217  
218 use Params::Check::Faster qw[check];
219  
220 or use its fully qualified name instead.
221  
222 C<check> takes a list of arguments, as follows:
223  
224 =over 4
225  
226 =item Template
227  
228 This is a hashreference which contains a template as explained in the
229 C<SYNOPSIS> and C<Template> section.
230  
231 =item Arguments
232  
233 This is a reference to a hash of named arguments which need checking.
234  
235 =item Verbose
236  
237 A boolean to indicate whether C<check> should be verbose and warn
238 about what went wrong in a check or not.
239  
240 You can enable this program wide by setting the package variable
241 C<$Params::Check::Faster::VERBOSE> to a true value. For details, see the
242 section on C<Global Variables> below.
243  
244 =back
245  
246 C<check> will return when it fails, or a hashref with lowercase
247 keys of parsed arguments when it succeeds.
248  
249 So a typical call to check would look like this:
250  
251 my $parsed = check( \%template, \%arguments, $VERBOSE )
252 or warn q[Arguments could not be parsed!];
253  
254 A lot of the behaviour of C<check()> can be altered by setting
255 package variables. See the section on C<Global Variables> for details
256 on this.
257  
258 =cut
259  
260  
261 38 ▶sub check {
Subroutine check: called CC=46 SCAR=39.2
Pod documented
262 # for speed purpose we don't copy @_; check if we have anything to work on
263 38 ▶ if (!$_[0] || !$_[1]) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($_[0] and $_[1]) 0 38 38
Condition33%1/3
$_[0] and $_[1]
!ll&&!rl&&r
0038
MC/DC0%0/2
$_[0] and $_[1]
$_[0] $_[1]
Truth table33%1/3
A and B
A= $_[0]B= $_[1]
ABresult
0X0
100
111
264 0 return;
265 }
266  
267 38 my %template = %{$_[0]};
268 38 my %args = %{$_[1]};
269 38 ▶ my $verbose = $_[2] || $VERBOSE || 0;
Condition40%2/5
$_[2] || $Params::Check::Faster::VERBOSE || 0
l!l
038
$_[2] or $Params::Check::Faster::VERBOSE
l!l&&r!l&&!r
0038
MC/DC0%0/2
$_[2] || $Params::Check::Faster::VERBOSE || 0
$_[2] $Params::Check::Faster::VERBOSE
Truth table33%1/3
A or B
A= $_[2]B= $Params::Check::Faster::VERBOSE
ABresult
1X1
011
000
270  
271 # clear current error
272 38 _clear_error();
273  
274 # flag to see if we warned for anything, needed for warnings_fatal
275 38 my $warned;
276  
277 # flag to see if anything went wrong
278 my $wrong;
279  
280 # key to remove from the args, if unauthorised
281 38 my @keys_to_remove = ();
282  
283 # keys to rename : [ old_key_name, new_key_name]
284 38 my @keys_to_rename = ();
285  
286 # list of values to store into ref : [ $type, $ref, $value ]
287 38 my @to_store = ();
288  
289 # list of keys to delete from args
290 38 my @to_delete = ();
291  
292 # ARG_LOOP:
293 # loop on the arguments
294 38 ▶ while (my ($arg_key, $arg_value) = each %args) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %args) 41 38 79
295  
296 # handle key name
297 41 ▶ if (!$PRESERVE_CASE || $STRIP_LEADING_DASHES) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $Params::Check::Faster::PRESERVE_CASE or $Params::Check::Faster::STRIP_LEADING_DASHES) 40 1 41
Condition66%2/3
not $Params::Check::Faster::PRESERVE_CASE or $Params::Check::Faster::STRIP_LEADING_DASHES
l!l&&r!l&&!r
4001
MC/DC50%1/2
not $Params::Check::Faster::PRESERVE_CASE or $Params::Check::Faster::STRIP_LEADING_DASHES
not $Params::Check::Faster::PRESERVE_CASE $Params::Check::Faster::STRIP_LEADING_DASHES
Truth table66%2/3
not(A) or B
A= not $Params::Check::Faster::PRESERVE_CASEB= $Params::Check::Faster::STRIP_LEADING_DASHES
ABresult
1X1
011
000
298 40 my $orig_arg_key = $arg_key;
299 40 ▶ $arg_key = lc($arg_key) unless $PRESERVE_CASE;
Branch: 1 branch
BranchTrueFalseTotal
unless $Params::Check::Faster::PRESERVE_CASE 40 0 40
300 40 ▶ $arg_key =~ s/^-// if $STRIP_LEADING_DASHES;
Branch: 1 branch
BranchTrueFalseTotal
if $Params::Check::Faster::STRIP_LEADING_DASHES 1 39 40
301 40 ▶ if ($arg_key ne $orig_arg_key) {
Branch: 1 branch
BranchTrueFalseTotal
if ($arg_key ne $orig_arg_key) 3 37 40
302 3 push @keys_to_rename, [ $arg_key, $orig_arg_key ];
303 }
304 }
305  
306 # the argument doesn't exist in the template
307 41 ▶ if ( !exists $template{$arg_key} ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $template{$arg_key}) 3 38 41
308 3 ▶ if (!$ALLOW_UNKNOWN) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($Params::Check::Faster::ALLOW_UNKNOWN) 2 1 3
309 2 _store_error(
310 loc(q(Key '%1' is not a valid key for %2 provided by %3),
311 $arg_key, _who_was_it(), _who_was_it(1)), $verbose);
312 2 $warned = 1;
313 2 push @keys_to_remove, $arg_key;
314 }
315 3 next;
316 };
317  
318 # copy of this keys template instructions, to save derefs
319 38 my %arg_template = %{delete $template{$arg_key} };
320  
321 38 ▶ if ($SANITY_CHECK_TEMPLATE) {
Branch: 1 branch
BranchTrueFalseTotal
if ($Params::Check::Faster::SANITY_CHECK_TEMPLATE) 38 0 38
322 38 foreach(grep { ! $known_keys{$_} } keys %arg_template) {
323 0 _store_error(loc(q(Template type '%1' not supported [at key '%2']),
324 $_, $arg_key), $verbose)
325 }
326 }
327  
328 # the argument cannot be overridden
329 38 ▶ if ($arg_template{no_override}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($arg_template{"no_override"}) 1 37 38
330 1 _store_error(
331 loc(q(You are not allowed to override key '%1' for %2 from %3),
332 $arg_key, _who_was_it(), _who_was_it(1)),
333 $verbose
334 );
335 1 $warned = 1;
336 1 push @keys_to_remove, $arg_key;
337 1 $template{$arg_key} = \%arg_template;
338 1 next;
339 }
340  
341 # check if you were supposed to provide defined() values
342 37 ▶ if ( ($arg_template{defined} || $ONLY_ALLOW_DEFINED) && !defined $arg_value ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($arg_template{"defined"} || $Params::Check::Faster::ONLY_ALLOW_DEFINED and not defined $arg_value) 4 33 37
Condition100%6/6
$arg_template{"defined"} || $Params::Check::Faster::ONLY_ALLOW_DEFINED and not defined $arg_value
!ll&&!rl&&r
3034
$arg_template{"defined"} or $Params::Check::Faster::ONLY_ALLOW_DEFINED
l!l&&r!l&&!r
5230
MC/DC100%3/3
$arg_template{"defined"} || $Params::Check::Faster::ONLY_ALLOW_DEFINED and not defined $arg_value
$arg_template{"defined"} $Params::Check::Faster::ONLY_ALLOW_DEFINED not defined $arg_value
Truth table100%5/5
A or B and not(C)
A= $arg_template{"defined"}B= $Params::Check::Faster::ONLY_ALLOW_DEFINEDC= not defined $arg_value
ABCresult
00X0
1X00
0100
1X11
0111
343 4 _store_error(loc(q(Key '%1' must be defined when passed), $arg_key),
344 $verbose );
345 4 $wrong = 1;
346 4 push @keys_to_remove, $arg_key;
347 4 $template{$arg_key} = \%arg_template;
348 4 next;
349 }
350  
351 # check if they should be of a strict type, and if it is
352 33 ▶ if ( ($arg_template{strict_type} || $STRICT_TYPE) && ref $arg_value ne ref $arg_template{default}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($arg_template{"strict_type"} || $Params::Check::Faster::STRICT_TYPE and ref $arg_value ne ref $arg_template{"default"}) 2 31 33
Condition100%6/6
$arg_template{"strict_type"} || $Params::Check::Faster::STRICT_TYPE and ref $arg_value ne ref $arg_template{"default"}
!ll&&!rl&&r
2832
$arg_template{"strict_type"} or $Params::Check::Faster::STRICT_TYPE
l!l&&r!l&&!r
3228
MC/DC100%3/3
$arg_template{"strict_type"} || $Params::Check::Faster::STRICT_TYPE and ref $arg_value ne ref $arg_template{"default"}
$arg_template{"strict_type"} $Params::Check::Faster::STRICT_TYPE ref $arg_value ne ref $arg_template{"default"}
Truth table100%5/5
A or B and C
A= $arg_template{"strict_type"}B= $Params::Check::Faster::STRICT_TYPEC= ref $arg_value ne ref $arg_template{"default"}
ABCresult
00X0
1X00
0100
1X11
0111
353 _store_error(loc(q(Key '%1' needs to be of type '%2'),
354 2 ▶ $arg_key, ref($arg_template{default}) || 'SCALAR'),
Condition50%1/2
ref $arg_template{'default'} || 'SCALAR'
l!l
20
MC/DC0%0/1
ref $arg_template{'default'} || 'SCALAR'
ref $arg_template{'default'}
Truth table50%1/2
A
A= ref $arg_template{'default'}
Aresult
11
00
355 $verbose );
356 2 $wrong = 1;
357 2 push @keys_to_remove, $arg_key;
358 2 $template{$arg_key} = \%arg_template;
359 2 next;
360 }
361  
362 # check if we have an allow handler, to validate against
363 # allow() will report its own errors
364 31 ▶ if (exists $arg_template{allow} && !do {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $arg_template{"allow"} and not do { local $Params::Check::Faster::_ERROR_STRING; allow($arg_value, $arg_template{"allow"}) }) 5 26 31
Condition100%3/3
exists $arg_template{"allow"} and not do { local $Params::Check::Faster::_ERROR_STRING; allow($arg_value, $arg_template{"allow"}) }
!ll&&!rl&&r
1795
MC/DC100%2/2
exists $arg_template{"allow"} and not do { local $Params::Check::Faster::_ERROR_STRING; allow($arg_value, $arg_template{"allow"}) }
exists $arg_template{"allow"} not do { local $Params::Check::Faster::_ERROR_STRING; allow($arg_value, $arg_template{"allow"}) }
Truth table100%3/3
A and not(B)
A= exists $arg_template{"allow"}B= not do { local $Params::Check::Faster::_ERROR_STRING; allow($arg_value, $arg_template{"allow"}) }
ABresult
0X0
100
111
365 14 local $_ERROR_STRING;
366 allow($arg_value, $arg_template{allow})
367 14 }) {
368 # stringify the value in the error report -- we don't want dumps
369 # of objects, but we do want to see *roughly* what we passed
370 5 _store_error(loc(q(Key '%1' (%2) is of invalid type for '%3' provided by %4),
371 $arg_key, $arg_value, _who_was_it(),
372 _who_was_it(1)), $verbose);
373 5 $wrong = 1;
374 5 push @keys_to_remove, $arg_key;
375 5 $template{$arg_key} = \%arg_template;
376 5 next;
377 }
378  
379 # check if we need to store the argument value to a provided ref
380 26 ▶ if (my $ref = $arg_template{store}) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $ref = $arg_template{"store"}) 6 20 26
381 6 ▶ if ( !_store_var($arg_key, $ref, $arg_value, $verbose, \@to_store, \@to_delete)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (_store_var($arg_key, $ref, $arg_value, $verbose, \@to_store, \@to_delete)) 0 6 6
382 0 $wrong = 1;
383 0 next;
384 }
385 }
386 }
387  
388  
389 # if we needed to rename keys
390 38 foreach (@keys_to_rename) {
391 3 $args{$_->[0]} = delete $args{$_->[1]};
392 }
393  
394 # if we needed to remove unknown keys, so that default applies
395 38 ▶ if (@keys_to_remove) {
Branch: 1 branch
BranchTrueFalseTotal
if (@keys_to_remove) 14 24 38
396 14 delete @args{@keys_to_remove};
397 }
398  
399 # now check if there is any key left in the template
400 38 ▶ while (my ($t_key, $t_value) = each %template) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %template) 20 38 58
401  
402 # check if required key is missing
403 20 ▶ if ($t_value->{required}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($t_value->{"required"}) 3 17 20
404 3 _store_error(
405 loc(q(Required option '%1' is not provided for %2 by %3),
406 $t_key, _who_was_it(), _who_was_it(1)), $verbose );
407 3 $wrong = 1;
408 3 next;
409 }
410  
411 # set default argument omitted
412 17 ▶ if (exists $t_value->{default}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $t_value->{"default"}) 9 8 17
413 9 $args{$t_key} = $t_value->{default};
414 # check if we need to store the default value to a provided ref
415 9 ▶ if (my $ref = $t_value->{store}) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $ref = $t_value->{"store"}) 0 9 9
416 0 ▶ if (!_store_var($t_key, $ref, $t_value->{default}, $verbose, \@to_store, \@to_delete)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (_store_var($t_key, $ref, $t_value->{"default"}, $verbose, \@to_store, \@to_delete)) 0 0 0
417 0 $wrong = 1;
418 0 next;
419 }
420 }
421 }
422 # special case to be backward compatible
423 17 ▶ if ($SANITY_CHECK_TEMPLATE && exists $t_value->{store} && !ref $t_value->{store} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($Params::Check::Faster::SANITY_CHECK_TEMPLATE and exists $t_value->{"store"} and not ref $t_value->{"store"}) 1 16 17
Condition66%4/6
$Params::Check::Faster::SANITY_CHECK_TEMPLATE and exists $t_value->{"store"} and not ref $t_value->{"store"}
!ll&&!rl&&r
1601
$Params::Check::Faster::SANITY_CHECK_TEMPLATE and exists $t_value->{"store"}
!ll&&!rl&&r
0161
MC/DC33%1/3
$Params::Check::Faster::SANITY_CHECK_TEMPLATE and exists $t_value->{"store"} and not ref $t_value->{"store"}
$Params::Check::Faster::SANITY_CHECK_TEMPLATE exists $t_value->{"store"} not ref $t_value->{"store"}
Truth table50%2/4
A and B and not(C)
A= $Params::Check::Faster::SANITY_CHECK_TEMPLATEB= exists $t_value->{"store"}C= not ref $t_value->{"store"}
ABCresult
0XX0
10X0
1100
1111
424 1 _store_error( loc(
425 q(Store variable for '%1' is not a reference!), $t_key
426 ), $verbose);
427 }
428  
429 }
430  
431 # croak with the collected errors if there were errors and we have the
432 # fatal flag toggled.
433 38 ▶ if ( ($wrong || $warned) && $WARNINGS_FATAL) {
Branch: 1 branch
BranchTrueFalseTotal
if ($wrong || $warned and $Params::Check::Faster::WARNINGS_FATAL) 1 37 38
Condition100%6/6
$wrong || $warned and $Params::Check::Faster::WARNINGS_FATAL
!ll&&!rl&&r
21161
$wrong or $warned
l!l&&r!l&&!r
14321
MC/DC66%2/3
$wrong || $warned and $Params::Check::Faster::WARNINGS_FATAL
$wrong $warned $Params::Check::Faster::WARNINGS_FATAL
Truth table80%4/5
A or B and C
A= $wrongB= $warnedC= $Params::Check::Faster::WARNINGS_FATAL
ABCresult
00X0
1X00
0100
1X11
0111
434 1 croak(__PACKAGE__->last_error());
435 }
436  
437 # if $wrong is set, somethign went wrong and the user is already informed,
438 # just return...
439 37 ▶ return if $wrong;
Branch: 1 branch
BranchTrueFalseTotal
if $wrong 13 24 37
440  
441 # check if we need to store any of the keys. can't do it before, because
442 # something may go wrong later, leaving the user with a few set variables
443  
444 24 foreach(@to_store) {
445 6 my ($type, $ref, $value) = @$_;
446 6 ▶ if ($type == 0) {
Branch: 3 branches
BranchTrueFalseTotal
if ($type == 0) { } 4 2 6
elsif ($type == 1) { } 1 1 2
elsif ($type == 2) { } 1 0 1
447 4 $$ref = $value;
448 }
449 elsif ($type == 1) {
450 1 @{$ref} = @{$value};
451 }
452 elsif ($type == 2) {
453 1 %{$ref} = %{$value};
454 }
455 }
456 24 ▶ $NO_DUPLICATES and delete @args{@to_delete};
Branch: 1 branch
BranchTrueFalseTotal
$Params::Check::Faster::NO_DUPLICATES and delete @args{@to_delete} 1 23 24
457  
458 # now, everything is fine, we can return the arguments
459 24 return(\%args);
460 }
461  
462 6 ▶sub _store_var {
Subroutine _store_var: called CC=10 SCAR=26.6
463 6 my ($key, $ref, $value, $verbose, $to_store, $to_delete) = @_;
464  
465 6 ▶ if ($SANITY_CHECK_TEMPLATE && !ref($ref)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($Params::Check::Faster::SANITY_CHECK_TEMPLATE and not ref $ref) 0 6 6
Condition33%1/3
$Params::Check::Faster::SANITY_CHECK_TEMPLATE and not ref $ref
!ll&&!rl&&r
060
MC/DC0%0/2
$Params::Check::Faster::SANITY_CHECK_TEMPLATE and not ref $ref
$Params::Check::Faster::SANITY_CHECK_TEMPLATE not ref $ref
Truth table33%1/3
A and not(B)
A= $Params::Check::Faster::SANITY_CHECK_TEMPLATEB= not ref $ref
ABresult
0X0
100
111
466 0 _store_error( loc(
467 q(Store variable for '%1' is not a reference!), $key
468 ), $verbose, 1 );
469 0 return; #error
470 }
471
472 6 ▶ if (ref($ref) eq 'ARRAY') {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $ref eq 'ARRAY') { } 1 5 6
elsif (ref $ref eq 'HASH') { } 1 4 5
473 1 ▶ if (ref($value) ne 'ARRAY') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $value ne "ARRAY") 0 1 1
474 0 _store_error(
475 loc(q(Key '%1' (value %2) is not a ARRAYREF. For %3 by %4),
476 $key, $value, _who_was_it(1), _who_was_it(2)), $verbose, 1);
477 0 return; # error
478 }
479 # push the refs/values to execute later
480 1 push @$to_store, [ 1, $ref, $value]; # 1 = array
481 1 ▶ $NO_DUPLICATES and push @$to_delete, $key;
Branch: 1 branch
BranchTrueFalseTotal
$Params::Check::Faster::NO_DUPLICATES and push @$to_delete, $key 0 1 1
482 }
483 elsif (ref($ref) eq 'HASH') {
484 1 ▶ if (ref($value) ne 'HASH') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $value ne "HASH") 0 1 1
485 0 _store_error(
486 loc(q(Key '%1' (value %2) is not a HASHREF. For %3 by %4),
487 $key, $value, _who_was_it(1), _who_was_it(2)), $verbose, 1);
488 0 return; # error
489 }
490 # push the refs/values to execute later
491 1 push @$to_store, [ 2, $ref, $value]; # 2 = hash
492 1 ▶ $NO_DUPLICATES and push @$to_delete, $key;
Branch: 1 branch
BranchTrueFalseTotal
$Params::Check::Faster::NO_DUPLICATES and push @$to_delete, $key 0 1 1
493 }
494 else {
495 # push the refs/values to execute later
496 4 push @$to_store, [ 0, $ref, $value]; # 0 = scalar ref
497 4 ▶ $NO_DUPLICATES and push(@$to_delete, $key);
Branch: 1 branch
BranchTrueFalseTotal
$Params::Check::Faster::NO_DUPLICATES and push @$to_delete, $key 1 3 4
498 }
499  
500 6 return 1; # success
501 }
502  
503 =head2 allow( $test_me, \@criteria );
504  
505 The function that handles the C<allow> key in the template is also
506 available for independent use.
507  
508 The function takes as first argument a key to test against, and
509 as second argument any form of criteria that are also allowed by
510 the C<allow> key in the template.
511  
512 You can use the following types of values for allow:
513  
514 =over 4
515  
516 =item string
517  
518 The provided argument MUST be equal to the string for the validation
519 to pass.
520  
521 =item regexp
522  
523 The provided argument MUST match the regular expression for the
524 validation to pass.
525  
526 =item subroutine
527  
528 The provided subroutine MUST return true in order for the validation
529 to pass and the argument accepted.
530  
531 (This is particularly useful for more complicated data).
532  
533 =item array ref
534  
535 The provided argument MUST equal one of the elements of the array
536 ref for the validation to pass. An array ref can hold all the above
537 values.
538  
539 =back
540  
541 It returns true if the key matched the criteria, or false otherwise.
542  
543 =cut
544  
545 40 ▶sub allow {
Subroutine allow: called CC=8 SCAR=20.9
Pod documented
546  
547 # it's a regexp
548 40 ▶ if (ref($_[1]) eq 'Regexp') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $_[1] eq "Regexp") 4 36 40
549 1 ▶ no warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
550 4 return(scalar $_[0] =~ /$_[1]/); ## no critic (Regular expression)
551 }
552  
553 # it's a sub
554 36 ▶ if (ref($_[1]) eq 'CODE') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $_[1] eq "CODE") 18 18 36
555 18 return $_[1]->($_[0]);
556 }
557
558 # it's an array
559 18 ▶ if (ref($_[1])eq 'ARRAY') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $_[1] eq "ARRAY") 7 11 18
560  
561 # loop over the elements, see if one of them says the
562 # value is OK
563 # also, short-cicruit when possible
564 7 foreach (@{$_[1]}) {
565 12 ▶ if (allow($_[0], $_)) {
Branch: 1 branch
BranchTrueFalseTotal
if (allow($_[0], $_)) 5 7 12
566 5 return 1;
567 }
568 }
569 2 return;
570 }
571  
572 # fall back to a simple, but safe 'eq'
573 11 ▶ return (defined $_[0] && defined $_[1]
Branch: 1 branch
BranchTrueFalseTotal
defined $_[0] && defined $_[1] ? : 11 0 11
Condition33%1/3
defined $_[0] and defined $_[1]
!ll&&!rl&&r
0011
MC/DC0%0/2
defined $_[0] and defined $_[1]
defined $_[0] defined $_[1]
Truth table33%1/3
A and B
A= defined $_[0]B= defined $_[1]
ABresult
0X0
100
111
574 ? $_[0] eq $_[1]
575 : defined $_[0] eq defined $_[1]
576 );
577 }
578  
579 # helper functions
580  
581 22 ▶sub _who_was_it {
Subroutine _who_was_it: called CC=3 SCAR=11.0
582 22 ▶ my $level = $_[0] || 0;
Condition100%2/2
$_[0] || 0
l!l
1111
MC/DC100%1/1
$_[0] || 0
$_[0]
Truth table100%2/2
A
A= $_[0]
Aresult
11
00
583  
584 22 ▶ return (caller(2 + $CALLER_DEPTH + $level))[3] || 'ANON'
Condition100%2/2
(caller 2 + $Params::Check::Faster::CALLER_DEPTH + $level)[3] || 'ANON'
l!l
517
MC/DC100%1/1
(caller 2 + $Params::Check::Faster::CALLER_DEPTH + $level)[3] || 'ANON'
(caller 2 + $Params::Check::Faster::CALLER_DEPTH + $level)[3]
Truth table100%2/2
A
A= (caller 2 + $Params::Check::Faster::CALLER_DEPTH + $level)[3]
Aresult
11
00
585 }
586  
587 =head2 last_error()
588  
589 Returns a string containing all warnings and errors reported during
590 the last time C<check> was called.
591  
592 This is useful if you want to report then some other way than
593 C<carp>'ing when the verbose flag is on.
594  
595 It is exported upon request.
596  
597 =cut
598  
599 1 { $_ERROR_STRING = '';
600  
601 18 ▶ sub _store_error {
Subroutine _store_error: called CC=4 SCAR=14.3
602 18 my($err, $verbose, $offset) = @_[0..2];
603 18 ▶ $verbose ||= 0;
Condition50%1/2
$verbose ||= 0
l!l
018
MC/DC0%0/1
$verbose ||= 0
$verbose
Truth table50%1/2
A
A= $verbose
Aresult
11
00
604 18 ▶ $offset ||= 0;
Condition50%1/2
$offset ||= 0
l!l
018
MC/DC0%0/1
$offset ||= 0
$offset
Truth table50%1/2
A
A= $offset
Aresult
11
00
605 18 my $level = 1 + $offset;
606  
607 18 local $Carp::CarpLevel = $level;
608  
609 18 ▶ carp $err if $verbose;
Branch: 1 branch
BranchTrueFalseTotal
if $verbose 0 18 18
610  
611 18 $_ERROR_STRING .= $err . "\n";
612 }
613  
614 38 ▶ sub _clear_error {
Subroutine _clear_error: called CC=1 SCAR=0.0
615 38 $_ERROR_STRING = '';
616 }
617  
618 17 ▶ sub last_error { $_ERROR_STRING }
Subroutine last_error: called CC=1 SCAR=0.0
Pod documented
619 }
620  
621 1 1;
622  
623 =head1 Global Variables
624  
625 The behaviour of Params::Check::Faster can be altered by changing the
626 following global variables:
627  
628 =head2 $Params::Check::Faster::VERBOSE
629  
630 This controls whether Params::Check::Faster will issue warnings and
631 explanations as to why certain things may have failed.
632 If you set it to 0, Params::Check::Faster will not output any warnings.
633  
634 The default is 1 when L<warnings> are enabled, 0 otherwise;
635  
636 =head2 $Params::Check::Faster::STRICT_TYPE
637  
638 This works like the C<strict_type> option you can pass to C<check>,
639 which will turn on C<strict_type> globally for all calls to C<check>.
640  
641 The default is 0;
642  
643 =head2 $Params::Check::Faster::ALLOW_UNKNOWN
644  
645 If you set this flag, unknown options will still be present in the
646 return value, rather than filtered out. This is useful if your
647 subroutine is only interested in a few arguments, and wants to pass
648 the rest on blindly to perhaps another subroutine.
649  
650 The default is 0;
651  
652 =head2 $Params::Check::Faster::STRIP_LEADING_DASHES
653  
654 If you set this flag, all keys passed in the following manner:
655  
656 function( -key => 'val' );
657  
658 will have their leading dashes stripped.
659  
660 =head2 $Params::Check::Faster::NO_DUPLICATES
661  
662 If set to true, all keys in the template that are marked as to be
663 stored in a scalar, will also be removed from the result set.
664  
665 Default is false, meaning that when you use C<store> as a template
666 key, C<check> will put it both in the scalar you supplied, as well as
667 in the hashref it returns.
668  
669 =head2 $Params::Check::Faster::PRESERVE_CASE
670  
671 If set to true, L<Params::Check::Faster> will no longer convert all keys from
672 the user input to lowercase, but instead expect them to be in the
673 case the template provided. This is useful when you want to use
674 similar keys with different casing in your templates.
675  
676 Understand that this removes the case-insensitivy feature of this
677 module.
678  
679 Default is 0;
680  
681 =head2 $Params::Check::Faster::ONLY_ALLOW_DEFINED
682  
683 If set to true, L<Params::Check::Faster> will require all values passed to be
684 C<defined>. If you wish to enable this on a 'per key' basis, use the
685 template option C<defined> instead.
686  
687 Default is 0;
688  
689 =head2 $Params::Check::Faster::SANITY_CHECK_TEMPLATE
690  
691 If set to true, L<Params::Check::Faster> will sanity check templates, validating
692 for errors and unknown keys. Although very useful for debugging, this
693 can be somewhat slow in hot-code and large loops.
694  
695 To disable this check, set this variable to C<false>.
696  
697 Default is 1;
698  
699 =head2 $Params::Check::Faster::WARNINGS_FATAL
700  
701 If set to true, L<Params::Check::Faster> will C<croak> when an error during
702 template validation occurs, rather than return C<false>.
703  
704 Default is 0;
705  
706 =head2 $Params::Check::Faster::CALLER_DEPTH
707  
708 This global modifies the argument given to C<caller()> by
709 C<Params::Check::Faster::check()> and is useful if you have a custom wrapper
710 function around C<Params::Check::Faster::check()>. The value must be an
711 integer, indicating the number of wrapper functions inserted between
712 the real function call and C<Params::Check::Faster::check()>.
713  
714 Example wrapper function, using a custom stacktrace:
715  
716 sub check {
717 my ($template, $args_in) = @_;
718  
719 local $Params::Check::Faster::WARNINGS_FATAL = 1;
720 local $Params::Check::Faster::CALLER_DEPTH = $Params::Check::Faster::CALLER_DEPTH + 1;
721 my $args_out = Params::Check::Faster::check($template, $args_in);
722  
723 my_stacktrace(Params::Check::Faster::last_error) unless $args_out;
724  
725 return $args_out;
726 }
727  
728 Default is 0;
729  
730 =head1 AUTHOR
731  
732 This module by
733 Damien "dams" Krotkine E<lt>dams@cpan.orgE<gt>.
734  
735 =head1 COPYRIGHT
736  
737 This module is
738 copyright (c) 2007 Damien "dams" Krotkine E<lt>dams@cpan.orgE<gt>.
739 All rights reserved.
740  
741 This library is free software;
742 you may redistribute and/or modify it under the same
743 terms as Perl itself.
744  
745 =cut
746  
747 # Local variables:
748 # c-indentation-style: bsd
749 # c-basic-offset: 4
750 # indent-tabs-mode: nil
751 # End:
752 # vim: expandtab shiftwidth=4:
↑ Summary