local-lib5/man/man3/Moose::Spec::Role.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 "Moose::Spec::Role 3"
 132 .TH Moose::Spec::Role 3 "2009-05-01" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Moose::Spec::Role \- Formal spec for Role behavior
 135 .SH "DESCRIPTION"
 136 .IX Header "DESCRIPTION"
 137 \&\fB\s-1NOTE:\s0\fR This document is currently incomplete.
 138 .Sh "Components of a Role"
 139 .IX Subsection "Components of a Role"
 140 .IP "Excluded Roles" 4
 141 .IX Item "Excluded Roles"
 142 A role can have a list of excluded roles, these are basically
 143 roles that they shouldn't be composed with. This is not just
 144 direct composition either, but also \*(L"inherited\*(R" composition.
 145 .Sp
 146 This feature was taken from the Fortress language and is really
 147 of most use when building a large set of role \*(L"building blocks\*(R"
 148 some of which should never be used together.
 149 .IP "Attributes" 4
 150 .IX Item "Attributes"
 151 A roles attributes are similar to those of a class, except that
 152 they are not actually applied. This means that methods that are
 153 generated by an attributes accessor will not be generated in the
 154 role, but only created once the role is applied to a class.
 155 .IP "Methods" 4
 156 .IX Item "Methods"
 157 These are the methods defined within the role. Simple as that.
 158 .IP "Required Methods" 4
 159 .IX Item "Required Methods"
 160 A role can require a consuming class (or role) to provide a
 161 given method. Failure to do so for classes is a fatal error,
 162 while for roles it simply passes on the method requirement to
 163 the consuming role.
 164 .IP "Required Attributes" 4
 165 .IX Item "Required Attributes"
 166 Just as a role can require methods, it can also require attributes.
 167 The requirement fulfilling attribute must implement at least as much
 168 as is required. That means, for instance, that if the role requires
 169 that the attribute be read\-only, then it must at least have a reader
 170 and can also have a writer. It means that if the role requires that
 171 the attribute be an ArrayRef, then it must either be an ArrayRef or
 172 a subtype of an ArrayRef.
 173 .IP "Overridden Methods" 4
 174 .IX Item "Overridden Methods"
 175 The \f(CW\*(C`override\*(C'\fR and \f(CW\*(C`super\*(C'\fR keywords are allowed in roles, but
 176 their behavior is different from that of it's class counterparts.
 177 The \f(CW\*(C`super\*(C'\fR in a class refers directly to that class's superclass,
 178 while the \f(CW\*(C`super\*(C'\fR in a role is deferred and only has meaning once
 179 the role is composed into a class. Once that composition occurs,
 180 \&\f(CW\*(C`super\*(C'\fR then refers to that class's superclass.
 181 .Sp
 182 It is key to remember that roles do not have hierarchy, so they
 183 can never have a \fIsuper\fR role.
 184 .IP "Method Modifiers" 4
 185 .IX Item "Method Modifiers"
 186 These are the \f(CW\*(C`before\*(C'\fR, \f(CW\*(C`around\*(C'\fR and \f(CW\*(C`after\*(C'\fR modifiers provided
 187 in Moose classes. The difference here is that the modifiers are not
 188 actually applied until the role is composed into a class (this is
 189 just like attributes and the \f(CW\*(C`override\*(C'\fR keyword).
 190 .Sh "Role Composition"
 191 .IX Subsection "Role Composition"
 192 \fIComposing into a Class\fR
 193 .IX Subsection "Composing into a Class"
 194 .IP "Excluded Roles" 4
 195 .IX Item "Excluded Roles"
 196 .PD 0
 197 .IP "Required Methods" 4
 198 .IX Item "Required Methods"
 199 .IP "Required Attributes" 4
 200 .IX Item "Required Attributes"
 201 .IP "Attributes" 4
 202 .IX Item "Attributes"
 203 .IP "Methods" 4
 204 .IX Item "Methods"
 205 .IP "Overridden methods" 4
 206 .IX Item "Overridden methods"
 207 .IP "Method Modifiers (before, around, after)" 4
 208 .IX Item "Method Modifiers (before, around, after)"
 209 .PD
 210 .PP
 211 \fIComposing into a Instance\fR
 212 .IX Subsection "Composing into a Instance"
 213 .PP
 214 \fIComposing into a Role\fR
 215 .IX Subsection "Composing into a Role"
 216 .IP "Excluded Roles" 4
 217 .IX Item "Excluded Roles"
 218 .PD 0
 219 .IP "Required Methods" 4
 220 .IX Item "Required Methods"
 221 .IP "Required Attributes" 4
 222 .IX Item "Required Attributes"
 223 .IP "Attributes" 4
 224 .IX Item "Attributes"
 225 .IP "Methods" 4
 226 .IX Item "Methods"
 227 .IP "Overridden methods" 4
 228 .IX Item "Overridden methods"
 229 .IP "Method Modifiers (before, around, after)" 4
 230 .IX Item "Method Modifiers (before, around, after)"
 231 .PD
 232 .PP
 233 \fIRole Summation\fR
 234 .IX Subsection "Role Summation"
 235 .PP
 236 When multiple roles are added to another role (using the
 237 \&\f(CW\*(C`with @roles\*(C'\fR keyword) the roles are composed symmetrically.
 238 The product of the composition is a composite role
 239 (Moose::Meta::Role::Composite).
 240 .IP "Excluded Roles" 4
 241 .IX Item "Excluded Roles"
 242 .PD 0
 243 .IP "Required Methods" 4
 244 .IX Item "Required Methods"
 245 .IP "Required Attributes" 4
 246 .IX Item "Required Attributes"
 247 .IP "Attributes" 4
 248 .IX Item "Attributes"
 249 .PD
 250 Attributes with the same name will conflict and are considered
 251 a unrecoverable error. No other aspect of the attribute is
 252 examined, it is enough that just the attribute names conflict.
 253 .Sp
 254 The reason for such early and harsh conflicts with attributes
 255 is because there is so much room for variance between two
 256 attributes that the problem quickly explodes and rules get
 257 very complex. It is my opinion that this complexity is not
 258 worth the trouble.
 259 .IP "Methods" 4
 260 .IX Item "Methods"
 261 Methods with the same name will conflict, but no error is
 262 thrown, instead the method name is added to the list of
 263 \&\fIrequired\fR methods for the new composite role.
 264 .Sp
 265 To look at this in terms of set theory, each role can be
 266 said to have a set of methods. The symmetric difference of
 267 these two sets is the new set of methods for the composite
 268 role, while the intersection of these two sets are the
 269 conflicts. This can be illustrated like so:
 270 .Sp
 271 .Vb 2
 272 \&   Role A has method set { a, b, c }
 273 \&   Role B has method set { c, d, e }
 274 .Ve
 275 .Sp
 276 .Vb 3
 277 \&   The composite role (A,B) has
 278 \&       method   set { a, b, d, e }
 279 \&       conflict set { c }
 280 .Ve
 281 .IP "Overridden methods" 4
 282 .IX Item "Overridden methods"
 283 An overridden method can conflict in one of two ways.
 284 .Sp
 285 The first way is with another overridden method of the same
 286 name, and this is considered an unrecoverable error. This
 287 is an obvious error since you cannot override a method twice
 288 in the same class.
 289 .Sp
 290 The second way for conflict is for an overridden method and a
 291 regular method to have the same name. This is also an unrecoverable
 292 error since there is no way to combine these two, nor is it
 293 okay for both items to be composed into a single class at some
 294 point.
 295 .Sp
 296 The use of override in roles can be tricky, but if used
 297 carefully they can be a very powerful tool.
 298 .IP "Method Modifiers (before, around, after)" 4
 299 .IX Item "Method Modifiers (before, around, after)"
 300 Method modifiers are the only place where the ordering of
 301 role composition matters. This is due to the nature of
 302 method modifiers themselves.
 303 .Sp
 304 Since a method can have multiple method modifiers, these
 305 are just collected in order to be later applied to the
 306 class in that same order.
 307 .Sp
 308 In general, great care should be taken in using method
 309 modifiers in roles. The order sensitivity can possibly
 310 lead to subtle and difficult to find bugs if they are
 311 overused. As with all good things in life, moderation
 312 is the key.
 313 .PP
 314 \fIComposition Edge Cases\fR
 315 .IX Subsection "Composition Edge Cases"
 316 .PP
 317 This is a just a set of complex edge cases which can easily get
 318 confused. This attempts to clarify those cases and provide an
 319 explanation of what is going on in them.
 320 .IP "Role Method Overriding" 4
 321 .IX Item "Role Method Overriding"
 322 Many people want to \*(L"override\*(R" methods in roles they are consuming.
 323 This works fine for classes, since the local class method is favored
 324 over the role method. However in roles it is trickier, this is because
 325 conflicts result in neither method being chosen and the method being
 326 \&\*(L"required\*(R" instead.
 327 .Sp
 328 Here is an example of this (incorrect) type of overriding.
 329 .Sp
 330 .Vb 2
 331 \&    package Role::Foo;
 332 \&    use Moose::Role;
 333 .Ve
 334 .Sp
 335 .Vb 1
 336 \&    sub foo { ... }
 337 .Ve
 338 .Sp
 339 .Vb 2
 340 \&    package Role::FooBar;
 341 \&    use Moose::Role;
 342 .Ve
 343 .Sp
 344 .Vb 1
 345 \&    with 'Role::Foo';
 346 .Ve
 347 .Sp
 348 .Vb 2
 349 \&    sub foo { ... }
 350 \&    sub bar { ... }
 351 .Ve
 352 .Sp
 353 Here the \f(CW\*(C`foo\*(C'\fR methods conflict and the Role::FooBar now requires a
 354 class or role consuming it to implement \f(CW\*(C`foo\*(C'\fR. This is very often not
 355 what the user wants.
 356 .Sp
 357 Now here is an example of the (correct) type of overriding, only it is
 358 not overriding at all, as is explained in the text below.
 359 .Sp
 360 .Vb 2
 361 \&    package Role::Foo;
 362 \&    use Moose::Role;
 363 .Ve
 364 .Sp
 365 .Vb 1
 366 \&    sub foo { ... }
 367 .Ve
 368 .Sp
 369 .Vb 2
 370 \&    package Role::Bar;
 371 \&    use Moose::Role;
 372 .Ve
 373 .Sp
 374 .Vb 2
 375 \&    sub foo { ... }
 376 \&    sub bar { ... }
 377 .Ve
 378 .Sp
 379 .Vb 2
 380 \&    package Role::FooBar;
 381 \&    use Moose::Role;
 382 .Ve
 383 .Sp
 384 .Vb 1
 385 \&    with 'Role::Foo', 'Role::Bar';
 386 .Ve
 387 .Sp
 388 .Vb 1
 389 \&    sub foo { ... }
 390 .Ve
 391 .Sp
 392 This works because the combination of Role::Foo and Role::Bar produce
 393 a conflict with the \f(CW\*(C`foo\*(C'\fR method. This conflict results in the
 394 composite role (that was created by the combination of Role::Foo
 395 and Role::Bar using the \fIwith\fR keyword) having a method requirement
 396 of \f(CW\*(C`foo\*(C'\fR. The Role::FooBar then fulfills this requirement.
 397 .Sp
 398 It is important to note that Role::FooBar is simply fulfilling the
 399 required \f(CW\*(C`foo\*(C'\fR method, and **NOT** overriding \f(CW\*(C`foo\*(C'\fR. This is an
 400 important distinction to make.
 401 .Sp
 402 Now here is another example of a (correct) type of overriding, this
 403 time using the \fIexcludes\fR option.
 404 .Sp
 405 .Vb 2
 406 \&    package Role::Foo;
 407 \&    use Moose::Role;
 408 .Ve
 409 .Sp
 410 .Vb 1
 411 \&    sub foo { ... }
 412 .Ve
 413 .Sp
 414 .Vb 2
 415 \&    package Role::FooBar;
 416 \&    use Moose::Role;
 417 .Ve
 418 .Sp
 419 .Vb 1
 420 \&    with 'Role::Foo' => { excludes => 'foo' };
 421 .Ve
 422 .Sp
 423 .Vb 2
 424 \&    sub foo { ... }
 425 \&    sub bar { ... }
 426 .Ve
 427 .Sp
 428 By specifically excluding the \f(CW\*(C`foo\*(C'\fR method during composition,
 429 we allow \fBRole::FooBar\fR to define it's own version of \f(CW\*(C`foo\*(C'\fR.
 430 .SH "SEE ALSO"
 431 .IX Header "SEE ALSO"
 432 .IP "Traits" 4
 433 .IX Item "Traits"
 434 Roles are based on Traits, which originated in the Smalltalk
 435 community.
 436 .RS 4
 437 .IP "<http://www.iam.unibe.ch/~scg/Research/Traits/>" 4
 438 .IX Item "<http://www.iam.unibe.ch/~scg/Research/Traits/>"
 439 This is the main site for the original Traits papers.
 440 .IP "Class::Trait" 4
 441 .IX Item "Class::Trait"
 442 I created this implementation of traits several years ago,
 443 after reading the papers linked above. (This module is now
 444 maintained by Ovid and I am no longer involved with it).
 445 .RE
 446 .RS 4
 447 .RE
 448 .IP "Roles" 4
 449 .IX Item "Roles"
 450 Since they are relatively new, and the Moose implementation
 451 is probably the most mature out there, roles don't have much
 452 to link to. However, here is some bits worth looking at (mostly
 453 related to Perl 6)
 454 .RS 4
 455 .IP "<http://www.oreillynet.com/onlamp/blog/2006/08/roles_composable_units_of_obje.html>" 4
 456 .IX Item "<http://www.oreillynet.com/onlamp/blog/2006/08/roles_composable_units_of_obje.html>"
 457 This is chromatic's take on roles, which is worth reading since
 458 he was/is one of the big proponents of them.
 459 .IP "<http://svn.perl.org/perl6/doc/trunk/design/syn/S12.pod>" 4
 460 .IX Item "<http://svn.perl.org/perl6/doc/trunk/design/syn/S12.pod>"
 461 This is Synopsis 12, which is all about the Perl 6 Object System.
 462 Which, of course, includes roles.
 463 .RE
 464 .RS 4
 465 .RE
 466 .SH "AUTHOR"
 467 .IX Header "AUTHOR"
 468 Stevan Little <stevan@iinteractive.com>
 469 .SH "COPYRIGHT AND LICENSE"
 470 .IX Header "COPYRIGHT AND LICENSE"
 471 Copyright 2007\-2009 by Infinity Interactive, Inc.
 472 .PP
 473 <http://www.iinteractive.com>
 474 .PP
 475 This library is free software; you can redistribute it and/or modify
 476 it under the same terms as Perl itself.