lib/Moose/Spec/Role.pod

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