local-lib5/man/man3/MooseX::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 "MooseX::Params::Validate 3"
 132 .TH MooseX::Params::Validate 3 "2009-11-29" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 MooseX::Params::Validate \- an extension of Params::Validate for using Moose's types
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 3
 138 \&  package Foo;
 139 \&  use Moose;
 140 \&  use MooseX::Params::Validate;
 141 .Ve
 142 .PP
 143 .Vb 7
 144 \&  sub foo {
 145 \&      my ( $self, %params ) = validated_hash(
 146 \&          \e@_,
 147 \&          bar => { isa => 'Str', default => 'Moose' },
 148 \&      );
 149 \&      return "Horray for $params{bar}!";
 150 \&  }
 151 .Ve
 152 .PP
 153 .Vb 10
 154 \&  sub bar {
 155 \&      my $self = shift;
 156 \&      my ( $foo, $baz, $gorch ) = validated_list(
 157 \&          \e@_,
 158 \&          foo   => { isa => 'Foo' },
 159 \&          baz   => { isa => 'ArrayRef | HashRef', optional => 1 },
 160 \&          gorch => { isa => 'ArrayRef[Int]', optional => 1 }
 161 \&      );
 162 \&      [ $foo, $baz, $gorch ];
 163 \&  }
 164 .Ve
 165 .SH "DESCRIPTION"
 166 .IX Header "DESCRIPTION"
 167 This module fills a gap in Moose by adding method parameter validation
 168 to Moose. This is just one of many developing options, it should not
 169 be considered the \*(L"official\*(R" one by any means though.
 170 .PP
 171 You might also want to explore \f(CW\*(C`MooseX::Method::Signatures\*(C'\fR and
 172 \&\f(CW\*(C`MooseX::Declare\*(C'\fR
 173 .SH "CAVEATS"
 174 .IX Header "CAVEATS"
 175 It is not possible to introspect the method parameter specs, they are
 176 created as needed when the method is called and cached for subsequent
 177 calls.
 178 .SH "EXPORTS"
 179 .IX Header "EXPORTS"
 180 .ie n .IP "\fBvalidated_hash( \e@_, \fB%parameter_spec\fB )\fR" 4
 181 .el .IP "\fBvalidated_hash( \e@_, \f(CB%parameter_spec\fB )\fR" 4
 182 .IX Item "validated_hash( @_, %parameter_spec )"
 183 This behaves similar to the standard Params::Validate \f(CW\*(C`validate\*(C'\fR
 184 function and returns the captured values in a \s-1HASH\s0. The one exception
 185 being that if it spots an instance in the \f(CW@_\fR, then it will handle
 186 it appropriately (unlike Params::Validate which forces you to shift
 187 you \f(CW$self\fR first).
 188 .Sp
 189 The \f(CW%parameter_spec\fR accepts the following options:
 190 .RS 4
 191 .IP "\fIisa\fR" 4
 192 .IX Item "isa"
 193 The \f(CW\*(C`isa\*(C'\fR option can be either; class name, Moose type constraint
 194 name or an anon Moose type constraint.
 195 .IP "\fIdoes\fR" 4
 196 .IX Item "does"
 197 The \f(CW\*(C`does\*(C'\fR option can be either; role name or an anon Moose type
 198 constraint.
 199 .IP "\fIdefault\fR" 4
 200 .IX Item "default"
 201 This is the default value to be used if the value is not supplied.
 202 .IP "\fIoptional\fR" 4
 203 .IX Item "optional"
 204 As with Params::Validate, all options are considered required unless
 205 otherwise specified. This option is passed directly to
 206 Params::Validate.
 207 .IP "\fIcoerce\fR" 4
 208 .IX Item "coerce"
 209 If this is true and the parameter has a type constraint which has
 210 coercions, then the coercion will be called for this parameter. If the
 211 type does have coercions, then this parameter is ignored.
 212 .RE
 213 .RS 4
 214 .Sp
 215 This function is also available under its old name, \f(CW\*(C`validate\*(C'\fR.
 216 .RE
 217 .ie n .IP "\fBvalidated_list( \e@_, \fB%parameter_spec\fB )\fR" 4
 218 .el .IP "\fBvalidated_list( \e@_, \f(CB%parameter_spec\fB )\fR" 4
 219 .IX Item "validated_list( @_, %parameter_spec )"
 220 The \f(CW%parameter_spec\fR accepts the same options as above, but returns
 221 the parameters as positional values instead of a \s-1HASH\s0. This is best
 222 explained by example:
 223 .Sp
 224 .Vb 8
 225 \&  sub foo {
 226 \&      my ( $self, $foo, $bar ) = validated_list(
 227 \&          \e@_,
 228 \&          foo => { isa => 'Foo' },
 229 \&          bar => { isa => 'Bar' },
 230 \&      );
 231 \&      $foo\->baz($bar);
 232 \&  }
 233 .Ve
 234 .Sp
 235 We capture the order in which you defined the parameters and then
 236 return them as a list in the same order. If a param is marked optional
 237 and not included, then it will be set to \f(CW\*(C`undef\*(C'\fR.
 238 .Sp
 239 Like \f(CW\*(C`validated_hash\*(C'\fR, if it spots an object instance as the first
 240 parameter of \f(CW@_\fR, it will handle it appropriately, returning it as
 241 the first argument.
 242 .Sp
 243 This function is also available under its old name, \f(CW\*(C`validatep\*(C'\fR.
 244 .ie n .IP "\fBpos_validated_list( \e@_, \fB$spec\fB, \f(BI$spec\fB, ... )\fR" 4
 245 .el .IP "\fBpos_validated_list( \e@_, \f(CB$spec\fB, \f(CB$spec\fB, ... )\fR" 4
 246 .IX Item "pos_validated_list( @_, $spec, $spec, ... )"
 247 This function validates a list of positional parameters. Each \f(CW$spec\fR
 248 should validate one of the parameters in the list:
 249 .Sp
 250 .Vb 7
 251 \&  sub foo {
 252 \&      my $self = shift;
 253 \&      my ( $foo, $bar ) = pos_validated_list(
 254 \&          \e@_,
 255 \&          { isa => 'Foo' },
 256 \&          { isa => 'Bar' },
 257 \&      );
 258 .Ve
 259 .Sp
 260 .Vb 2
 261 \&      ...
 262 \&  }
 263 .Ve
 264 .Sp
 265 Unlike the other functions, this function \fIcannot\fR find \f(CW$self\fR in
 266 the argument list. Make sure to shift it off yourself before doing
 267 validation.
 268 .Sp
 269 If a parameter is marked as optional and is not present, it will
 270 simply not be returned.
 271 .Sp
 272 If you want to pass in any of the cache control parameters described
 273 below, simply pass them after the list of parameter validation specs:
 274 .Sp
 275 .Vb 8
 276 \&  sub foo {
 277 \&      my $self = shift;
 278 \&      my ( $foo, $bar ) = pos_validated_list(
 279 \&          \e@_,
 280 \&          { isa => 'Foo' },
 281 \&          { isa => 'Bar' },
 282 \&          MX_PARAMS_VALIDATE_NO_CACHE => 1,
 283 \&      );
 284 .Ve
 285 .Sp
 286 .Vb 2
 287 \&      ...
 288 \&  }
 289 .Ve
 290 .SH "EXPORTS"
 291 .IX Header "EXPORTS"
 292 By default, this module exports the \f(CW\*(C`validated_hash\*(C'\fR,
 293 \&\f(CW\*(C`validated_list\*(C'\fR, and \f(CW\*(C`pos_validated_list\*(C'\fR.
 294 .PP
 295 If you would prefer to import the now deprecated functions \f(CW\*(C`validate\*(C'\fR
 296 and \f(CW\*(C`validatep\*(C'\fR instead, you can use the \f(CW\*(C`:deprecated\*(C'\fR tag to import
 297 them.
 298 .SH "IMPORTANT NOTE ON CACHING"
 299 .IX Header "IMPORTANT NOTE ON CACHING"
 300 When \f(CW\*(C`validate\*(C'\fR or \f(CW\*(C`validatep\*(C'\fR are called the first time, the
 301 parameter spec is prepared and cached to avoid unnecessary
 302 regeneration. It uses the fully qualified name of the subroutine
 303 (package + subname) as the cache key.  In 99.999% of the use cases for
 304 this module, that will be the right thing to do.
 305 .PP
 306 However, I have (ab)used this module occasionally to handle dynamic
 307 sets of parameters. In this special use case you can do a couple
 308 things to better control the caching behavior.
 309 .IP "\(bu" 4
 310 Passing in the \f(CW\*(C`MX_PARAMS_VALIDATE_NO_CACHE\*(C'\fR flag in the parameter
 311 spec this will prevent the parameter spec from being cached.
 312 .Sp
 313 .Vb 6
 314 \&  sub foo {
 315 \&      my ( $self, %params ) = validated_hash(
 316 \&          \e@_,
 317 \&          foo                         => { isa => 'Foo' },
 318 \&          MX_PARAMS_VALIDATE_NO_CACHE => 1,
 319 \&      );
 320 .Ve
 321 .Sp
 322 .Vb 1
 323 \&  }
 324 .Ve
 325 .IP "\(bu" 4
 326 Passing in \f(CW\*(C`MX_PARAMS_VALIDATE_CACHE_KEY\*(C'\fR with a value to be used as
 327 the cache key will bypass the normal cache key generation.
 328 .Sp
 329 .Vb 6
 330 \&  sub foo {
 331 \&      my ( $self, %params ) = validated_hash(
 332 \&          \e@_,
 333 \&          foo                          => { isa => 'Foo' },
 334 \&          MX_PARAMS_VALIDATE_CACHE_KEY => 'foo\-42',
 335 \&      );
 336 .Ve
 337 .Sp
 338 .Vb 1
 339 \&  }
 340 .Ve
 341 .SH "BUGS"
 342 .IX Header "BUGS"
 343 All complex software has bugs lurking in it, and this module is no
 344 exception. If you find a bug please either email me, or add the bug to
 345 cpan\-RT.
 346 .SH "AUTHORS"
 347 .IX Header "AUTHORS"
 348 Stevan Little <stevan.little@iinteractive.com>
 349 .PP
 350 Dave Rolsky <autarch@urth.org>
 351 .SH "COPYRIGHT AND LICENSE"
 352 .IX Header "COPYRIGHT AND LICENSE"
 353 Copyright 2007\-2009 by Infinity Interactive, Inc.
 354 .PP
 355 <http://www.iinteractive.com>
 356 .PP
 357 This library is free software; you can redistribute it and/or modify
 358 it under the same terms as Perl itself.