1Params::Check(3) User Contributed Perl Documentation Params::Check(3)
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 dis‐
69 cuss 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 argu‐
86 ment. If marked as required and not provided, check() will fail.
87 strict_type
89 This does a "ref()" check on the argument provided. The "ref" of
90 the argument must be the same as the "ref" of the default value for
91 this check to pass.
92 This is very useful if you insist on taking an array reference as
94 argument for example.
95 defined
97 If this template key is true, enforces that if this key is provided
98 by user input, its value is "defined". This just means that the
99 user is not allowed to pass "undef" as a value for this key and is
100 equivalent to:
101 allow => sub { defined $_[0] && OTHER TESTS }
102 no_override
104 This allows you to specify "constants" in your template. ie, they
105 keys that are not allowed to be altered by the user. It pretty much
106 allows you to keep all your "configurable" data in one place; the
107 "Params::Check" template.
108 store
110 This allows you to pass a reference to a scalar, in which the data
111 will be stored:
112 my $x;
114 my $args = check(foo => { default => 1, store => \$x }, $input);
115 This is basically shorthand for saying:
117 my $args = check( { foo => { default => 1 }, $input );
119 my $x = $args->{foo};
120 You can alter the global variable $Params::Check::NO_DUPLICATES to
122 control whether the "store"'d key will still be present in your
123 result set. See the "Global Variables" section below.
124 allow
126 A set of criteria used to validate a particular piece of data if it
127 has to adhere to particular rules.
128 See the "allow()" function for details.
130
132 check( \%tmpl, \%args, [$verbose] );
133 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 check‐
149 ing.
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 sec‐
157 tion 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
173 available for independent use.
174 The function takes as first argument a key to test against, and as sec‐
176 ond argument any form of criteria that are also allowed by the "allow"
177 key in the template.
178 You can use the following types of values for allow:
180 string
182 The provided argument MUST be equal to the string for the valida‐
183 tion to pass.
184 regexp
186 The provided argument MUST match the regular expression for the
187 validation to pass.
188 subroutine
190 The provided subroutine MUST return true in order for the valida‐
191 tion to pass and the argument accepted.
192 (This is particularly useful for more complicated data).
194 array ref
196 The provided argument MUST equal one of the elements of the array
197 ref for the validation to pass. An array ref can hold all the above
198 values.
199 It returns true if the key matched the criteria, or false otherwise.
201 last_error()
203 Returns a string containing all warnings and errors reported during the
205 last time "check" was called.
206 This is useful if you want to report then some other way than
208 "carp"'ing when the verbose flag is on.
209 It is exported upon request.
211
213 The behaviour of Params::Check can be altered by changing the following
214 global variables:
215 $Params::Check::VERBOSE
217 This controls whether Params::Check will issue warnings and explana‐
219 tions as to why certain things may have failed. If you set it to 0,
220 Params::Check will not output any warnings.
221 The default is 1 when warnings are enabled, 0 otherwise;
223 $Params::Check::STRICT_TYPE
225 This works like the "strict_type" option you can pass to "check", which
227 will turn on "strict_type" globally for all calls to "check".
228 The default is 0;
230 $Params::Check::ALLOW_UNKNOWN
232 If you set this flag, unknown options will still be present in the
234 return value, rather than filtered out. This is useful if your subrou‐
235 tine is only interested in a few arguments, and wants to pass the rest
236 on blindly to perhaps another subroutine.
237 The default is 0;
239 $Params::Check::STRIP_LEADING_DASHES
241 If you set this flag, all keys passed in the following manner:
243 function( -key => 'val' );
245 will have their leading dashes stripped.
247 $Params::Check::NO_DUPLICATES
249 If set to true, all keys in the template that are marked as to be
251 stored in a scalar, will also be removed from the result set.
252 Default is false, meaning that when you use "store" as a template key,
254 "check" will put it both in the scalar you supplied, as well as in the
255 hashref it returns.
256 $Params::Check::PRESERVE_CASE
258 If set to true, Params::Check will no longer convert all keys from the
260 user input to lowercase, but instead expect them to be in the case the
261 template provided. This is useful when you want to use similar keys
262 with different casing in your templates.
263 Understand that this removes the case-insensitivy feature of this mod‐
265 ule.
266 Default is 0;
268 $Params::Check::ONLY_ALLOW_DEFINED
270 If set to true, Params::Check will require all values passed to be
272 "defined". If you wish to enable this on a 'per key' basis, use the
273 template option "defined" instead.
274 Default is 0;
276 $Params::Check::SANITY_CHECK_TEMPLATE
278 If set to true, Params::Check will sanity check templates, validating
280 for errors and unknown keys. Although very useful for debugging, this
281 can be somewhat slow in hot-code and large loops.
282 To disable this check, set this variable to "false".
284 Default is 1;
286 $Params::Check::WARNINGS_FATAL
288 If set to true, Params::Check will "croak" when an error during tem‐
290 plate validation occurs, rather than return "false".
291 Default is 0;
293 $Params::Check::CALLER_DEPTH
295 This global modifies the argument given to "caller()" by
297 "Params::Check::check()" and is useful if you have a custom wrapper
298 function around "Params::Check::check()". The value must be an integer,
299 indicating the number of wrapper functions inserted between the real
300 function call and "Params::Check::check()".
301 Example wrapper function, using a custom stacktrace:
303 sub check {
305 my ($template, $args_in) = @_;
306 local $Params::Check::WARNINGS_FATAL = 1;
308 local $Params::Check::CALLER_DEPTH = $Params::Check::CALLER_DEPTH + 1;
309 my $args_out = Params::Check::check($template, $args_in);
310 my_stacktrace(Params::Check::last_error) unless $args_out;
312 return $args_out;
314 }
315 Default is 0;
317
319 This module by Jos Boumans <kane@cpan.org>.
320
322 Thanks to Richard Soderberg for his performance improvements.
323
325 This module is copyright (c) 2003,2004 Jos Boumans <kane@cpan.org>.
326 All rights reserved.
327 This library is free software; you may redistribute and/or modify it
329 under the same terms as Perl itself.
330perl v5.8.8 2007-03-01 Params::Check(3)