Commit | Line | Data |
ef45e915 |
1 | =pod |
2 | |
3 | =head1 NAME |
4 | |
d67ce58f |
5 | Moose::Manual::Roles - Roles, an alternative to deep hierarchies and base classes |
ef45e915 |
6 | |
7 | =head1 WHAT IS A ROLE? |
8 | |
9 | A role is something that classes do. Usually, a role encapsulates some |
10 | piece of behavior or state that can be shared between classes. It is |
c89a5d69 |
11 | important to understand that I<roles are not classes>. You cannot |
12 | inherit from a role, and a role cannot be instantiated. We sometimes |
13 | say that roles are I<consumed>, either by classes or other roles. |
ef45e915 |
14 | |
15 | Instead, a role is I<composed> into a class. In practical terms, this |
16 | means that all of the methods and attributes defined in a role are |
ca426a3a |
17 | added directly to (we sometimes say "flattened into") the class that |
18 | consumes the role. These attributes and methods then appear as if they |
c89a5d69 |
19 | were defined in the class itself. A subclass of the consuming class |
20 | will inherit all of these methods and attributes. |
ef45e915 |
21 | |
22 | Moose roles are similar to mixins or interfaces in other languages. |
23 | |
24 | Besides defining their own methods and attributes, roles can also |
25 | require that the consuming class define certain methods of its |
26 | own. You could have a role that consisted only of a list of required |
27 | methods, in which case the role would be very much like a Java |
28 | interface. |
29 | |
92fcea04 |
30 | Note that attribute accessors also count as methods for the |
31 | purposes of satisfying the requirements of a role. |
32 | |
ef45e915 |
33 | =head1 A SIMPLE ROLE |
34 | |
35 | Creating a role looks a lot like creating a Moose class: |
36 | |
37 | package Breakable; |
38 | |
39 | use Moose::Role; |
40 | |
41 | has 'is_broken' => ( |
42 | is => 'rw', |
43 | isa => 'Bool', |
44 | ); |
45 | |
46 | sub break { |
47 | my $self = shift; |
48 | |
49 | print "I broke\n"; |
50 | |
51 | $self->is_broken(1); |
52 | } |
53 | |
0c39debe |
54 | Except for our use of L<Moose::Role>, this looks just like a class |
ef45e915 |
55 | definition with Moose. However, this is not a class, and it cannot be |
56 | instantiated. |
57 | |
58 | Instead, its attributes and methods will be composed into classes |
59 | which use the role: |
60 | |
61 | package Car; |
62 | |
63 | use Moose; |
64 | |
65 | with 'Breakable'; |
66 | |
67 | has 'engine' => ( |
68 | is => 'ro', |
69 | isa => 'Engine', |
70 | ); |
71 | |
72 | The C<with> function composes roles into a class. Once that is done, |
73 | the C<Car> class has an C<is_broken> attribute and a C<break> |
74 | method. The C<Car> class also C<does('Breakable')>: |
75 | |
c56e5db4 |
76 | my $car = Car->new( engine => Engine->new ); |
ef45e915 |
77 | |
c56e5db4 |
78 | print $car->is_broken ? 'Still working' : 'Busted'; |
79 | $car->break; |
80 | print $car->is_broken ? 'Still working' : 'Busted'; |
ef45e915 |
81 | |
82 | $car->does('Breakable'); # true |
83 | |
84 | This prints: |
85 | |
86 | Still working |
87 | I broke |
88 | Busted |
89 | |
90 | We could use this same role in a C<Bone> class: |
91 | |
92 | package Bone; |
93 | |
94 | use Moose; |
95 | |
96 | with 'Breakable'; |
97 | |
98 | has 'marrow' => ( |
99 | is => 'ro', |
100 | isa => 'Marrow', |
101 | ); |
102 | |
103 | =head1 REQUIRED METHODS |
104 | |
105 | As mentioned previously, a role can require that consuming classes |
106 | provide one or more methods. Using our C<Breakable> example, let's |
107 | make it require that consuming classes implement their own C<break> |
108 | methods: |
109 | |
110 | package Breakable; |
111 | |
112 | use Moose::Role; |
113 | |
114 | requires 'break'; |
115 | |
116 | has 'is_broken' => ( |
117 | is => 'rw', |
118 | isa => 'Bool', |
119 | ); |
120 | |
121 | after 'break' => sub { |
122 | my $self = shift; |
123 | |
124 | $self->is_broken(1); |
c56e5db4 |
125 | }; |
ef45e915 |
126 | |
127 | If we try to consume this role in a class that does not have a |
128 | C<break> method, we will get an exception. |
129 | |
ca426a3a |
130 | You can see that we added a method modifier on C<break>. We want |
131 | classes that consume this role to implement their own logic for |
132 | breaking, but we make sure that the C<is_broken> attribute is always |
133 | set to true when C<break> is called. |
ef45e915 |
134 | |
135 | package Car |
136 | |
ca426a3a |
137 | use Moose; |
ef45e915 |
138 | |
139 | with 'Breakable'; |
140 | |
141 | has 'engine' => ( |
142 | is => 'ro', |
143 | isa => 'Engine', |
144 | ); |
145 | |
146 | sub break { |
147 | my $self = shift; |
148 | |
c56e5db4 |
149 | if ( $self->is_moving ) { |
150 | $self->stop; |
ef45e915 |
151 | } |
152 | } |
153 | |
c89a5d69 |
154 | =head2 Roles Versus Abstract Base Classes |
155 | |
156 | If you are familiar with the concept of abstract base classes in other |
157 | languages, you may be tempted to use roles in the same way. |
158 | |
398e8913 |
159 | You I<can> define an "interface-only" role, one that contains I<just> |
160 | a list of required methods. |
c89a5d69 |
161 | |
162 | However, any class which consumes this role must implement all of the |
163 | required methods, either directly or through inheritance from a |
164 | parent. You cannot delay the method requirement check so that they can |
165 | be implemented by future subclasses. |
166 | |
167 | Because the role defines the required methods directly, adding a base |
168 | class to the mix would not achieve anything. We recommend that you |
169 | simply consume the interface role in each class which implements that |
170 | interface. |
171 | |
ef45e915 |
172 | =head1 USING METHOD MODIFIERS |
173 | |
174 | Method modifiers and roles are a very powerful combination. Often, a |
175 | role will combine method modifiers and required methods. We already |
176 | saw one example with our C<Breakable> example. |
177 | |
eb169874 |
178 | Method modifiers increase the complexity of roles, because they make |
c56e5db4 |
179 | the role application order relevant. If a class uses multiple roles, |
180 | each of which modify the same method, those modifiers will be applied |
181 | in the same order as the roles are used: |
eb169874 |
182 | |
183 | package MovieCar; |
184 | |
185 | use Moose; |
186 | |
187 | extends 'Car'; |
188 | |
189 | with 'Breakable', 'ExplodesOnBreakage'; |
190 | |
191 | Assuming that the new C<ExplodesOnBreakage> method I<also> has an |
192 | C<after> modifier on C<break>, the C<after> modifiers will run one |
193 | after the other. The modifier from C<Breakable> will run first, then |
194 | the one from C<ExplodesOnBreakage>. |
195 | |
196 | =head1 METHOD CONFLICTS |
197 | |
198 | If a class composes multiple roles, and those roles have methods of |
199 | the same name, we will have a conflict. In that case, the composing |
200 | class is required to provide its I<own> method of the same name. |
201 | |
dab94063 |
202 | package Breakdancer; |
eb169874 |
203 | |
204 | use Moose::Role |
205 | |
206 | sub break { |
207 | |
208 | } |
209 | |
210 | If we compose both C<Breakable> and C<Breakdancer> in a class, we must |
211 | provide our own C<break> method: |
212 | |
213 | package FragileDancer; |
214 | |
215 | use Moose; |
216 | |
217 | with 'Breakable', 'Breakdancer'; |
ef45e915 |
218 | |
c56e5db4 |
219 | sub break { ... } |
220 | |
221 | =head1 METHOD EXCLUSION AND ALIASING |
222 | |
223 | If we want our C<FragileDancer> class to be able to call the methods |
224 | from both its roles, we can alias the methods: |
225 | |
226 | package FragileDancer; |
227 | |
228 | use Moose; |
229 | |
c8b8d92f |
230 | with 'Breakable' => { -alias => { break => 'break_bone' } }, |
231 | 'Breakdancer' => { -alias => { break => 'break_dance' } }; |
c56e5db4 |
232 | |
233 | However, aliasing a method simply makes a I<copy> of the method with |
234 | the new name. We also need to exclude the original name: |
235 | |
236 | with 'Breakable' => { |
c8b8d92f |
237 | -alias => { break => 'break_bone' }, |
238 | -excludes => 'break', |
c56e5db4 |
239 | }, |
240 | 'Breakdancer' => { |
c8b8d92f |
241 | -alias => { break => 'break_dance' }, |
242 | -excludes => 'break', |
c56e5db4 |
243 | }; |
244 | |
ffb800c0 |
245 | The excludes parameter prevents the C<break> method from being composed |
c56e5db4 |
246 | into the C<FragileDancer> class, so we don't have a conflict. This |
247 | means that C<FragileDancer> does not need to implement its own |
248 | C<break> method. |
249 | |
250 | This is useful, but it's worth noting that this breaks the contract |
251 | implicit in consuming a role. Our C<FragileDancer> class does both the |
252 | C<Breakable> and C<BreakDancer>, but does not provide a C<break> |
253 | method. If some API expects an object that does one of those roles, it |
254 | probably expects it to implement that method. |
255 | |
ca426a3a |
256 | In some use cases we might alias and exclude methods from roles, but |
257 | then provide a method of the same name in the class itself. |
258 | |
259 | =head1 ROLE EXCLUSION |
260 | |
261 | A role can say that it cannot be combined with some other role. This |
262 | should be used with great caution, since it limits the re-usability of |
263 | the role. |
264 | |
265 | package Breakable; |
266 | |
267 | use Moose::Role; |
268 | |
269 | excludes 'BreakDancer'; |
270 | |
a4bd85ad |
271 | =head1 AUTHOR |
272 | |
273 | Dave Rolsky E<lt>autarch@urth.orgE<gt> |
274 | |
275 | =head1 COPYRIGHT AND LICENSE |
276 | |
2840a3b2 |
277 | Copyright 2009 by Infinity Interactive, Inc. |
a4bd85ad |
278 | |
279 | L<http://www.iinteractive.com> |
280 | |
281 | This library is free software; you can redistribute it and/or modify |
282 | it under the same terms as Perl itself. |
283 | |
284 | =cut |