1Params::Check(3pm) Perl Programmers Reference Guide Params::Check(3pm)
2
6 Params::Check - A generic input parsing/checking mechanism.
7
9 use Params::Check qw[check allow last_error];
10 sub fill_personal_info {
12 my %hash = @_;
13 my $x;
14 my $tmpl = {
16 firstname => { required => 1, defined => 1 },
17 lastname => { required => 1, store => \$x },
18 gender => { required => 1,
19 allow => [qr/M/i, qr/F/i],
20 },
21 married => { allow => [0,1] },
22 age => { default => 21,
23 allow => qr/^\d+$/,
24 },
25 phone => { allow => [ sub { return 1 if /$valid_re/ },
27 '1-800-PERL' ]
28 },
29 id_list => { default => [],
30 strict_type => 1
31 },
32 employer => { default => 'NSA', no_override => 1 },
33 };
34 ### check() returns a hashref of parsed args on success ###
36 my $parsed_args = check( $tmpl, \%hash, $VERBOSE )
37 or die qw[Could not parse arguments!];
38 ... other code here ...
40 }
41 my $ok = allow( $colour, [qw|blue green yellow|] );
43 my $error = Params::Check::last_error();
45
47 Params::Check is a generic input parsing/checking mechanism.
48 It allows you to validate input via a template. The only requirement is
50 that the arguments must be named.
51 Params::Check can do the following things for you:
53 · Convert all keys to lowercase
55 · Check if all required arguments have been provided
57 · Set arguments that have not been provided to the default
59 · Weed out arguments that are not supported and warn about them to
61 the user
62 · Validate the arguments given by the user based on strings, regexes,
64 lists or even subroutines
65 · Enforce type integrity if required
67 Most of Params::Check's power comes from its template, which we'll
69 discuss below:
70
72 As you can see in the synopsis, based on your template, the arguments
73 provided will be validated.
74 The template can take a different set of rules per key that is used.
76 The following rules are available:
78 default
80 This is the default value if none was provided by the user. This
81 is also the type "strict_type" will look at when checking type
82 integrity (see below).
83 required
85 A boolean flag that indicates if this argument was a required
86 argument. If marked as required and not provided, check() will
87 fail.
88 strict_type
90 This does a "ref()" check on the argument provided. The "ref" of
91 the argument must be the same as the "ref" of the default value for
92 this check to pass.
93 This is very useful if you insist on taking an array reference as
95 argument for example.
96 defined
98 If this template key is true, enforces that if this key is provided
99 by user input, its value is "defined". This just means that the
100 user is not allowed to pass "undef" as a value for this key and is
101 equivalent to:
102 allow => sub { defined $_[0] && OTHER TESTS }
103 no_override
105 This allows you to specify "constants" in your template. ie, they
106 keys that are not allowed to be altered by the user. It pretty much
107 allows you to keep all your "configurable" data in one place; the
108 "Params::Check" template.
109 store
111 This allows you to pass a reference to a scalar, in which the data
112 will be stored:
113 my $x;
115 my $args = check(foo => { default => 1, store => \$x }, $input);
116 This is basically shorthand for saying:
118 my $args = check( { foo => { default => 1 }, $input );
120 my $x = $args->{foo};
121 You can alter the global variable $Params::Check::NO_DUPLICATES to
123 control whether the "store"'d key will still be present in your
124 result set. See the "Global Variables" section below.
125 allow
127 A set of criteria used to validate a particular piece of data if it
128 has to adhere to particular rules.
129 See the "allow()" function for details.
131
133 check( \%tmpl, \%args, [$verbose] );
134 This function is not exported by default, so you'll have to ask for it
135 via:
136 use Params::Check qw[check];
138 or use its fully qualified name instead.
140 "check" takes a list of arguments, as follows:
142 Template
144 This is a hashreference which contains a template as explained in
145 the "SYNOPSIS" and "Template" section.
146 Arguments
148 This is a reference to a hash of named arguments which need
149 checking.
150 Verbose
152 A boolean to indicate whether "check" should be verbose and warn
153 about what went wrong in a check or not.
154 You can enable this program wide by setting the package variable
156 $Params::Check::VERBOSE to a true value. For details, see the
157 section on "Global Variables" below.
158 "check" will return when it fails, or a hashref with lowercase keys of
160 parsed arguments when it succeeds.
161 So a typical call to check would look like this:
163 my $parsed = check( \%template, \%arguments, $VERBOSE )
165 or warn q[Arguments could not be parsed!];
166 A lot of the behaviour of "check()" can be altered by setting package
168 variables. See the section on "Global Variables" for details on this.
169 allow( $test_me, \@criteria );
171 The function that handles the "allow" key in the template is also
172 available for independent use.
173 The function takes as first argument a key to test against, and as
175 second argument any form of criteria that are also allowed by the
176 "allow" key in the template.
177 You can use the following types of values for allow:
179 string
181 The provided argument MUST be equal to the string for the
182 validation to pass.
183 regexp
185 The provided argument MUST match the regular expression for the
186 validation to pass.
187 subroutine
189 The provided subroutine MUST return true in order for the
190 validation to pass and the argument accepted.
191 (This is particularly useful for more complicated data).
193 array ref
195 The provided argument MUST equal one of the elements of the array
196 ref for the validation to pass. An array ref can hold all the above
197 values.
198 It returns true if the key matched the criteria, or false otherwise.
200 last_error()
202 Returns a string containing all warnings and errors reported during the
203 last time "check" was called.
204 This is useful if you want to report then some other way than
206 "carp"'ing when the verbose flag is on.
207 It is exported upon request.
209
211 The behaviour of Params::Check can be altered by changing the following
212 global variables:
213 $Params::Check::VERBOSE
215 This controls whether Params::Check will issue warnings and
216 explanations as to why certain things may have failed. If you set it
217 to 0, Params::Check will not output any warnings.
218 The default is 1 when warnings are enabled, 0 otherwise;
220 $Params::Check::STRICT_TYPE
222 This works like the "strict_type" option you can pass to "check", which
223 will turn on "strict_type" globally for all calls to "check".
224 The default is 0;
226 $Params::Check::ALLOW_UNKNOWN
228 If you set this flag, unknown options will still be present in the
229 return value, rather than filtered out. This is useful if your
230 subroutine is only interested in a few arguments, and wants to pass the
231 rest on blindly to perhaps another subroutine.
232 The default is 0;
234 $Params::Check::STRIP_LEADING_DASHES
236 If you set this flag, all keys passed in the following manner:
237 function( -key => 'val' );
239 will have their leading dashes stripped.
241 $Params::Check::NO_DUPLICATES
243 If set to true, all keys in the template that are marked as to be
244 stored in a scalar, will also be removed from the result set.
245 Default is false, meaning that when you use "store" as a template key,
247 "check" will put it both in the scalar you supplied, as well as in the
248 hashref it returns.
249 $Params::Check::PRESERVE_CASE
251 If set to true, Params::Check will no longer convert all keys from the
252 user input to lowercase, but instead expect them to be in the case the
253 template provided. This is useful when you want to use similar keys
254 with different casing in your templates.
255 Understand that this removes the case-insensitivy feature of this
257 module.
258 Default is 0;
260 $Params::Check::ONLY_ALLOW_DEFINED
262 If set to true, Params::Check will require all values passed to be
263 "defined". If you wish to enable this on a 'per key' basis, use the
264 template option "defined" instead.
265 Default is 0;
267 $Params::Check::SANITY_CHECK_TEMPLATE
269 If set to true, Params::Check will sanity check templates, validating
270 for errors and unknown keys. Although very useful for debugging, this
271 can be somewhat slow in hot-code and large loops.
272 To disable this check, set this variable to "false".
274 Default is 1;
276 $Params::Check::WARNINGS_FATAL
278 If set to true, Params::Check will "croak" when an error during
279 template validation occurs, rather than return "false".
280 Default is 0;
282 $Params::Check::CALLER_DEPTH
284 This global modifies the argument given to "caller()" by
285 "Params::Check::check()" and is useful if you have a custom wrapper
286 function around "Params::Check::check()". The value must be an integer,
287 indicating the number of wrapper functions inserted between the real
288 function call and "Params::Check::check()".
289 Example wrapper function, using a custom stacktrace:
291 sub check {
293 my ($template, $args_in) = @_;
294 local $Params::Check::WARNINGS_FATAL = 1;
296 local $Params::Check::CALLER_DEPTH = $Params::Check::CALLER_DEPTH + 1;
297 my $args_out = Params::Check::check($template, $args_in);
298 my_stacktrace(Params::Check::last_error) unless $args_out;
300 return $args_out;
302 }
303 Default is 0;
305
307 This module by Jos Boumans <kane@cpan.org>.
308
310 Thanks to Richard Soderberg for his performance improvements.
311
313 This module is copyright (c) 2003,2004 Jos Boumans <kane@cpan.org>.
314 All rights reserved.
315 This library is free software; you may redistribute and/or modify it
317 under the same terms as Perl itself.
318perl v5.12.4 2011-06-07 Params::Check(3pm)