1Params::Check(3)      User Contributed Perl Documentation     Params::Check(3)
2
3
4

NAME

6       Params::Check - A generic input parsing/checking mechanism.
7

SYNOPSIS

9           use Params::Check qw[check allow last_error];
10
11           sub fill_personal_info {
12               my %hash = @_;
13               my $x;
14
15               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
26                   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
35               ### 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
39               ... other code here ...
40           }
41
42           my $ok = allow( $colour, [qw|blue green yellow|] );
43
44           my $error = Params::Check::last_error();
45

DESCRIPTION

47       Params::Check is a generic input parsing/checking mechanism.
48
49       It allows you to validate input via a template. The only requirement is
50       that the arguments must be named.
51
52       Params::Check can do the following things for you:
53
54       ·   Convert all keys to lowercase
55
56       ·   Check if all required arguments have been provided
57
58       ·   Set arguments that have not been provided to the default
59
60       ·   Weed out arguments that are not supported and warn about them to
61           the user
62
63       ·   Validate the arguments given by the user based on strings, regexes,
64           lists or even subroutines
65
66       ·   Enforce type integrity if required
67
68       Most of Params::Check's power comes from its template, which we'll
69       discuss below:
70

Template

72       As you can see in the synopsis, based on your template, the arguments
73       provided will be validated.
74
75       The template can take a different set of rules per key that is used.
76
77       The following rules are available:
78
79       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
84       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
89       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
94           This is very useful if you insist on taking an array reference as
95           argument for example.
96
97       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
104       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
110       store
111           This allows you to pass a reference to a scalar, in which the data
112           will be stored:
113
114               my $x;
115               my $args = check(foo => { default => 1, store => \$x }, $input);
116
117           This is basically shorthand for saying:
118
119               my $args = check( { foo => { default => 1 }, $input );
120               my $x    = $args->{foo};
121
122           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
126       allow
127           A set of criteria used to validate a particular piece of data if it
128           has to adhere to particular rules.
129
130           See the "allow()" function for details.
131

Functions

133   check( \%tmpl, \%args, [$verbose] );
134       This function is not exported by default, so you'll have to ask for it
135       via:
136
137           use Params::Check qw[check];
138
139       or use its fully qualified name instead.
140
141       "check" takes a list of arguments, as follows:
142
143       Template
144           This is a hash reference which contains a template as explained in
145           the "SYNOPSIS" and "Template" section.
146
147       Arguments
148           This is a reference to a hash of named arguments which need
149           checking.
150
151       Verbose
152           A boolean to indicate whether "check" should be verbose and warn
153           about what went wrong in a check or not.
154
155           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
159       "check" will return when it fails, or a hashref with lowercase keys of
160       parsed arguments when it succeeds.
161
162       So a typical call to check would look like this:
163
164           my $parsed = check( \%template, \%arguments, $VERBOSE )
165                           or warn q[Arguments could not be parsed!];
166
167       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
170   allow( $test_me, \@criteria );
171       The function that handles the "allow" key in the template is also
172       available for independent use.
173
174       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
178       You can use the following types of values for allow:
179
180       string
181           The provided argument MUST be equal to the string for the
182           validation to pass.
183
184       regexp
185           The provided argument MUST match the regular expression for the
186           validation to pass.
187
188       subroutine
189           The provided subroutine MUST return true in order for the
190           validation to pass and the argument accepted.
191
192           (This is particularly useful for more complicated data).
193
194       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
199       It returns true if the key matched the criteria, or false otherwise.
200
201   last_error()
202       Returns a string containing all warnings and errors reported during the
203       last time "check" was called.
204
205       This is useful if you want to report then some other way than
206       "carp"'ing when the verbose flag is on.
207
208       It is exported upon request.
209

Global Variables

211       The behaviour of Params::Check can be altered by changing the following
212       global variables:
213
214   $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
219       The default is 1 when warnings are enabled, 0 otherwise;
220
221   $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
225       The default is 0;
226
227   $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
233       The default is 0;
234
235   $Params::Check::STRIP_LEADING_DASHES
236       If you set this flag, all keys passed in the following manner:
237
238           function( -key => 'val' );
239
240       will have their leading dashes stripped.
241
242   $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
246       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
250   $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
256       Understand that this removes the case-insensitivity feature of this
257       module.
258
259       Default is 0;
260
261   $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
266       Default is 0;
267
268   $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
273       To disable this check, set this variable to "false".
274
275       Default is 1;
276
277   $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
281       Default is 0;
282
283   $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
290       Example wrapper function, using a custom stacktrace:
291
292           sub check {
293               my ($template, $args_in) = @_;
294
295               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
299               my_stacktrace(Params::Check::last_error) unless $args_out;
300
301               return $args_out;
302           }
303
304       Default is 0;
305

Acknowledgements

307       Thanks to Richard Soderberg for his performance improvements.
308

BUG REPORTS

310       Please report bugs or other issues to <bug-params-check@rt.cpan.org>.
311

AUTHOR

313       This module by Jos Boumans <kane@cpan.org>.
314
316       This library is free software; you may redistribute and/or modify it
317       under the same terms as Perl itself.
318
319
320
321perl v5.16.3                      2013-06-20                  Params::Check(3)
Impressum