888a238c6c56b70f4b8f595ba971eb6f6d285b76
[gitmo/Moose.git] / lib / Moose / Manual / Roles.pod
1 =pod
2
3 =head1 NAME
4
5 Moose::Manual::Roles - Roles, an alternative to deep hierarchies and base classes
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
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.
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
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
19 were defined in the class itself. A subclass of the consuming class
20 will inherit all of these methods and attributes.
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
30 Note that attribute accessors also count as methods for the
31 purposes of satisfying the requirements of a role. 
32
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
54 Except for our use of L<Moose::Role>, this looks just like a class
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
76   my $car = Car->new( engine => Engine->new );
77
78   print $car->is_broken ? 'Still working' : 'Busted';
79   $car->break;
80   print $car->is_broken ? 'Still working' : 'Busted';
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);
125   };
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
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.
134
135   package Car
136
137   use Moose;
138
139   with 'Breakable';
140
141   has 'engine' => (
142       is  => 'ro',
143       isa => 'Engine',
144   );
145
146   sub break {
147       my $self = shift;
148
149       if ( $self->is_moving ) {
150           $self->stop;
151       }
152   }
153
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
159 You I<can> define an "interface-only" role, one that contains I<just>
160 a list of required methods.
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
172 =head2 Required Attributes
173
174 As mentioned before, a role requirement may also be satisfied by an
175 attribute accessor. But any C<has> functions, which will generate
176 accessors that satisfy the role requirement, must be placed
177 I<before> the C<with> function that composes the role.
178
179   package Breakable;
180
181   use Moose::Role;
182
183   requires 'stress';
184
185   package Car;
186
187   use Moose;
188
189   has 'stress' => ( 
190       is  => 'rw',
191       isa => 'Int',
192   );
193
194   with 'Breakable';
195
196 =head1 USING METHOD MODIFIERS
197
198 Method modifiers and roles are a very powerful combination.  Often, a
199 role will combine method modifiers and required methods. We already
200 saw one example with our C<Breakable> example.
201
202 Method modifiers increase the complexity of roles, because they make
203 the role application order relevant. If a class uses multiple roles,
204 each of which modify the same method, those modifiers will be applied
205 in the same order as the roles are used:
206
207   package MovieCar;
208
209   use Moose;
210
211   extends 'Car';
212
213   with 'Breakable', 'ExplodesOnBreakage';
214
215 Assuming that the new C<ExplodesOnBreakage> method I<also> has an
216 C<after> modifier on C<break>, the C<after> modifiers will run one
217 after the other. The modifier from C<Breakable> will run first, then
218 the one from C<ExplodesOnBreakage>.
219
220 =head1 METHOD CONFLICTS
221
222 If a class composes multiple roles, and those roles have methods of
223 the same name, we will have a conflict. In that case, the composing
224 class is required to provide its I<own> method of the same name.
225
226   package Breakdancer;
227
228   use Moose::Role
229
230   sub break {
231
232   }
233
234 If we compose both C<Breakable> and C<Breakdancer> in a class, we must
235 provide our own C<break> method:
236
237   package FragileDancer;
238
239   use Moose;
240
241   with 'Breakable', 'Breakdancer';
242
243   sub break { ... }
244
245 =head1 METHOD EXCLUSION AND ALIASING
246
247 If we want our C<FragileDancer> class to be able to call the methods
248 from both its roles, we can alias the methods:
249
250   package FragileDancer;
251
252   use Moose;
253
254   with 'Breakable'   => { -alias => { break => 'break_bone' } },
255        'Breakdancer' => { -alias => { break => 'break_dance' } };
256
257 However, aliasing a method simply makes a I<copy> of the method with
258 the new name. We also need to exclude the original name:
259
260   with 'Breakable' => {
261       -alias    => { break => 'break_bone' },
262       -excludes => 'break',
263       },
264       'Breakdancer' => {
265       -alias    => { break => 'break_dance' },
266       -excludes => 'break',
267       };
268
269 The excludes parameter prevents the C<break> method from being composed
270 into the C<FragileDancer> class, so we don't have a conflict. This
271 means that C<FragileDancer> does not need to implement its own
272 C<break> method.
273
274 This is useful, but it's worth noting that this breaks the contract
275 implicit in consuming a role. Our C<FragileDancer> class does both the
276 C<Breakable> and C<BreakDancer>, but does not provide a C<break>
277 method. If some API expects an object that does one of those roles, it
278 probably expects it to implement that method.
279
280 In some use cases we might alias and exclude methods from roles, but
281 then provide a method of the same name in the class itself.
282
283 =head1 ROLE EXCLUSION
284
285 A role can say that it cannot be combined with some other role. This
286 should be used with great caution, since it limits the re-usability of
287 the role.
288
289   package Breakable;
290
291   use Moose::Role;
292
293   excludes 'BreakDancer';
294
295 =head1 AUTHOR
296
297 Dave Rolsky E<lt>autarch@urth.orgE<gt>
298
299 =head1 COPYRIGHT AND LICENSE
300
301 Copyright 2009 by Infinity Interactive, Inc.
302
303 L<http://www.iinteractive.com>
304
305 This library is free software; you can redistribute it and/or modify
306 it under the same terms as Perl itself.
307
308 =cut