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 | |
75 | =head3 Composing into a Role |
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 | |
709c321c |
95 | =head3 Composing into a Class |
24a8fe99 |
96 | |
97 | =over 4 |
98 | |
709c321c |
99 | =item Excluded Roles |
100 | |
101 | =item Required Methods |
102 | |
103 | =item Required Attributes |
104 | |
105 | =item Attributes |
106 | |
107 | =item Methods |
108 | |
109 | =item Overriden methods |
110 | |
111 | =item Method Modifiers (before, around, after) |
112 | |
113 | =back |
114 | |
115 | =head3 Composing into a Instance |
116 | |
117 | =head2 Role Summation |
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 | |
199 | =head1 SEE ALSO |
200 | |
201 | =over 4 |
202 | |
203 | =item Traits |
204 | |
205 | Roles are based on Traits, which originated in the Smalltalk |
206 | community. |
207 | |
208 | =over 4 |
209 | |
210 | =item L<http://www.iam.unibe.ch/~scg/Research/Traits/> |
211 | |
212 | This is the main site for the original Traits papers. |
213 | |
214 | =item L<Class::Trait> |
215 | |
216 | I created this implementation of traits several years ago, |
217 | after reading the papers linked above. (This module is now |
218 | maintatined by Ovid and I am no longer involved with it). |
219 | |
220 | =back |
221 | |
222 | =item Roles |
223 | |
224 | Since they are relatively new, and the Moose implementation |
225 | is probably the most mature out there, roles don't have much |
226 | to link to. However, here is some bits worth looking at (mostly |
227 | related to Perl 6) |
228 | |
229 | =over 4 |
230 | |
231 | =item L<http://www.oreillynet.com/onlamp/blog/2006/08/roles_composable_units_of_obje.html> |
232 | |
233 | This is chromatic's take on roles, which is worth reading since |
234 | he was/is one of the big proponents of them. |
235 | |
236 | =item L<http://svn.perl.org/perl6/doc/trunk/design/syn/S12.pod> |
237 | |
238 | This is Synopsis 12, which is all about the Perl 6 Object System. |
239 | Which, of course, includes roles. |
240 | |
241 | =back |
242 | |
243 | =back |
244 | |
245 | =head1 AUTHOR |
246 | |
247 | Stevan Little E<lt>stevan@iinteractive.comE<gt> |
248 | |
249 | =head1 COPYRIGHT AND LICENSE |
250 | |
778db3ac |
251 | Copyright 2007-2008 by Infinity Interactive, Inc. |
24a8fe99 |
252 | |
253 | L<http://www.iinteractive.com> |
254 | |
255 | This library is free software; you can redistribute it and/or modify |
256 | it under the same terms as Perl itself. |
257 | |
258 | =cut |
259 | |