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