Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Params::Check.3pm

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