File Coverage

blib/lib/Params/Check/Faster.pm
Criterion Covered Total %
statement 154 167 92.2
branch 66 82 80.4
condition 34 51 66.6
subroutine 15 15 100.0
pod 3 3 100.0
total 272 318 85.5


line stmt bran cond sub pod time code
1             package Params::Check::Faster;
2              
3 1     1   56718 use 5.006; #warnings.pm
  1         3  
4 1     1   6 use strict;
  1         2  
  1         33  
5              
6 1     1   5 use Carp qw[carp croak];
  1         6  
  1         73  
7 1     1   884 use Locale::Maketext::Simple Style => 'gettext';
  1         1498  
  1         6  
8              
9             BEGIN {
10 1     1   421 use Exporter ();
  1         2  
  1         29  
11 1         203 use vars qw[ @ISA $VERSION @EXPORT_OK $VERBOSE $ALLOW_UNKNOWN
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     1   4 ];
  1         1  
16              
17 1     1   10 @ISA = qw[ Exporter ];
18 1         3 @EXPORT_OK = qw[check allow last_error];
19              
20 1         2 $VERSION = '0.04';
21 1 50       5 $VERBOSE = $^W ? 1 : 0;
22 1         2 $NO_DUPLICATES = 0;
23 1         1 $STRIP_LEADING_DASHES = 0;
24 1         2 $STRICT_TYPE = 0;
25 1         1 $ALLOW_UNKNOWN = 0;
26 1         2 $PRESERVE_CASE = 0;
27 1         2 $ONLY_ALLOW_DEFINED = 0;
28 1         1 $SANITY_CHECK_TEMPLATE = 1;
29 1         2 $WARNINGS_FATAL = 0;
30 1         1334 $CALLER_DEPTH = 0;
31             }
32              
33             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 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 check on the argument provided. The C of the
153             argument must be the same as the C 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. This just means that the user is
163             not allowed to pass C 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 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 data in one place; the
172             C 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'd key will still be present in your
200             result set. See the L 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 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 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 and C