local-lib5/man/man3/Params::Check.3pm

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