close over the coercion sub separately
[gitmo/Moose.git] / lib / Moose / Manual / Roles.pod
1 package Moose::Manual::Roles;
2
3 # ABSTRACT: Roles, an alternative to deep hierarchies and base classes
4
5 __END__
6
7 =pod
8
9 =head1 WHAT IS A ROLE?
10
11 A role encapsulates some piece of behavior or state that can be shared between
12 classes. It is something that classes I<do>. It is important to understand that
13 I<roles are not classes>. You cannot inherit from a role, and a role cannot be
14 instantiated. We sometimes say that roles are I<consumed>, either by classes
15 or other roles.
16
17 Instead, a role is I<composed> into a class. In practical terms, this
18 means that all of the methods, method modifiers, and attributes defined in a role are
19 added directly to (we sometimes say "flattened into") the class that
20 consumes the role. These attributes and methods then appear as if they
21 were defined in the class itself. A subclass of the consuming class
22 will inherit all of these methods and attributes.
23
24 Moose roles are similar to mixins or interfaces in other languages.
25
26 Besides defining their own methods and attributes, roles can also
27 require that the consuming class define certain methods of its
28 own. You could have a role that consisted only of a list of required
29 methods, in which case the role would be very much like a Java
30 interface.
31
32 Note that attribute accessors also count as methods for the
33 purposes of satisfying the requirements of a role.
34
35 =head1 A SIMPLE ROLE
36
37 Creating a role looks a lot like creating a Moose class:
38
39   package Breakable;
40
41   use Moose::Role;
42
43   has 'is_broken' => (
44       is  => 'rw',
45       isa => 'Bool',
46   );
47
48   sub break {
49       my $self = shift;
50
51       print "I broke\n";
52
53       $self->is_broken(1);
54   }
55
56 Except for our use of L<Moose::Role>, this looks just like a class
57 definition with Moose. However, this is not a class, and it cannot be
58 instantiated.
59
60 Instead, its attributes and methods will be composed into classes
61 which use the role:
62
63   package Car;
64
65   use Moose;
66
67   with 'Breakable';
68
69   has 'engine' => (
70       is  => 'ro',
71       isa => 'Engine',
72   );
73
74 The C<with> function composes roles into a class. Once that is done,
75 the C<Car> class has an C<is_broken> attribute and a C<break>
76 method. The C<Car> class also C<does('Breakable')>:
77
78   my $car = Car->new( engine => Engine->new );
79
80   print $car->is_broken ? 'Busted' : 'Still working';
81   $car->break;
82   print $car->is_broken ? 'Busted' : 'Still working';
83
84   $car->does('Breakable'); # true
85
86 This prints:
87
88   Still working
89   I broke
90   Busted
91
92 We could use this same role in a C<Bone> class:
93
94   package Bone;
95
96   use Moose;
97
98   with 'Breakable';
99
100   has 'marrow' => (
101       is  => 'ro',
102       isa => 'Marrow',
103   );
104
105 See also L<Moose::Cookbook::Roles::Recipe1> for an example.
106
107 =head1 REQUIRED METHODS
108
109 As mentioned previously, a role can require that consuming classes
110 provide one or more methods. Using our C<Breakable> example, let's
111 make it require that consuming classes implement their own C<break>
112 methods:
113
114   package Breakable;
115
116   use Moose::Role;
117
118   requires 'break';
119
120   has 'is_broken' => (
121       is  => 'rw',
122       isa => 'Bool',
123   );
124
125   after 'break' => sub {
126       my $self = shift;
127
128       $self->is_broken(1);
129   };
130
131 If we try to consume this role in a class that does not have a
132 C<break> method, we will get an exception.
133
134 You can see that we added a method modifier on C<break>. We want
135 classes that consume this role to implement their own logic for
136 breaking, but we make sure that the C<is_broken> attribute is always
137 set to true when C<break> is called.
138
139   package Car
140
141   use Moose;
142
143   with 'Breakable';
144
145   has 'engine' => (
146       is  => 'ro',
147       isa => 'Engine',
148   );
149
150   sub break {
151       my $self = shift;
152
153       if ( $self->is_moving ) {
154           $self->stop;
155       }
156   }
157
158 =head2 Roles Versus Abstract Base Classes
159
160 If you are familiar with the concept of abstract base classes in other
161 languages, you may be tempted to use roles in the same way.
162
163 You I<can> define an "interface-only" role, one that contains I<just>
164 a list of required methods.
165
166 However, any class which consumes this role must implement all of the
167 required methods, either directly or through inheritance from a
168 parent. You cannot delay the method requirement check so that they can
169 be implemented by future subclasses.
170
171 Because the role defines the required methods directly, adding a base
172 class to the mix would not achieve anything. We recommend that you
173 simply consume the interface role in each class which implements that
174 interface.
175
176 =head2 Required Attributes
177
178 As mentioned before, a role's required method may also be satisfied by an
179 attribute accessor. However, the call to C<has> which defines an attribute
180 happens at runtime. This means that you must define the attribute I<before>
181 consuming the role, or else the role will not see the generated accessor.
182
183   package Breakable;
184
185   use Moose::Role;
186
187   requires 'stress';
188
189   package Car;
190
191   use Moose;
192
193   has 'stress' => (
194       is  => 'rw',
195       isa => 'Int',
196   );
197
198   with 'Breakable';
199
200 =head1 USING METHOD MODIFIERS
201
202 Method modifiers and roles are a very powerful combination.  Often, a
203 role will combine method modifiers and required methods. We already
204 saw one example with our C<Breakable> example.
205
206 Method modifiers increase the complexity of roles, because they make
207 the role application order relevant. If a class uses multiple roles,
208 each of which modify the same method, those modifiers will be applied
209 in the same order as the roles are used:
210
211   package MovieCar;
212
213   use Moose;
214
215   extends 'Car';
216
217   with 'Breakable', 'ExplodesOnBreakage';
218
219 Assuming that the new C<ExplodesOnBreakage> method I<also> has an
220 C<after> modifier on C<break>, the C<after> modifiers will run one
221 after the other. The modifier from C<Breakable> will run first, then
222 the one from C<ExplodesOnBreakage>.
223
224 =head1 METHOD CONFLICTS
225
226 If a class composes multiple roles, and those roles have methods of
227 the same name, we will have a conflict. In that case, the composing
228 class is required to provide its I<own> method of the same name.
229
230   package Breakdancer;
231
232   use Moose::Role
233
234   sub break {
235
236   }
237
238 If we compose both C<Breakable> and C<Breakdancer> in a class, we must
239 provide our own C<break> method:
240
241   package FragileDancer;
242
243   use Moose;
244
245   with 'Breakable', 'Breakdancer';
246
247   sub break { ... }
248
249 A role can be a collection of other roles:
250
251   package Break::Bundle;
252
253   use Moose::Role;
254
255   with ('Breakable', 'Breakdancer');
256
257 =head1 METHOD EXCLUSION AND ALIASING
258
259 If we want our C<FragileDancer> class to be able to call the methods
260 from both its roles, we can alias the methods:
261
262   package FragileDancer;
263
264   use Moose;
265
266   with 'Breakable'   => { -alias => { break => 'break_bone' } },
267        'Breakdancer' => { -alias => { break => 'break_dance' } };
268
269 However, aliasing a method simply makes a I<copy> of the method with
270 the new name. We also need to exclude the original name:
271
272   with 'Breakable' => {
273       -alias    => { break => 'break_bone' },
274       -excludes => 'break',
275       },
276       'Breakdancer' => {
277       -alias    => { break => 'break_dance' },
278       -excludes => 'break',
279       };
280
281 The excludes parameter prevents the C<break> method from being composed
282 into the C<FragileDancer> class, so we don't have a conflict. This
283 means that C<FragileDancer> does not need to implement its own
284 C<break> method.
285
286 This is useful, but it's worth noting that this breaks the contract
287 implicit in consuming a role. Our C<FragileDancer> class does both the
288 C<Breakable> and C<BreakDancer>, but does not provide a C<break>
289 method. If some API expects an object that does one of those roles, it
290 probably expects it to implement that method.
291
292 In some use cases we might alias and exclude methods from roles, but
293 then provide a method of the same name in the class itself.
294
295 Also see L<Moose::Cookbook::Roles::Recipe2> for an example.
296
297 =head1 ROLE EXCLUSION
298
299 A role can say that it cannot be combined with some other role. This
300 should be used with great caution, since it limits the re-usability of
301 the role.
302
303   package Breakable;
304
305   use Moose::Role;
306
307   excludes 'BreakDancer';
308
309 =head1 ADDING A ROLE TO AN OBJECT INSTANCE
310
311 You may want to add a role to an object instance, rather than to a class. For
312 example, you may want to add debug tracing to one instance of an object while
313 debugging a particular bug. Another use case might be to dynamically change
314 objects based on a user's configuration, as a plugin system.
315
316 The best way to do this is to use the C<apply_all_roles()> function from
317 L<Moose::Util>:
318
319   use Moose::Util qw( apply_all_roles );
320
321   my $car = Car->new;
322   apply_all_roles( $car, 'Breakable' );
323
324 This function can apply more than one role at a time, and will do so using the
325 normal Moose role combination system. We recommend using this function to
326 apply roles to an object. This is what Moose uses internally when you call
327 C<with>.
328
329 =cut