6 Moose::Spec::Role - Formal spec for Role behavior
10 =head2 Components of a Role
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.
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.
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.
33 These are the methods defined within the role. Simple as that.
35 =item Required Methods
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
42 =item Required Attributes
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.
52 =item Overriden Methods
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.
61 It is key to remember that roles do not have hierarchy, so they
62 can never have a I<super> role.
64 =item Method Modifiers
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).
73 =head2 Role Composition
75 =head3 Composing into a Class
81 =item Required Methods
83 =item Required Attributes
89 =item Overriden methods
91 =item Method Modifiers (before, around, after)
95 =head3 Composing into a Instance
97 =head3 Composing into a Role
103 =item Required Methods
105 =item Required Attributes
111 =item Overriden methods
113 =item Method Modifiers (before, around, after)
117 =head3 Role Summation
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>).
128 =item Required Methods
130 =item Required Attributes
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.
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
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.
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:
156 Role A has method set { a, b, c }
157 Role B has method set { c, d, e }
159 The composite role (A,B) has
160 method set { a, b, d, e }
163 =item Overriden methods
165 An overriden method can conflict in one of two ways.
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
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
178 The use of override in roles can be tricky, but if used
179 carefully they can be a very powerful tool.
181 =item Method Modifiers (before, around, after)
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.
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.
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
199 =head3 Composition Edge Cases
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.
207 =item Role Method Overriding
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
215 Here is an example of this (incorrect) type of overriding.
222 package Role::FooBar;
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
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.
248 package Role::FooBar;
251 with 'Role::Foo', 'Role::Bar';
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.
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.
273 Roles are based on Traits, which originated in the Smalltalk
278 =item L<http://www.iam.unibe.ch/~scg/Research/Traits/>
280 This is the main site for the original Traits papers.
282 =item L<Class::Trait>
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).
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
299 =item L<http://www.oreillynet.com/onlamp/blog/2006/08/roles_composable_units_of_obje.html>
301 This is chromatic's take on roles, which is worth reading since
302 he was/is one of the big proponents of them.
304 =item L<http://svn.perl.org/perl6/doc/trunk/design/syn/S12.pod>
306 This is Synopsis 12, which is all about the Perl 6 Object System.
307 Which, of course, includes roles.
315 Stevan Little E<lt>stevan@iinteractive.comE<gt>
317 =head1 COPYRIGHT AND LICENSE
319 Copyright 2007-2008 by Infinity Interactive, Inc.
321 L<http://www.iinteractive.com>
323 This library is free software; you can redistribute it and/or modify
324 it under the same terms as Perl itself.