lib/Moose/Spec/Role.pod

   1
   2 =pod
   3
   4 =head1 NAME
   5
   6 Moose::Spec::Role - Formal spec for Role behavior
   7
   8 =head1 DESCRIPTION
   9
  10 =head2 Components of a Role
  11
  12 =over 4
  13
  14 =item Excluded Roles
  15
  16 A role can have a list of excluded roles, these are basically
  17 roles that they shouldn't be composed with. This is not just
  18 direct composition either, but also "inherited" composition.
  19
  20 This feature was taken from the Fortress language and is really
  21 of most use when building a large set of role "building blocks"
  22 some of which should never be used together.
  23
  24 =item Attributes
  25
  26 A roles attributes are similar to those of a class, except that
  27 they are not actually applied. This means that methods that are
  28 generated by an attributes accessor will not be generated in the
  29 role, but only created once the role is applied to a class.
  30
  31 =item Methods
  32
  33 These are the methods defined within the role. Simple as that.
  34
  35 =item Required Methods
  36
  37 A role can require a consuming class (or role) to provide a
  38 given method. Failure to do so for classes is a fatal error,
  39 while for roles it simply passes on the method requirement to
  40 the consuming role.
  41
  42 =item Required Attributes
  43
  44 Just as a role can require methods, it can also require attributes.
  45 The requirement fufilling attribute must implement at least as much
  46 as is required. That means, for instance, that if the role requires
  47 that the attribute be readonly, then it must at least have a reader
  48 and can also have a writer. It means that if the role requires that
  49 the attribute be an ArrayRef, then it must either be an ArrayRef or
  50 a subtype of an ArrayRef.
  51
  52 =item Overriden Methods
  53
  54 The C<override> and C<super> keywords are allowed in roles, but
  55 thier behavior is different from that of it's class counterparts.
  56 The C<super> in a class refers directly to that class's superclass,
  57 while the C<super> in a role is deferred and only has meaning once
  58 the role is composed into a class. Once that composition occurs,
  59 C<super> then refers to that class's superclass.
  60
  61 It is key to remember that roles do not have hierarchy, so they
  62 can never have a I<super> role.
  63
  64 =item Method Modifiers
  65
  66 These are the C<before>, C<around> and C<after> modifiers provided
  67 in Moose classes. The difference here is that the modifiers are not
  68 actually applied until the role is composed into a class (this is
  69 just like attributes and the C<override> keyword).
  70
  71 =back
  72
  73 =head2 Role Composition
  74
  75 =head3 Composing into a Class
  76
  77 =over 4
  78
  79 =item Excluded Roles
  80
  81 =item Required Methods
  82
  83 =item Required Attributes
  84
  85 =item Attributes
  86
  87 =item Methods
  88
  89 =item Overriden methods
  90
  91 =item Method Modifiers (before, around, after)
  92
  93 =back
  94
  95 =head3 Composing into a Instance
  96
  97 =head3 Composing into a Role
  98
  99 =over 4
 100
 101 =item Excluded Roles
 102
 103 =item Required Methods
 104
 105 =item Required Attributes
 106
 107 =item Attributes
 108
 109 =item Methods
 110
 111 =item Overriden methods
 112
 113 =item Method Modifiers (before, around, after)
 114
 115 =back
 116
 117 =head3 Role Summation
 118
 119 When multiple roles are added to another role (using the
 120 C<with @roles> keyword) the roles are composed symmetrically.
 121 The product of the composition is a composite role
 122 (L<Moose::Meta::Role::Composite>).
 123
 124 =over 4
 125
 126 =item Excluded Roles
 127
 128 =item Required Methods
 129
 130 =item Required Attributes
 131
 132 =item Attributes
 133
 134 Attributes with the same name will conflict and are considered
 135 a un-recoverable error. No other aspect of the attribute is
 136 examained, it is enough that just the attribute names conflict.
 137
 138 The reason for such early and harsh conflicts with attributes
 139 is because there is so much room for variance between two
 140 attributes that the problem quickly explodes and rules get
 141 very complex. It is my opinion that this complexity is not
 142 worth the trouble.
 143
 144 =item Methods
 145
 146 Methods with the same name will conflict, but no error is
 147 thrown, instead the method name is added to the list of
 148 I<required> methods for the new composite role.
 149
 150 To look at this in terms of set theory, each role can be
 151 said to have a set of methods. The symmetric difference of
 152 these two sets is the new set of methods for the composite
 153 role, while the intersection of these two sets are the
 154 conflicts. This can be illustrated like so:
 155
 156    Role A has method set { a, b, c }
 157    Role B has method set { c, d, e }
 158
 159    The composite role (A,B) has
 160        method   set { a, b, d, e }
 161        conflict set { c }
 162
 163 =item Overriden methods
 164
 165 An overriden method can conflict in one of two ways.
 166
 167 The first way is with another overriden method of the same
 168 name, and this is considered an un-recoverable error. This
 169 is an obvious error since you cannot override a method twice
 170 in the same class.
 171
 172 The second way for conflict is for an overriden method and a
 173 regular method to have the same name. This is also an un-recoverable
 174 error since there is no way to combine these two, nor is it
 175 okay for both items to be composed into a single class at some
 176 point.
 177
 178 The use of override in roles can be tricky, but if used
 179 carefully they can be a very powerful tool.
 180
 181 =item Method Modifiers (before, around, after)
 182
 183 Method modifiers are the only place where the ordering of
 184 role composition matters. This is due to the nature of
 185 method modifiers themselves.
 186
 187 Since a method can have multiple method modifiers, these
 188 are just collected in order to be later applied to the
 189 class in that same order.
 190
 191 In general, great care should be taken in using method
 192 modifiers in roles. The order sensitivity can possibly
 193 lead to subtle and difficult to find bugs if they are
 194 overused. As with all good things in life, moderation
 195 is the key.
 196
 197 =back
 198
 199 =head3 Composition Edge Cases
 200
 201 This is a just a set of complex edge cases which can easily get
 202 confused. This attempts to clarify those cases and provide an
 203 explination of what is going on in them.
 204
 205 =over 4
 206
 207 =item Role Method Overriding
 208
 209 Many people want to "override" methods in roles they are consuming.
 210 This works fine for classes, since the local class method is favored
 211 over the role method. However in roles it is trickier, this is because
 212 conflicts result in neither method being chosen and the method being
 213 "required" instead.
 214
 215 Here is an example of this (incorrect) type of overriding.
 216
 217     package Role::Foo;
 218     use Moose::Role;
 219
 220     sub foo { ... }
 221
 222     package Role::FooBar;
 223     use Moose::Role;
 224
 225     with 'Role::Foo';
 226
 227     sub foo { ... }
 228     sub bar { ... }
 229
 230 Here the C<foo> methods conflict and the Role::FooBar now requires a
 231 class or role consuming it to implement C<foo>. This is very often not
 232 what the user wants.
 233
 234 Now here is an example of the (correct) type of overriding, only it is
 235 not overriding at all, as is explained in the text below.
 236
 237     package Role::Foo;
 238     use Moose::Role;
 239
 240     sub foo { ... }
 241
 242     package Role::Bar;
 243     use Moose::Role;
 244
 245     sub foo { ... }
 246     sub bar { ... }
 247
 248     package Role::FooBar;
 249     use Moose::Role;
 250
 251     with 'Role::Foo', 'Role::Bar';
 252
 253     sub foo { ... }
 254
 255 This works because the combination of Role::Foo and Role::Bar produce
 256 a conflict with the C<foo> method. This conflict results in the
 257 composite role (that was created by the combination of Role::Foo
 258 and Role::Bar using the I<with> keyword) having a method requirement
 259 of C<foo>. The Role::FooBar then fufills this requirement.
 260
 261 It is important to note that Role::FooBar is simply fufilling the
 262 required C<foo> method, and **NOT** overriding C<foo>. This is an
 263 important distinction to make.
 264
 265 =back
 266
 267 =head1 SEE ALSO
 268
 269 =over 4
 270
 271 =item Traits
 272
 273 Roles are based on Traits, which originated in the Smalltalk
 274 community.
 275
 276 =over 4
 277
 278 =item L<http://www.iam.unibe.ch/~scg/Research/Traits/>
 279
 280 This is the main site for the original Traits papers.
 281
 282 =item L<Class::Trait>
 283
 284 I created this implementation of traits several years ago,
 285 after reading the papers linked above. (This module is now
 286 maintatined by Ovid and I am no longer involved with it).
 287
 288 =back
 289
 290 =item Roles
 291
 292 Since they are relatively new, and the Moose implementation
 293 is probably the most mature out there, roles don't have much
 294 to link to. However, here is some bits worth looking at (mostly
 295 related to Perl 6)
 296
 297 =over 4
 298
 299 =item L<http://www.oreillynet.com/onlamp/blog/2006/08/roles_composable_units_of_obje.html>
 300
 301 This is chromatic's take on roles, which is worth reading since
 302 he was/is one of the big proponents of them.
 303
 304 =item L<http://svn.perl.org/perl6/doc/trunk/design/syn/S12.pod>
 305
 306 This is Synopsis 12, which is all about the Perl 6 Object System.
 307 Which, of course, includes roles.
 308
 309 =back
 310
 311 =back
 312
 313 =head1 AUTHOR
 314
 315 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 316
 317 =head1 COPYRIGHT AND LICENSE
 318
 319 Copyright 2007-2008 by Infinity Interactive, Inc.
 320
 321 L<http://www.iinteractive.com>
 322
 323 This library is free software; you can redistribute it and/or modify
 324 it under the same terms as Perl itself.
 325
 326 =cut
 327