close over the coercion sub separately
[gitmo/Moose.git] / 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