Commit | Line | Data |
24a8fe99 |
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 | |
709c321c |
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 | |
24a8fe99 |
24 | =item Attributes |
25 | |
709c321c |
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 | |
24a8fe99 |
31 | =item Methods |
32 | |
709c321c |
33 | These are the methods defined within the role. Simple as that. |
34 | |
24a8fe99 |
35 | =item Required Methods |
36 | |
709c321c |
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 | |
24a8fe99 |
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 | |
709c321c |
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 | |
24a8fe99 |
71 | =back |
72 | |
709c321c |
73 | =head2 Role Composition |
74 | |
3e19778d |
75 | =head3 Composing into a Class |
709c321c |
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 |
24a8fe99 |
94 | |
3e19778d |
95 | =head3 Composing into a Instance |
96 | |
97 | =head3 Composing into a Role |
24a8fe99 |
98 | |
99 | =over 4 |
100 | |
709c321c |
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 | |
3e19778d |
117 | =head3 Role Summation |
709c321c |
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 | |
24a8fe99 |
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 | |
3e19778d |
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 | |
24a8fe99 |
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 | |
778db3ac |
319 | Copyright 2007-2008 by Infinity Interactive, Inc. |
24a8fe99 |
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 | |