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

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Params::Validate 3"
 132 .TH Params::Validate 3 "2009-12-09" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Params::Validate \- Validate method/function parameters
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&  use Params::Validate qw(:all);
 139 .Ve
 140 .PP
 141 .Vb 8
 142 \&  # takes named params (hash or hashref)
 143 \&  sub foo
 144 \&  {
 145 \&      validate( @_, { foo => 1, # mandatory
 146 \&                      bar => 0, # optional
 147 \&                    }
 148 \&              );
 149 \&  }
 150 .Ve
 151 .PP
 152 .Vb 6
 153 \&  # takes positional params
 154 \&  sub bar
 155 \&  {
 156 \&      # first two are mandatory, third is optional
 157 \&      validate_pos( @_, 1, 1, 0 );
 158 \&  }
 159 .Ve
 160 .PP
 161 .Vb 6
 162 \&  sub foo2
 163 \&  {
 164 \&      validate( @_,
 165 \&                { foo =>
 166 \&                  # specify a type
 167 \&                  { type => ARRAYREF },
 168 .Ve
 169 .PP
 170 .Vb 3
 171 \&                  bar =>
 172 \&                  # specify an interface
 173 \&                  { can => [ 'print', 'flush', 'frobnicate' ] },
 174 .Ve
 175 .PP
 176 .Vb 12
 177 \&                  baz =>
 178 \&                  { type => SCALAR,   # a scalar ...
 179 \&                    # ... that is a plain integer ...
 180 \&                    regex => qr/^\ed+$/,
 181 \&                    callbacks =>
 182 \&                    { # ... and smaller than 90
 183 \&                      'less than 90' => sub { shift() < 90 },
 184 \&                    },
 185 \&                  }
 186 \&                }
 187 \&              );
 188 \&  }
 189 .Ve
 190 .PP
 191 .Vb 7
 192 \&  sub with_defaults
 193 \&  {
 194 \&       my %p = validate( @_, { foo => 1, # required
 195 \&                               # $p{bar} will be 99 if bar is not
 196 \&                               # given.  bar is now optional.
 197 \&                               bar => { default => 99 } } );
 198 \&  }
 199 .Ve
 200 .PP
 201 .Vb 4
 202 \&  sub pos_with_defaults
 203 \&  {
 204 \&       my @p = validate_pos( @_, 1, { default => 99 } );
 205 \&  }
 206 .Ve
 207 .PP
 208 .Vb 8
 209 \&  sub sets_options_on_call
 210 \&  {
 211 \&       my %p = validate_with
 212 \&                   ( params => \e@_,
 213 \&                     spec   => { foo => { type SCALAR, default => 2 } },
 214 \&                     normalize_keys => sub { $_[0] =~ s/^\-//; lc $_[0] },
 215 \&                   );
 216 \&  }
 217 .Ve
 218 .SH "DESCRIPTION"
 219 .IX Header "DESCRIPTION"
 220 The Params::Validate module allows you to validate method or function
 221 call parameters to an arbitrary level of specificity.  At the simplest
 222 level, it is capable of validating the required parameters were given
 223 and that no unspecified additional parameters were passed in.
 224 .PP
 225 It is also capable of determining that a parameter is of a specific
 226 type, that it is an object of a certain class hierarchy, that it
 227 possesses certain methods, or applying validation callbacks to
 228 arguments.
 229 .Sh "\s-1EXPORT\s0"
 230 .IX Subsection "EXPORT"
 231 The module always exports the \f(CW\*(C`validate()\*(C'\fR and \f(CW\*(C`validate_pos()\*(C'\fR
 232 functions.
 233 .PP
 234 It also has an additional function available for export,
 235 \&\f(CW\*(C`validate_with\*(C'\fR, which can be used to validate any type of
 236 parameters, and set various options on a per-invocation basis.
 237 .PP
 238 In addition, it can export the following constants, which are used as
 239 part of the type checking.  These are \f(CW\*(C`SCALAR\*(C'\fR, \f(CW\*(C`ARRAYREF\*(C'\fR,
 240 \&\f(CW\*(C`HASHREF\*(C'\fR, \f(CW\*(C`CODEREF\*(C'\fR, \f(CW\*(C`GLOB\*(C'\fR, \f(CW\*(C`GLOBREF\*(C'\fR, and \f(CW\*(C`SCALARREF\*(C'\fR,
 241 \&\f(CW\*(C`UNDEF\*(C'\fR, \f(CW\*(C`OBJECT\*(C'\fR, \f(CW\*(C`BOOLEAN\*(C'\fR, and \f(CW\*(C`HANDLE\*(C'\fR.  These are explained
 242 in the section on Type Validation.
 243 .PP
 244 The constants are available via the export tag \f(CW\*(C`:types\*(C'\fR.  There is
 245 also an \f(CW\*(C`:all\*(C'\fR tag which includes all of the constants as well as the
 246 \&\f(CW\*(C`validation_options()\*(C'\fR function.
 247 .SH "PARAMETER VALIDATION"
 248 .IX Header "PARAMETER VALIDATION"
 249 The validation mechanisms provided by this module can handle both
 250 named or positional parameters.  For the most part, the same features
 251 are available for each.  The biggest difference is the way that the
 252 validation specification is given to the relevant subroutine.  The
 253 other difference is in the error messages produced when validation
 254 checks fail.
 255 .PP
 256 When handling named parameters, the module will accept either a hash
 257 or a hash reference.
 258 .PP
 259 Subroutines expecting named parameters should call the \f(CW\*(C`validate()\*(C'\fR
 260 subroutine like this:
 261 .PP
 262 .Vb 4
 263 \& validate( @_, { parameter1 => validation spec,
 264 \&                 parameter2 => validation spec,
 265 \&                 ...
 266 \&               } );
 267 .Ve
 268 .PP
 269 Subroutines expecting positional parameters should call the
 270 \&\f(CW\*(C`validate_pos()\*(C'\fR subroutine like this:
 271 .PP
 272 .Vb 1
 273 \& validate_pos( @_, { validation spec }, { validation spec } );
 274 .Ve
 275 .Sh "Mandatory/Optional Parameters"
 276 .IX Subsection "Mandatory/Optional Parameters"
 277 If you just want to specify that some parameters are mandatory and
 278 others are optional, this can be done very simply.
 279 .PP
 280 For a subroutine expecting named parameters, you would do this:
 281 .PP
 282 .Vb 1
 283 \& validate( @_, { foo => 1, bar => 1, baz => 0 } );
 284 .Ve
 285 .PP
 286 This says that the \*(L"foo\*(R" and \*(L"bar\*(R" parameters are mandatory and that
 287 the \*(L"baz\*(R" parameter is optional.  The presence of any other
 288 parameters will cause an error.
 289 .PP
 290 For a subroutine expecting positional parameters, you would do this:
 291 .PP
 292 .Vb 1
 293 \& validate_pos( @_, 1, 1, 0, 0 );
 294 .Ve
 295 .PP
 296 This says that you expect at least 2 and no more than 4 parameters.
 297 If you have a subroutine that has a minimum number of parameters but
 298 can take any maximum number, you can do this:
 299 .PP
 300 .Vb 1
 301 \& validate_pos( @_, 1, 1, (0) x (@_ \- 2) );
 302 .Ve
 303 .PP
 304 This will always be valid as long as at least two parameters are
 305 given.  A similar construct could be used for the more complex
 306 validation parameters described further on.
 307 .PP
 308 Please note that this:
 309 .PP
 310 .Vb 1
 311 \& validate_pos( @_, 1, 1, 0, 1, 1 );
 312 .Ve
 313 .PP
 314 makes absolutely no sense, so don't do it.  Any zeros must come at the
 315 end of the validation specification.
 316 .PP
 317 In addition, if you specify that a parameter can have a default, then
 318 it is considered optional.
 319 .Sh "Type Validation"
 320 .IX Subsection "Type Validation"
 321 This module supports the following simple types, which can be
 322 exported as constants:
 323 .IP "* \s-1SCALAR\s0" 4
 324 .IX Item "SCALAR"
 325 A scalar which is not a reference, such as \f(CW10\fR or \f(CW'hello'\fR.  A
 326 parameter that is undefined is \fBnot\fR treated as a scalar.  If you
 327 want to allow undefined values, you will have to specify \f(CW\*(C`SCALAR |
 328 UNDEF\*(C'\fR.
 329 .IP "* \s-1ARRAYREF\s0" 4
 330 .IX Item "ARRAYREF"
 331 An array reference such as \f(CW\*(C`[1, 2, 3]\*(C'\fR or \f(CW\*(C`\e@foo\*(C'\fR.
 332 .IP "* \s-1HASHREF\s0" 4
 333 .IX Item "HASHREF"
 334 A hash reference such as \f(CW\*(C`{ a => 1, b => 2 }\*(C'\fR or \f(CW\*(C`\e%bar\*(C'\fR.
 335 .IP "* \s-1CODEREF\s0" 4
 336 .IX Item "CODEREF"
 337 A subroutine reference such as \f(CW\*(C`\e&foo_sub\*(C'\fR or \f(CW\*(C`sub { print "hello" }\*(C'\fR.
 338 .IP "* \s-1GLOB\s0" 4
 339 .IX Item "GLOB"
 340 This one is a bit tricky.  A glob would be something like \f(CW*FOO\fR, but
 341 not \f(CW\*(C`\e*FOO\*(C'\fR, which is a glob reference.  It should be noted that this
 342 trick:
 343 .Sp
 344 .Vb 1
 345 \& my $fh = do { local *FH; };
 346 .Ve
 347 .Sp
 348 makes \f(CW$fh\fR a glob, not a glob reference.  On the other hand, the
 349 return value from \f(CW\*(C`Symbol::gensym\*(C'\fR is a glob reference.  Either can
 350 be used as a file or directory handle.
 351 .IP "* \s-1GLOBREF\s0" 4
 352 .IX Item "GLOBREF"
 353 A glob reference such as \f(CW\*(C`\e*FOO\*(C'\fR.  See the \s-1GLOB\s0 entry above
 354 for more details.
 355 .IP "* \s-1SCALARREF\s0" 4
 356 .IX Item "SCALARREF"
 357 A reference to a scalar such as \f(CW\*(C`\e$x\*(C'\fR.
 358 .IP "* \s-1UNDEF\s0" 4
 359 .IX Item "UNDEF"
 360 An undefined value
 361 .IP "* \s-1OBJECT\s0" 4
 362 .IX Item "OBJECT"
 363 A blessed reference.
 364 .IP "* \s-1BOOLEAN\s0" 4
 365 .IX Item "BOOLEAN"
 366 This is a special option, and is just a shortcut for \f(CW\*(C`UNDEF | SCALAR\*(C'\fR.
 367 .IP "* \s-1HANDLE\s0" 4
 368 .IX Item "HANDLE"
 369 This option is also special, and is just a shortcut for \f(CW\*(C`GLOB |
 370 GLOBREF\*(C'\fR.  However, it seems likely that most people interested in
 371 either globs or glob references are likely to really be interested in
 372 whether the parameter in question could be a valid file or directory
 373 handle.
 374 .PP
 375 To specify that a parameter must be of a given type when using named
 376 parameters, do this:
 377 .PP
 378 .Vb 2
 379 \& validate( @_, { foo => { type => SCALAR },
 380 \&                 bar => { type => HASHREF } } );
 381 .Ve
 382 .PP
 383 If a parameter can be of more than one type, just use the bitwise or
 384 (\f(CW\*(C`|\*(C'\fR) operator to combine them.
 385 .PP
 386 .Vb 1
 387 \& validate( @_, { foo => { type => GLOB | GLOBREF } );
 388 .Ve
 389 .PP
 390 For positional parameters, this can be specified as follows:
 391 .PP
 392 .Vb 1
 393 \& validate_pos( @_, { type => SCALAR | ARRAYREF }, { type => CODEREF } );
 394 .Ve
 395 .Sh "Interface Validation"
 396 .IX Subsection "Interface Validation"
 397 To specify that a parameter is expected to have a certain set of
 398 methods, we can do the following:
 399 .PP
 400 .Vb 4
 401 \& validate( @_,
 402 \&           { foo =>
 403 \&             # just has to be able to \->bar
 404 \&             { can => 'bar' } } );
 405 .Ve
 406 .PP
 407 .Vb 1
 408 \& ... or ...
 409 .Ve
 410 .PP
 411 .Vb 4
 412 \& validate( @_,
 413 \&           { foo =>
 414 \&             # must be able to \->bar and \->print
 415 \&             { can => [ qw( bar print ) ] } } );
 416 .Ve
 417 .Sh "Class Validation"
 418 .IX Subsection "Class Validation"
 419 A word of warning.  When constructing your external interfaces, it is
 420 probably better to specify what methods you expect an object to
 421 have rather than what class it should be of (or a child of).  This
 422 will make your \s-1API\s0 much more flexible.
 423 .PP
 424 With that said, if you want to validate that an incoming parameter
 425 belongs to a class (or child class) or classes, do:
 426 .PP
 427 .Vb 3
 428 \& validate( @_,
 429 \&           { foo =>
 430 \&             { isa => 'My::Frobnicator' } } );
 431 .Ve
 432 .PP
 433 .Vb 1
 434 \& ... or ...
 435 .Ve
 436 .PP
 437 .Vb 4
 438 \& validate( @_,
 439 \&           { foo =>
 440 \&             { isa => [ qw( My::Frobnicator IO::Handle ) ] } } );
 441 \& # must be both, not either!
 442 .Ve
 443 .Sh "Regex Validation"
 444 .IX Subsection "Regex Validation"
 445 If you want to specify that a given parameter must match a specific
 446 regular expression, this can be done with \*(L"regex\*(R" spec key.  For
 447 example:
 448 .PP
 449 .Vb 3
 450 \& validate( @_,
 451 \&           { foo =>
 452 \&             { regex => qr/^\ed+$/ } } );
 453 .Ve
 454 .PP
 455 The value of the \*(L"regex\*(R" key may be either a string or a pre-compiled
 456 regex created via \f(CW\*(C`qr\*(C'\fR.
 457 .PP
 458 If the value being checked against a regex is undefined, the regex is
 459 explicitly checked against the empty string ('') instead, in order to
 460 avoid \*(L"Use of uninitialized value\*(R" warnings.
 461 .PP
 462 The \f(CW\*(C`Regexp::Common\*(C'\fR module on \s-1CPAN\s0 is an excellent source of regular
 463 expressions suitable for validating input.
 464 .Sh "Callback Validation"
 465 .IX Subsection "Callback Validation"
 466 If none of the above are enough, it is possible to pass in one or more
 467 callbacks to validate the parameter.  The callback will be given the
 468 \&\fBvalue\fR of the parameter as its first argument.  Its second argument
 469 will be all the parameters, as a reference to either a hash or array.
 470 Callbacks are specified as hash reference.  The key is an id for the
 471 callback (used in error messages) and the value is a subroutine
 472 reference, such as:
 473 .PP
 474 .Vb 6
 475 \& validate( @_,
 476 \&           { foo =>
 477 \&             { callbacks =>
 478 \&               { 'smaller than a breadbox' => sub { shift() < $breadbox },
 479 \&                 'green or blue' =>
 480 \&                  sub { $_[0] eq 'green' || $_[0] eq 'blue' } } } );
 481 .Ve
 482 .PP
 483 .Vb 4
 484 \& validate( @_,
 485 \&           { foo =>
 486 \&             { callbacks =>
 487 \&               { 'bigger than baz' => sub { $_[0] > $_[1]\->{baz} } } } } );
 488 .Ve
 489 .Sh "Untainting"
 490 .IX Subsection "Untainting"
 491 If you want values untainted, set the \*(L"untaint\*(R" key in a spec hashref
 492 to a true value, like this:
 493 .PP
 494 .Vb 5
 495 \& my %p =
 496 \&   validate( @_, { foo =>
 497 \&                   { type => SCALAR, untaint => 1 },
 498 \&                   bar =>
 499 \&                   { type => ARRAYREF } } );
 500 .Ve
 501 .PP
 502 This will untaint the \*(L"foo\*(R" parameter if the parameters are valid.
 503 .PP
 504 Note that untainting is only done if \fIall parameters\fR are valid.
 505 Also, only the return values are untainted, not the original values
 506 passed into the validation function.
 507 .PP
 508 Asking for untainting of a reference value will not do anything, as
 509 \&\f(CW\*(C`Params::Validate\*(C'\fR will only attempt to untaint the reference itself.
 510 .Sh "Mandatory/Optional Revisited"
 511 .IX Subsection "Mandatory/Optional Revisited"
 512 If you want to specify something such as type or interface, plus the
 513 fact that a parameter can be optional, do this:
 514 .PP
 515 .Vb 4
 516 \& validate( @_, { foo =>
 517 \&                 { type => SCALAR },
 518 \&                 bar =>
 519 \&                 { type => ARRAYREF, optional => 1 } } );
 520 .Ve
 521 .PP
 522 or this for positional parameters:
 523 .PP
 524 .Vb 1
 525 \& validate_pos( @_, { type => SCALAR }, { type => ARRAYREF, optional => 1 } );
 526 .Ve
 527 .PP
 528 By default, parameters are assumed to be mandatory unless specified as
 529 optional.
 530 .Sh "Dependencies"
 531 .IX Subsection "Dependencies"
 532 It also possible to specify that a given optional parameter depends on
 533 the presence of one or more other optional parameters.
 534 .PP
 535 .Vb 9
 536 \& validate( @_, { cc_number =>
 537 \&                 { type => SCALAR, optional => 1,
 538 \&                   depends => [ 'cc_expiration', 'cc_holder_name' ],
 539 \&                 },
 540 \&                 cc_expiration
 541 \&                 { type => SCALAR, optional => 1 },
 542 \&                 cc_holder_name
 543 \&                 { type => SCALAR, optional => 1 },
 544 \&               } );
 545 .Ve
 546 .PP
 547 In this case, \*(L"cc_number\*(R", \*(L"cc_expiration\*(R", and \*(L"cc_holder_name\*(R" are
 548 all optional.  However, if \*(L"cc_number\*(R" is provided, then
 549 \&\*(L"cc_expiration\*(R" and \*(L"cc_holder_name\*(R" must be provided as well.
 550 .PP
 551 This allows you to group together sets of parameters that all must be
 552 provided together.
 553 .PP
 554 The \f(CW\*(C`validate_pos()\*(C'\fR version of dependencies is slightly different,
 555 in that you can only depend on one other parameter.  Also, if for
 556 example, the second parameter 2 depends on the fourth parameter, then
 557 it implies a dependency on the third parameter as well.  This is
 558 because if the fourth parameter is required, then the user must also
 559 provide a third parameter so that there can be four parameters in
 560 total.
 561 .PP
 562 \&\f(CW\*(C`Params::Validate\*(C'\fR will die if you try to depend on a parameter not
 563 declared as part of your parameter specification.
 564 .Sh "Specifying defaults"
 565 .IX Subsection "Specifying defaults"
 566 If the \f(CW\*(C`validate()\*(C'\fR or \f(CW\*(C`validate_pos()\*(C'\fR functions are called in a
 567 list context, they will return an array or hash containing the
 568 original parameters plus defaults as indicated by the validation spec.
 569 .PP
 570 If the function is not called in a list context, providing a default
 571 in the validation spec still indicates that the parameter is optional.
 572 .PP
 573 The hash or array returned from the function will always be a copy of
 574 the original parameters, in order to leave \f(CW@_\fR untouched for the
 575 calling function.
 576 .PP
 577 Simple examples of defaults would be:
 578 .PP
 579 .Vb 1
 580 \& my %p = validate( @_, { foo => 1, bar => { default => 99 } } );
 581 .Ve
 582 .PP
 583 .Vb 1
 584 \& my @p = validate( @_, 1, { default => 99 } );
 585 .Ve
 586 .PP
 587 In scalar context, a hash reference or array reference will be
 588 returned, as appropriate.
 589 .SH "USAGE NOTES"
 590 .IX Header "USAGE NOTES"
 591 .Sh "Validation failure"
 592 .IX Subsection "Validation failure"
 593 By default, when validation fails \f(CW\*(C`Params::Validate\*(C'\fR calls
 594 \&\f(CW\*(C`Carp::confess()\*(C'\fR.  This can be overridden by setting the \f(CW\*(C`on_fail\*(C'\fR
 595 option, which is described in the \*(L"\s-1GLOBAL\s0\*(R" \s-1OPTIONS\s0
 596 section.
 597 .Sh "Method calls"
 598 .IX Subsection "Method calls"
 599 When using this module to validate the parameters passed to a method
 600 call, you will probably want to remove the class/object from the
 601 parameter list \fBbefore\fR calling \f(CW\*(C`validate()\*(C'\fR or \f(CW\*(C`validate_pos()\*(C'\fR.
 602 If your method expects named parameters, then this is necessary for
 603 the \f(CW\*(C`validate()\*(C'\fR function to actually work, otherwise \f(CW@_\fR will not
 604 be useable as a hash, because it will first have your object (or
 605 class) \fBfollowed\fR by a set of keys and values.
 606 .PP
 607 Thus the idiomatic usage of \f(CW\*(C`validate()\*(C'\fR in a method call will look
 608 something like this:
 609 .PP
 610 .Vb 3
 611 \& sub method
 612 \& {
 613 \&     my $self = shift;
 614 .Ve
 615 .PP
 616 .Vb 2
 617 \&     my %params = validate( @_, { foo => 1, bar => { type => ARRAYREF } } );
 618 \& }
 619 .Ve
 620 .ie n .SH """GLOBAL"" OPTIONS"
 621 .el .SH "``GLOBAL'' OPTIONS"
 622 .IX Header "GLOBAL OPTIONS"
 623 Because the \s-1API\s0 for the \f(CW\*(C`validate()\*(C'\fR and \f(CW\*(C`validate_pos()\*(C'\fR functions
 624 does not make it possible to specify any options other than the the
 625 validation spec, it is possible to set some options as
 626 pseudo\-'globals'.  These allow you to specify such things as whether
 627 or not the validation of named parameters should be case sensitive,
 628 for one example.
 629 .PP
 630 These options are called pseudo\-'globals' because these settings are
 631 \&\fBonly applied to calls originating from the package that set the
 632 options\fR.
 633 .PP
 634 In other words, if I am in package \f(CW\*(C`Foo\*(C'\fR and I call
 635 \&\f(CW\*(C`validation_options()\*(C'\fR, those options are only in effect when I call
 636 \&\f(CW\*(C`validate()\*(C'\fR from package \f(CW\*(C`Foo\*(C'\fR.
 637 .PP
 638 While this is quite different from how most other modules operate, I
 639 feel that this is necessary in able to make it possible for one
 640 module/application to use Params::Validate while still using other
 641 modules that also use Params::Validate, perhaps with different
 642 options set.
 643 .PP
 644 The downside to this is that if you are writing an app with a standard
 645 calling style for all functions, and your app has ten modules, \fBeach
 646 module must include a call to \f(CB\*(C`validation_options()\*(C'\fB\fR. You could of
 647 course write a module that all your modules use which uses various
 648 trickery to do this when imported.
 649 .Sh "Options"
 650 .IX Subsection "Options"
 651 .ie n .IP "* normalize_keys => $callback" 4
 652 .el .IP "* normalize_keys => \f(CW$callback\fR" 4
 653 .IX Item "normalize_keys => $callback"
 654 This option is only relevant when dealing with named parameters.
 655 .Sp
 656 This callback will be used to transform the hash keys of both the
 657 parameters and the parameter spec when \f(CW\*(C`validate()\*(C'\fR or
 658 \&\f(CW\*(C`validate_with()\*(C'\fR are called.
 659 .Sp
 660 Any alterations made by this callback will be reflected in the
 661 parameter hash that is returned by the validation function.  For
 662 example:
 663 .Sp
 664 .Vb 7
 665 \&  sub foo {
 666 \&      return
 667 \&        validate_with( params => \e@_,
 668 \&                       spec   => { foo => { type => SCALAR } },
 669 \&                       normalize_keys =>
 670 \&                       sub { my $k = shift; $k =~ s/^\-//; return uc $k },
 671 \&                     );
 672 .Ve
 673 .Sp
 674 .Vb 1
 675 \&  }
 676 .Ve
 677 .Sp
 678 .Vb 1
 679 \&  %p = foo( foo => 20 );
 680 .Ve
 681 .Sp
 682 .Vb 1
 683 \&  # $p{FOO} is now 20
 684 .Ve
 685 .Sp
 686 .Vb 1
 687 \&  %p = foo( \-fOo => 50 );
 688 .Ve
 689 .Sp
 690 .Vb 1
 691 \&  # $p{FOO} is now 50
 692 .Ve
 693 .Sp
 694 The callback must return a defined value.
 695 .Sp
 696 If a callback is given than the deprecated \*(L"ignore_case\*(R" and
 697 \&\*(L"strip_leading\*(R" options are ignored.
 698 .ie n .IP "* allow_extra => $boolean" 4
 699 .el .IP "* allow_extra => \f(CW$boolean\fR" 4
 700 .IX Item "allow_extra => $boolean"
 701 If true, then the validation routine will allow extra parameters not
 702 named in the validation specification.  In the case of positional
 703 parameters, this allows an unlimited number of maximum parameters
 704 (though a minimum may still be set).  Defaults to false.
 705 .ie n .IP "* on_fail => $callback" 4
 706 .el .IP "* on_fail => \f(CW$callback\fR" 4
 707 .IX Item "on_fail => $callback"
 708 If given, this callback will be called whenever a validation check
 709 fails.  It will be called with a single parameter, which will be a
 710 string describing the failure.  This is useful if you wish to have
 711 this module throw exceptions as objects rather than as strings, for
 712 example.
 713 .Sp
 714 This callback is expected to \f(CW\*(C`die()\*(C'\fR internally.  If it does not, the
 715 validation will proceed onwards, with unpredictable results.
 716 .Sp
 717 The default is to simply use the Carp module's \f(CW\*(C`confess()\*(C'\fR function.
 718 .ie n .IP "* stack_skip => $number" 4
 719 .el .IP "* stack_skip => \f(CW$number\fR" 4
 720 .IX Item "stack_skip => $number"
 721 This tells Params::Validate how many stack frames to skip when finding
 722 a subroutine name to use in error messages.  By default, it looks one
 723 frame back, at the immediate caller to \f(CW\*(C`validate()\*(C'\fR or
 724 \&\f(CW\*(C`validate_pos()\*(C'\fR.  If this option is set, then the given number of
 725 frames are skipped instead.
 726 .ie n .IP "* ignore_case => $boolean" 4
 727 .el .IP "* ignore_case => \f(CW$boolean\fR" 4
 728 .IX Item "ignore_case => $boolean"
 729 \&\s-1DEPRECATED\s0
 730 .Sp
 731 This is only relevant when dealing with named parameters.  If it is
 732 true, then the validation code will ignore the case of parameter
 733 names.  Defaults to false.
 734 .ie n .IP "* strip_leading => $characters" 4
 735 .el .IP "* strip_leading => \f(CW$characters\fR" 4
 736 .IX Item "strip_leading => $characters"
 737 \&\s-1DEPRECATED\s0
 738 .Sp
 739 This too is only relevant when dealing with named parameters.  If this
 740 is given then any parameters starting with these characters will be
 741 considered equivalent to parameters without them entirely.  For
 742 example, if this is specified as '\-', then \f(CW\*(C`\-foo\*(C'\fR and \f(CW\*(C`foo\*(C'\fR would be
 743 considered identical.
 744 .SH "PER-INVOCATION OPTIONS"
 745 .IX Header "PER-INVOCATION OPTIONS"
 746 The \f(CW\*(C`validate_with()\*(C'\fR function can be used to set the options listed
 747 above on a per-invocation basis.  For example:
 748 .PP
 749 .Vb 7
 750 \&  my %p =
 751 \&      validate_with
 752 \&          ( params => \e@_,
 753 \&            spec   => { foo => { type => SCALAR },
 754 \&                        bar => { default => 10 } },
 755 \&            allow_extra => 1,
 756 \&          );
 757 .Ve
 758 .PP
 759 In addition to the options listed above, it is also possible to set
 760 the option \*(L"called\*(R", which should be a string.  This string will be
 761 used in any error messages caused by a failure to meet the validation
 762 spec.
 763 .PP
 764 This subroutine will validate named parameters as a hash if the \*(L"spec\*(R"
 765 parameter is a hash reference.  If it is an array reference, the
 766 parameters are assumed to be positional.
 767 .PP
 768 .Vb 8
 769 \&  my %p =
 770 \&      validate_with
 771 \&          ( params => \e@_,
 772 \&            spec   => { foo => { type => SCALAR },
 773 \&                        bar => { default => 10 } },
 774 \&            allow_extra => 1,
 775 \&            called => 'The Quux::Baz class constructor',
 776 \&          );
 777 .Ve
 778 .PP
 779 .Vb 8
 780 \&  my @p =
 781 \&      validate_with
 782 \&          ( params => \e@_,
 783 \&            spec   => [ { type => SCALAR },
 784 \&                        { default => 10 } ],
 785 \&            allow_extra => 1,
 786 \&            called => 'The Quux::Baz class constructor',
 787 \&          );
 788 .Ve
 789 .SH "DISABLING VALIDATION"
 790 .IX Header "DISABLING VALIDATION"
 791 If the environment variable \f(CW\*(C`PERL_NO_VALIDATION\*(C'\fR is set to something
 792 true, then validation is turned off.  This may be useful if you only
 793 want to use this module during development but don't want the speed
 794 hit during production.
 795 .PP
 796 The only error that will be caught will be when an odd number of
 797 parameters are passed into a function/method that expects a hash.
 798 .PP
 799 If you want to selectively turn validation on and off at runtime, you
 800 can directly set the \f(CW$Params::Validate::NO_VALIDATION\fR global
 801 variable.  It is \fBstrongly\fR recommended that you \fBlocalize\fR any
 802 changes to this variable, because other modules you are using may
 803 expect validation to be on when they execute.  For example:
 804 .PP
 805 .Vb 5
 806 \&  {
 807 \&      local $Params::Validate::NO_VALIDATION = 1;
 808 \&      # no error
 809 \&      foo( bar => 2 );
 810 \&  }
 811 .Ve
 812 .PP
 813 .Vb 2
 814 \&  # error
 815 \&  foo( bar => 2 );
 816 .Ve
 817 .PP
 818 .Vb 5
 819 \&  sub foo
 820 \&  {
 821 \&      my %p = validate( @_, { foo => 1 } );
 822 \&      ...
 823 \&  }
 824 .Ve
 825 .PP
 826 But if you want to shoot yourself in the foot and just turn it off, go
 827 ahead!
 828 .SH "LIMITATIONS"
 829 .IX Header "LIMITATIONS"
 830 Right now there is no way (short of a callback) to specify that
 831 something must be of one of a list of classes, or that it must possess
 832 one of a list of methods.  If this is desired, it can be added in the
 833 future.
 834 .PP
 835 Ideally, there would be only one validation function.  If someone
 836 figures out how to do this, please let me know.
 837 .SH "SUPPORT"
 838 .IX Header "SUPPORT"
 839 Please submit bugs and patches to the \s-1CPAN\s0 \s-1RT\s0 system at
 840 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Params%3A%3AValidate or
 841 via email at bug\-params\-validate@rt.cpan.org.
 842 .PP
 843 Support questions can be sent to Dave at autarch@urth.org.
 844 .PP
 845 The code repository is at https://svn.urth.org/svn/Params\-Validate/
 846 .SH "DONATIONS"
 847 .IX Header "DONATIONS"
 848 If you'd like to thank me for the work I've done on this module,
 849 please consider making a \*(L"donation\*(R" to me via PayPal. I spend a lot of
 850 free time creating free software, and would appreciate any support
 851 you'd care to offer.
 852 .PP
 853 Please note that \fBI am not suggesting that you must do this\fR in order
 854 for me to continue working on this particular software. I will
 855 continue to do so, inasmuch as I have in the past, for as long as it
 856 interests me.
 857 .PP
 858 Similarly, a donation made in this way will probably not make me work
 859 on this software much more, unless I get so many donations that I can
 860 consider working on free software full time, which seems unlikely at
 861 best.
 862 .PP
 863 To donate, log into PayPal and send money to autarch@urth.org or use
 864 the button on this page:
 865 <http://www.urth.org/~autarch/fs\-donation.html>
 866 .SH "AUTHORS"
 867 .IX Header "AUTHORS"
 868 Dave Rolsky, <autarch@urth.org> and Ilya Martynov <ilya@martynov.org>
 869 .SH "COPYRIGHT"
 870 .IX Header "COPYRIGHT"
 871 Copyright (c) 2004\-2007 David Rolsky.  All rights reserved.  This
 872 program is free software; you can redistribute it and/or modify it
 873 under the same terms as Perl itself.