local-lib5/man/man3/Mouse::Util::TypeConstraints.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 "Mouse::Util::TypeConstraints 3"
 127 .TH Mouse::Util::TypeConstraints 3 "2009-12-07" "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 Mouse::Util::TypeConstraints \- Type constraint system for Mouse
 134 .SH "VERSION"
 135 .IX Header "VERSION"
 136 This document describes Mouse version 0.43
 137 .SS "\s-1SYNOPSIS\s0"
 138 .IX Subsection "SYNOPSIS"
 139 .Vb 1
 140 \&  use Mouse::Util::TypeConstraints;
 141 \&
 142 \&  subtype \*(AqNatural\*(Aq
 143 \&      => as \*(AqInt\*(Aq
 144 \&      => where { $_ > 0 };
 145 \&
 146 \&  subtype \*(AqNaturalLessThanTen\*(Aq
 147 \&      => as \*(AqNatural\*(Aq
 148 \&      => where { $_ < 10 }
 149 \&      => message { "This number ($_) is not less than ten!" };
 150 \&
 151 \&  coerce \*(AqNum\*(Aq
 152 \&      => from \*(AqStr\*(Aq
 153 \&        => via { 0+$_ };
 154 \&
 155 \&  enum \*(AqRGBColors\*(Aq => qw(red green blue);
 156 \&
 157 \&  no Mouse::Util::TypeConstraints;
 158 .Ve
 159 .SH "DESCRIPTION"
 160 .IX Header "DESCRIPTION"
 161 This module provides Mouse with the ability to create custom type
 162 constraints to be used in attribute definition.
 163 .SS "Important Caveat"
 164 .IX Subsection "Important Caveat"
 165 This is \fB\s-1NOT\s0\fR a type system for Perl 5. These are type constraints,
 166 and they are not used by Mouse unless you tell it to. No type
 167 inference is performed, expressions are not typed, etc. etc. etc.
 168 .PP
 169 A type constraint is at heart a small \*(L"check if a value is valid\*(R"
 170 function. A constraint can be associated with an attribute. This
 171 simplifies parameter validation, and makes your code clearer to read,
 172 because you can refer to constraints by name.
 173 .SS "Slightly Less Important Caveat"
 174 .IX Subsection "Slightly Less Important Caveat"
 175 It is \fBalways\fR a good idea to quote your type names.
 176 .PP
 177 This prevents Perl from trying to execute the call as an indirect
 178 object call. This can be an issue when you have a subtype with the
 179 same name as a valid class.
 180 .PP
 181 For instance:
 182 .PP
 183 .Vb 1
 184 \&  subtype DateTime => as Object => where { $_\->isa(\*(AqDateTime\*(Aq) };
 185 .Ve
 186 .PP
 187 will \fIjust work\fR, while this:
 188 .PP
 189 .Vb 2
 190 \&  use DateTime;
 191 \&  subtype DateTime => as Object => where { $_\->isa(\*(AqDateTime\*(Aq) };
 192 .Ve
 193 .PP
 194 will fail silently and cause many headaches. The simple way to solve
 195 this, as well as future proof your subtypes from classes which have
 196 yet to have been created, is to quote the type name:
 197 .PP
 198 .Vb 2
 199 \&  use DateTime;
 200 \&  subtype \*(AqDateTime\*(Aq => as \*(AqObject\*(Aq => where { $_\->isa(\*(AqDateTime\*(Aq) };
 201 .Ve
 202 .SS "Default Type Constraints"
 203 .IX Subsection "Default Type Constraints"
 204 This module also provides a simple hierarchy for Perl 5 types, here is
 205 that hierarchy represented visually.
 206 .PP
 207 .Vb 10
 208 \& Any
 209 \&  Item
 210 \&      Bool
 211 \&      Maybe[\`a]
 212 \&      Undef
 213 \&      Defined
 214 \&          Value
 215 \&              Str
 216 \&                  Num
 217 \&                      Int
 218 \&                  ClassName
 219 \&                  RoleName
 220 \&          Ref
 221 \&              ScalarRef
 222 \&              ArrayRef[\`a]
 223 \&              HashRef[\`a]
 224 \&              CodeRef
 225 \&              RegexpRef
 226 \&              GlobRef
 227 \&                  FileHandle
 228 \&              Object
 229 .Ve
 230 .PP
 231 \&\fB\s-1NOTE:\s0\fR Any type followed by a type parameter \f(CW\*(C`[\`a]\*(C'\fR can be
 232 parameterized, this means you can say:
 233 .PP
 234 .Vb 3
 235 \&  ArrayRef[Int]    # an array of integers
 236 \&  HashRef[CodeRef] # a hash of str to CODE ref mappings
 237 \&  Maybe[Str]       # value may be a string, may be undefined
 238 .Ve
 239 .PP
 240 If Mouse finds a name in brackets that it does not recognize as an
 241 existing type, it assumes that this is a class name, for example
 242 \&\f(CW\*(C`ArrayRef[DateTime]\*(C'\fR.
 243 .PP
 244 \&\fB\s-1NOTE:\s0\fR Unless you parameterize a type, then it is invalid to include
 245 the square brackets. I.e. \f(CW\*(C`ArrayRef[]\*(C'\fR will be treated as a new type
 246 name, \fInot\fR as a parameterization of \f(CW\*(C`ArrayRef\*(C'\fR.
 247 .PP
 248 \&\fB\s-1NOTE:\s0\fR The \f(CW\*(C`Undef\*(C'\fR type constraint for the most part works
 249 correctly now, but edge cases may still exist, please use it
 250 sparingly.
 251 .PP
 252 \&\fB\s-1NOTE:\s0\fR The \f(CW\*(C`ClassName\*(C'\fR type constraint does a complex package
 253 existence check. This means that your class \fBmust\fR be loaded for this
 254 type constraint to pass.
 255 .PP
 256 \&\fB\s-1NOTE:\s0\fR The \f(CW\*(C`RoleName\*(C'\fR constraint checks a string is a \fIpackage
 257 name\fR which is a role, like \f(CW\*(AqMyApp::Role::Comparable\*(Aq\fR. The \f(CW\*(C`Role\*(C'\fR
 258 constraint checks that an \fIobject does\fR the named role.
 259 .SS "Type Constraint Naming"
 260 .IX Subsection "Type Constraint Naming"
 261 Type name declared via this module can only contain alphanumeric
 262 characters, colons (:), and periods (.).
 263 .PP
 264 Since the types created by this module are global, it is suggested
 265 that you namespace your types just as you would namespace your
 266 modules. So instead of creating a \fIColor\fR type for your
 267 \&\fBMy::Graphics\fR module, you would call the type
 268 \&\fIMy::Graphics::Types::Color\fR instead.
 269 .SS "Use with Other Constraint Modules"
 270 .IX Subsection "Use with Other Constraint Modules"
 271 This module can play nicely with other constraint modules with some
 272 slight tweaking. The \f(CW\*(C`where\*(C'\fR clause in types is expected to be a
 273 \&\f(CW\*(C`CODE\*(C'\fR reference which checks it's first argument and returns a
 274 boolean. Since most constraint modules work in a similar way, it
 275 should be simple to adapt them to work with Mouse.
 276 .PP
 277 For instance, this is how you could use it with
 278 Declare::Constraints::Simple to declare a completely new type.
 279 .PP
 280 .Vb 7
 281 \&  type \*(AqHashOfArrayOfObjects\*(Aq,
 282 \&      {
 283 \&      where => IsHashRef(
 284 \&          \-keys   => HasLength,
 285 \&          \-values => IsArrayRef(IsObject)
 286 \&      )
 287 \&  };
 288 .Ve
 289 .PP
 290 Here is an example of using Test::Deep and it's non-test
 291 related \f(CW\*(C`eq_deeply\*(C'\fR function.
 292 .PP
 293 .Vb 8
 294 \&  type \*(AqArrayOfHashOfBarsAndRandomNumbers\*(Aq
 295 \&      => where {
 296 \&          eq_deeply($_,
 297 \&              array_each(subhashof({
 298 \&                  bar           => isa(\*(AqBar\*(Aq),
 299 \&                  random_number => ignore()
 300 \&              })))
 301 \&        };
 302 .Ve
 303 .SH "METHODS"
 304 .IX Header "METHODS"
 305 .ie n .SS """list_all_builtin_type_constraints \-> (Names)"""
 306 .el .SS "\f(CWlist_all_builtin_type_constraints \-> (Names)\fP"
 307 .IX Subsection "list_all_builtin_type_constraints -> (Names)"
 308 Returns the names of builtin type constraints.
 309 .ie n .SS """list_all_type_constraints \-> (Names)"""
 310 .el .SS "\f(CWlist_all_type_constraints \-> (Names)\fP"
 311 .IX Subsection "list_all_type_constraints -> (Names)"
 312 Returns the names of all the type constraints.
 313 .SH "FUNCTIONS"
 314 .IX Header "FUNCTIONS"
 315 .ie n .IP """subtype \*(AqName\*(Aq => as \*(AqParent\*(Aq => where { } ... \-> Mouse::Meta::TypeConstraint""" 4
 316 .el .IP "\f(CWsubtype \*(AqName\*(Aq => as \*(AqParent\*(Aq => where { } ... \-> Mouse::Meta::TypeConstraint\fR" 4
 317 .IX Item "subtype Name => as Parent => where { } ... -> Mouse::Meta::TypeConstraint"
 318 .PD 0
 319 .ie n .IP """subtype as \*(AqParent\*(Aq => where { } ...  \-> Mouse::Meta::TypeConstraint""" 4
 320 .el .IP "\f(CWsubtype as \*(AqParent\*(Aq => where { } ...  \-> Mouse::Meta::TypeConstraint\fR" 4
 321 .IX Item "subtype as Parent => where { } ...  -> Mouse::Meta::TypeConstraint"
 322 .ie n .IP """class_type ($class, ?$options) \-> Mouse::Meta::TypeConstraint""" 4
 323 .el .IP "\f(CWclass_type ($class, ?$options) \-> Mouse::Meta::TypeConstraint\fR" 4
 324 .IX Item "class_type ($class, ?$options) -> Mouse::Meta::TypeConstraint"
 325 .ie n .IP """role_type ($role, ?$options) \-> Mouse::Meta::TypeConstraint""" 4
 326 .el .IP "\f(CWrole_type ($role, ?$options) \-> Mouse::Meta::TypeConstraint\fR" 4
 327 .IX Item "role_type ($role, ?$options) -> Mouse::Meta::TypeConstraint"
 328 .ie n .IP """enum (\e@values) \-> Mouse::Meta::TypeConstraint""" 4
 329 .el .IP "\f(CWenum (\e@values) \-> Mouse::Meta::TypeConstraint\fR" 4
 330 .IX Item "enum (@values) -> Mouse::Meta::TypeConstraint"
 331 .ie n .IP """find_type_constraint(Type) \-> Mouse::Meta::TypeConstraint""" 4
 332 .el .IP "\f(CWfind_type_constraint(Type) \-> Mouse::Meta::TypeConstraint\fR" 4
 333 .IX Item "find_type_constraint(Type) -> Mouse::Meta::TypeConstraint"
 334 .PD
 335 .SH "THANKS"
 336 .IX Header "THANKS"
 337 Much of this documentation was taken from \f(CW\*(C`Moose::Util::TypeConstraints\*(C'\fR
 338 .SH "SEE ALSO"
 339 .IX Header "SEE ALSO"
 340 Moose::Util::TypeConstraints