Debian Codegraph @

upstream/debian-unstable/man3/Params::Check.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Params::Check 3perl"
58 .TH Params::Check 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Params::Check \- A generic input parsing/checking mechanism.
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use Params::Check qw[check allow last_error];
69 \&
70 \& sub fill_personal_info {
71 \& my %hash = @_;
72 \& my $x;
73 \&
74 \& my $tmpl = {
75 \& firstname => { required => 1, defined => 1 },
76 \& lastname => { required => 1, store => \e$x },
77 \& gender => { required => 1,
78 \& allow => [qr/M/i, qr/F/i],
79 \& },
80 \& married => { allow => [0,1] },
81 \& age => { default => 21,
82 \& allow => qr/^\ed+$/,
83 \& },
84 \&
85 \& phone => { allow => [ sub { return 1 if /$valid_re/ },
86 \& \*(Aq1\-800\-PERL\*(Aq ]
87 \& },
88 \& id_list => { default => [],
89 \& strict_type => 1
90 \& },
91 \& employer => { default => \*(AqNSA\*(Aq, no_override => 1 },
92 \& };
93 \&
94 \& ### check() returns a hashref of parsed args on success ###
95 \& my $parsed_args = check( $tmpl, \e%hash, $VERBOSE )
96 \& or die qw[Could not parse arguments!];
97 \&
98 \& ... other code here ...
99 \& }
100 \&
101 \& my $ok = allow( $colour, [qw|blue green yellow|] );
102 \&
103 \& my $error = Params::Check::last_error();
104 .Ve
105 .SH DESCRIPTION
106 .IX Header "DESCRIPTION"
107 Params::Check is a generic input parsing/checking mechanism.
108 .PP
109 It allows you to validate input via a template. The only requirement
110 is that the arguments must be named.
111 .PP
112 Params::Check can do the following things for you:
113 .IP \(bu 4
114 Convert all keys to lowercase
115 .IP \(bu 4
116 Check if all required arguments have been provided
117 .IP \(bu 4
118 Set arguments that have not been provided to the default
119 .IP \(bu 4
120 Weed out arguments that are not supported and warn about them to the
121 user
122 .IP \(bu 4
123 Validate the arguments given by the user based on strings, regexes,
124 lists or even subroutines
125 .IP \(bu 4
126 Enforce type integrity if required
127 .PP
128 Most of Params::Check's power comes from its template, which we'll
129 discuss below:
130 .SH Template
131 .IX Header "Template"
132 As you can see in the synopsis, based on your template, the arguments
133 provided will be validated.
134 .PP
135 The template can take a different set of rules per key that is used.
136 .PP
137 The following rules are available:
138 .IP default 4
139 .IX Item "default"
140 This is the default value if none was provided by the user.
141 This is also the type \f(CW\*(C`strict_type\*(C'\fR will look at when checking type
142 integrity (see below).
143 .IP required 4
144 .IX Item "required"
145 A boolean flag that indicates if this argument was a required
146 argument. If marked as required and not provided, \fBcheck()\fR will fail.
147 .IP strict_type 4
148 .IX Item "strict_type"
149 This does a \f(CWref()\fR check on the argument provided. The \f(CW\*(C`ref\*(C'\fR of the
150 argument must be the same as the \f(CW\*(C`ref\*(C'\fR of the default value for this
151 check to pass.
152 .Sp
153 This is very useful if you insist on taking an array reference as
154 argument for example.
155 .IP defined 4
156 .IX Item "defined"
157 If this template key is true, enforces that if this key is provided by
158 user input, its value is \f(CW\*(C`defined\*(C'\fR. This just means that the user is
159 not allowed to pass \f(CW\*(C`undef\*(C'\fR as a value for this key and is equivalent
160 to:
161 allow => sub { defined \f(CW$_\fR[0] && OTHER TESTS }
162 .IP no_override 4
163 .IX Item "no_override"
164 This allows you to specify \f(CW\*(C`constants\*(C'\fR in your template. ie, they
165 keys that are not allowed to be altered by the user. It pretty much
166 allows you to keep all your \f(CW\*(C`configurable\*(C'\fR data in one place; the
167 \&\f(CW\*(C`Params::Check\*(C'\fR template.
168 .IP store 4
169 .IX Item "store"
170 This allows you to pass a reference to a scalar, in which the data
171 will be stored:
172 .Sp
173 .Vb 2
174 \& my $x;
175 \& my $args = check(foo => { default => 1, store => \e$x }, $input);
176 .Ve
177 .Sp
178 This is basically shorthand for saying:
179 .Sp
180 .Vb 2
181 \& my $args = check( { foo => { default => 1 }, $input );
182 \& my $x = $args\->{foo};
183 .Ve
184 .Sp
185 You can alter the global variable \f(CW$Params::Check::NO_DUPLICATES\fR to
186 control whether the \f(CW\*(C`store\*(C'\fR'd key will still be present in your
187 result set. See the "Global Variables" section below.
188 .IP allow 4
189 .IX Item "allow"
190 A set of criteria used to validate a particular piece of data if it
191 has to adhere to particular rules.
192 .Sp
193 See the \f(CWallow()\fR function for details.
194 .SH Functions
195 .IX Header "Functions"
196 .SS "check( \e%tmpl, \e%args, [$verbose] );"
197 .IX Subsection "check( %tmpl, %args, [$verbose] );"
198 This function is not exported by default, so you'll have to ask for it
199 via:
200 .PP
201 .Vb 1
202 \& use Params::Check qw[check];
203 .Ve
204 .PP
205 or use its fully qualified name instead.
206 .PP
207 \&\f(CW\*(C`check\*(C'\fR takes a list of arguments, as follows:
208 .IP Template 4
209 .IX Item "Template"
210 This is a hash reference which contains a template as explained in the
211 \&\f(CW\*(C`SYNOPSIS\*(C'\fR and \f(CW\*(C`Template\*(C'\fR section.
212 .IP Arguments 4
213 .IX Item "Arguments"
214 This is a reference to a hash of named arguments which need checking.
215 .IP Verbose 4
216 .IX Item "Verbose"
217 A boolean to indicate whether \f(CW\*(C`check\*(C'\fR should be verbose and warn
218 about what went wrong in a check or not.
219 .Sp
220 You can enable this program wide by setting the package variable
221 \&\f(CW$Params::Check::VERBOSE\fR to a true value. For details, see the
222 section on \f(CW\*(C`Global Variables\*(C'\fR below.
223 .PP
224 \&\f(CW\*(C`check\*(C'\fR will return when it fails, or a hashref with lowercase
225 keys of parsed arguments when it succeeds.
226 .PP
227 So a typical call to check would look like this:
228 .PP
229 .Vb 2
230 \& my $parsed = check( \e%template, \e%arguments, $VERBOSE )
231 \& or warn q[Arguments could not be parsed!];
232 .Ve
233 .PP
234 A lot of the behaviour of \f(CWcheck()\fR can be altered by setting
235 package variables. See the section on \f(CW\*(C`Global Variables\*(C'\fR for details
236 on this.
237 .ie n .SS "allow( $test_me, \e@criteria );"
238 .el .SS "allow( \f(CW$test_me\fP, \e@criteria );"
239 .IX Subsection "allow( $test_me, @criteria );"
240 The function that handles the \f(CW\*(C`allow\*(C'\fR key in the template is also
241 available for independent use.
242 .PP
243 The function takes as first argument a key to test against, and
244 as second argument any form of criteria that are also allowed by
245 the \f(CW\*(C`allow\*(C'\fR key in the template.
246 .PP
247 You can use the following types of values for allow:
248 .IP string 4
249 .IX Item "string"
250 The provided argument MUST be equal to the string for the validation
251 to pass.
252 .IP regexp 4
253 .IX Item "regexp"
254 The provided argument MUST match the regular expression for the
255 validation to pass.
256 .IP subroutine 4
257 .IX Item "subroutine"
258 The provided subroutine MUST return true in order for the validation
259 to pass and the argument accepted.
260 .Sp
261 (This is particularly useful for more complicated data).
262 .IP "array ref" 4
263 .IX Item "array ref"
264 The provided argument MUST equal one of the elements of the array
265 ref for the validation to pass. An array ref can hold all the above
266 values.
267 .PP
268 It returns true if the key matched the criteria, or false otherwise.
269 .SS \fBlast_error()\fP
270 .IX Subsection "last_error()"
271 Returns a string containing all warnings and errors reported during
272 the last time \f(CW\*(C`check\*(C'\fR was called.
273 .PP
274 This is useful if you want to report then some other way than
275 \&\f(CW\*(C`carp\*(C'\fR'ing when the verbose flag is on.
276 .PP
277 It is exported upon request.
278 .SH "Global Variables"
279 .IX Header "Global Variables"
280 The behaviour of Params::Check can be altered by changing the
281 following global variables:
282 .ie n .SS $Params::Check::VERBOSE
283 .el .SS \f(CW$Params::Check::VERBOSE\fP
284 .IX Subsection "$Params::Check::VERBOSE"
285 This controls whether Params::Check will issue warnings and
286 explanations as to why certain things may have failed.
287 If you set it to 0, Params::Check will not output any warnings.
288 .PP
289 The default is 1 when warnings are enabled, 0 otherwise;
290 .ie n .SS $Params::Check::STRICT_TYPE
291 .el .SS \f(CW$Params::Check::STRICT_TYPE\fP
292 .IX Subsection "$Params::Check::STRICT_TYPE"
293 This works like the \f(CW\*(C`strict_type\*(C'\fR option you can pass to \f(CW\*(C`check\*(C'\fR,
294 which will turn on \f(CW\*(C`strict_type\*(C'\fR globally for all calls to \f(CW\*(C`check\*(C'\fR.
295 .PP
296 The default is 0;
297 .ie n .SS $Params::Check::ALLOW_UNKNOWN
298 .el .SS \f(CW$Params::Check::ALLOW_UNKNOWN\fP
299 .IX Subsection "$Params::Check::ALLOW_UNKNOWN"
300 If you set this flag, unknown options will still be present in the
301 return value, rather than filtered out. This is useful if your
302 subroutine is only interested in a few arguments, and wants to pass
303 the rest on blindly to perhaps another subroutine.
304 .PP
305 The default is 0;
306 .ie n .SS $Params::Check::STRIP_LEADING_DASHES
307 .el .SS \f(CW$Params::Check::STRIP_LEADING_DASHES\fP
308 .IX Subsection "$Params::Check::STRIP_LEADING_DASHES"
309 If you set this flag, all keys passed in the following manner:
310 .PP
311 .Vb 1
312 \& function( \-key => \*(Aqval\*(Aq );
313 .Ve
314 .PP
315 will have their leading dashes stripped.
316 .ie n .SS $Params::Check::NO_DUPLICATES
317 .el .SS \f(CW$Params::Check::NO_DUPLICATES\fP
318 .IX Subsection "$Params::Check::NO_DUPLICATES"
319 If set to true, all keys in the template that are marked as to be
320 stored in a scalar, will also be removed from the result set.
321 .PP
322 Default is false, meaning that when you use \f(CW\*(C`store\*(C'\fR as a template
323 key, \f(CW\*(C`check\*(C'\fR will put it both in the scalar you supplied, as well as
324 in the hashref it returns.
325 .ie n .SS $Params::Check::PRESERVE_CASE
326 .el .SS \f(CW$Params::Check::PRESERVE_CASE\fP
327 .IX Subsection "$Params::Check::PRESERVE_CASE"
328 If set to true, Params::Check will no longer convert all keys from
329 the user input to lowercase, but instead expect them to be in the
330 case the template provided. This is useful when you want to use
331 similar keys with different casing in your templates.
332 .PP
333 Understand that this removes the case-insensitivity feature of this
334 module.
335 .PP
336 Default is 0;
337 .ie n .SS $Params::Check::ONLY_ALLOW_DEFINED
338 .el .SS \f(CW$Params::Check::ONLY_ALLOW_DEFINED\fP
339 .IX Subsection "$Params::Check::ONLY_ALLOW_DEFINED"
340 If set to true, Params::Check will require all values passed to be
341 \&\f(CW\*(C`defined\*(C'\fR. If you wish to enable this on a 'per key' basis, use the
342 template option \f(CW\*(C`defined\*(C'\fR instead.
343 .PP
344 Default is 0;
345 .ie n .SS $Params::Check::SANITY_CHECK_TEMPLATE
346 .el .SS \f(CW$Params::Check::SANITY_CHECK_TEMPLATE\fP
347 .IX Subsection "$Params::Check::SANITY_CHECK_TEMPLATE"
348 If set to true, Params::Check will sanity check templates, validating
349 for errors and unknown keys. Although very useful for debugging, this
350 can be somewhat slow in hot-code and large loops.
351 .PP
352 To disable this check, set this variable to \f(CW\*(C`false\*(C'\fR.
353 .PP
354 Default is 1;
355 .ie n .SS $Params::Check::WARNINGS_FATAL
356 .el .SS \f(CW$Params::Check::WARNINGS_FATAL\fP
357 .IX Subsection "$Params::Check::WARNINGS_FATAL"
358 If set to true, Params::Check will \f(CW\*(C`croak\*(C'\fR when an error during
359 template validation occurs, rather than return \f(CW\*(C`false\*(C'\fR.
360 .PP
361 Default is 0;
362 .ie n .SS $Params::Check::CALLER_DEPTH
363 .el .SS \f(CW$Params::Check::CALLER_DEPTH\fP
364 .IX Subsection "$Params::Check::CALLER_DEPTH"
365 This global modifies the argument given to \f(CWcaller()\fR by
366 \&\f(CWParams::Check::check()\fR and is useful if you have a custom wrapper
367 function around \f(CWParams::Check::check()\fR. The value must be an
368 integer, indicating the number of wrapper functions inserted between
369 the real function call and \f(CWParams::Check::check()\fR.
370 .PP
371 Example wrapper function, using a custom stacktrace:
372 .PP
373 .Vb 2
374 \& sub check {
375 \& my ($template, $args_in) = @_;
376 \&
377 \& local $Params::Check::WARNINGS_FATAL = 1;
378 \& local $Params::Check::CALLER_DEPTH = $Params::Check::CALLER_DEPTH + 1;
379 \& my $args_out = Params::Check::check($template, $args_in);
380 \&
381 \& my_stacktrace(Params::Check::last_error) unless $args_out;
382 \&
383 \& return $args_out;
384 \& }
385 .Ve
386 .PP
387 Default is 0;
388 .SH Acknowledgements
389 .IX Header "Acknowledgements"
390 Thanks to Richard Soderberg for his performance improvements.
391 .SH "BUG REPORTS"
392 .IX Header "BUG REPORTS"
393 Please report bugs or other issues to <bug\-params\[email protected]>.
394 .SH AUTHOR
395 .IX Header "AUTHOR"
396 This module by Jos Boumans <[email protected]>.
397 .SH COPYRIGHT
398 .IX Header "COPYRIGHT"
399 This library is free software; you may redistribute and/or modify it
400 under the same terms as Perl itself.