c2f5df1a7c2bc74749baf02449dfd04cff9a7b3e
[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 See also L<Moose::Cookbook::Roles::Recipe1> for an example.
104
105 =head1 REQUIRED METHODS
106
107 As mentioned previously, a role can require that consuming classes
108 provide one or more methods. Using our C<Breakable> example, let's
109 make it require that consuming classes implement their own C<break>
110 methods:
111
112   package Breakable;
113
114   use Moose::Role;
115
116   requires 'break';
117
118   has 'is_broken' => (
119       is  => 'rw',
120       isa => 'Bool',
121   );
122
123   after 'break' => sub {
124       my $self = shift;
125
126       $self->is_broken(1);
127   };
128
129 If we try to consume this role in a class that does not have a
130 C<break> method, we will get an exception.
131
132 You can see that we added a method modifier on C<break>. We want
133 classes that consume this role to implement their own logic for
134 breaking, but we make sure that the C<is_broken> attribute is always
135 set to true when C<break> is called.
136
137   package Car
138
139   use Moose;
140
141   with 'Breakable';
142
143   has 'engine' => (
144       is  => 'ro',
145       isa => 'Engine',
146   );
147
148   sub break {
149       my $self = shift;
150
151       if ( $self->is_moving ) {
152           $self->stop;
153       }
154   }
155
156 =head2 Roles Versus Abstract Base Classes
157
158 If you are familiar with the concept of abstract base classes in other
159 languages, you may be tempted to use roles in the same way.
160
161 You I<can> define an "interface-only" role, one that contains I<just>
162 a list of required methods.
163
164 However, any class which consumes this role must implement all of the
165 required methods, either directly or through inheritance from a
166 parent. You cannot delay the method requirement check so that they can
167 be implemented by future subclasses.
168
169 Because the role defines the required methods directly, adding a base
170 class to the mix would not achieve anything. We recommend that you
171 simply consume the interface role in each class which implements that
172 interface.
173
174 =head2 Required Attributes
175
176 As mentioned before, a role requirement may also be satisfied by an
177 attribute accessor. But any C<has> functions, which will generate
178 accessors that satisfy the role requirement, must be placed
179 I<before> the C<with> function that composes the role.
180
181   package Breakable;
182
183   use Moose::Role;
184
185   requires 'stress';
186
187   package Car;
188
189   use Moose;
190
191   has 'stress' => ( 
192       is  => 'rw',
193       isa => 'Int',
194   );
195
196   with 'Breakable';
197
198 =head1 USING METHOD MODIFIERS
199
200 Method modifiers and roles are a very powerful combination.  Often, a
201 role will combine method modifiers and required methods. We already
202 saw one example with our C<Breakable> example.
203
204 Method modifiers increase the complexity of roles, because they make
205 the role application order relevant. If a class uses multiple roles,
206 each of which modify the same method, those modifiers will be applied
207 in the same order as the roles are used:
208
209   package MovieCar;
210
211   use Moose;
212
213   extends 'Car';
214
215   with 'Breakable', 'ExplodesOnBreakage';
216
217 Assuming that the new C<ExplodesOnBreakage> method I<also> has an
218 C<after> modifier on C<break>, the C<after> modifiers will run one
219 after the other. The modifier from C<Breakable> will run first, then
220 the one from C<ExplodesOnBreakage>.
221
222 =head1 METHOD CONFLICTS
223
224 If a class composes multiple roles, and those roles have methods of
225 the same name, we will have a conflict. In that case, the composing
226 class is required to provide its I<own> method of the same name.
227
228   package Breakdancer;
229
230   use Moose::Role
231
232   sub break {
233
234   }
235
236 If we compose both C<Breakable> and C<Breakdancer> in a class, we must
237 provide our own C<break> method:
238
239   package FragileDancer;
240
241   use Moose;
242
243   with 'Breakable', 'Breakdancer';
244
245   sub break { ... }
246
247 A role can be a collection of other roles:
248
249   package Break::Bundle;
250
251   use Moose::Role;
252
253   with ('Breakable', 'Breakdancer');
254
255 =head1 METHOD EXCLUSION AND ALIASING
256
257 If we want our C<FragileDancer> class to be able to call the methods
258 from both its roles, we can alias the methods:
259
260   package FragileDancer;
261
262   use Moose;
263
264   with 'Breakable'   => { -alias => { break => 'break_bone' } },
265        'Breakdancer' => { -alias => { break => 'break_dance' } };
266
267 However, aliasing a method simply makes a I<copy> of the method with
268 the new name. We also need to exclude the original name:
269
270   with 'Breakable' => {
271       -alias    => { break => 'break_bone' },
272       -excludes => 'break',
273       },
274       'Breakdancer' => {
275       -alias    => { break => 'break_dance' },
276       -excludes => 'break',
277       };
278
279 The excludes parameter prevents the C<break> method from being composed
280 into the C<FragileDancer> class, so we don't have a conflict. This
281 means that C<FragileDancer> does not need to implement its own
282 C<break> method.
283
284 This is useful, but it's worth noting that this breaks the contract
285 implicit in consuming a role. Our C<FragileDancer> class does both the
286 C<Breakable> and C<BreakDancer>, but does not provide a C<break>
287 method. If some API expects an object that does one of those roles, it
288 probably expects it to implement that method.
289
290 In some use cases we might alias and exclude methods from roles, but
291 then provide a method of the same name in the class itself.
292
293 Also see L<Moose::Cookbook::Roles::Recipe2> for an example.
294
295 =head1 ROLE EXCLUSION
296
297 A role can say that it cannot be combined with some other role. This
298 should be used with great caution, since it limits the re-usability of
299 the role.
300
301   package Breakable;
302
303   use Moose::Role;
304
305   excludes 'BreakDancer';
306
307 =head1 APPLYING ROLES
308
309 A role can be applied to a class or an instance in other ways besides
310 using the 'with' syntax.
311
312 To apply a role to a class, use L<Moose::Util> and the 'apply_all_roles'
313 function. If you apply the role to a class, it will affect all objects of that
314 class. You can't apply a role to a class if it has been made immutable. In
315 some circumstances it may make sense to make the class mutable, apply the role,
316 then make the class immutable again.
317
318    use Moose::Util;
319    ...
320    my $class = 'MyApp::Test';
321    $class->meta->make_mutable;
322    Moose::Util::apply_all_roles($class->meta, ('MyApp::SomeRole'));
323    $class->meta->make_immutable;
324
325 Do not apply roles to classes that have immutable subclasses, since that
326 will invalidate the metadata of the subclasses.
327
328 If you want the role to be applied only to a particular instance and not to the
329 class, you can apply the roles to the instance instead of the class's meta:
330
331    Moose::Util::apply_all_roles($instance, ('MyApp::SomeRole'));
332
333 Or you can use the role's meta object:
334
335    MyApp::SomeRole->meta->apply($instance);
336
337 The mutable/immutable state is not relevant to roles applied to instances. 
338 See L<Moose::Role> and L<Moose::Util> for more details and 
339 L<Moose::Cookbook::Roles::Recipe3> for a more developed example.
340
341 =head1 AUTHOR
342
343 Dave Rolsky E<lt>autarch@urth.orgE<gt>
344
345 =head1 COPYRIGHT AND LICENSE
346
347 Copyright 2009 by Infinity Interactive, Inc.
348
349 L<http://www.iinteractive.com>
350
351 This library is free software; you can redistribute it and/or modify
352 it under the same terms as Perl itself.
353
354 =cut