5 Moose::Manual::Roles - Roles, an alternative to deep hierarchies and base classes
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.
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.
22 Moose roles are similar to mixins or interfaces in other languages.
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
32 Creating a role looks a lot like creating a Moose class:
51 Except for our use of L<Moose::Role>, this looks just like a class
52 definition with Moose. However, this is not a class, and it cannot be
55 Instead, its attributes and methods will be composed into classes
69 The C<with> function composes roles into a class. Once that is done,
70 the C<Car> class has an C<is_broken> attribute and a C<break>
71 method. The C<Car> class also C<does('Breakable')>:
73 my $car = Car->new( engine => Engine->new );
75 print $car->is_broken ? 'Still working' : 'Busted';
77 print $car->is_broken ? 'Still working' : 'Busted';
79 $car->does('Breakable'); # true
87 We could use this same role in a C<Bone> class:
100 =head1 REQUIRED METHODS
102 As mentioned previously, a role can require that consuming classes
103 provide one or more methods. Using our C<Breakable> example, let's
104 make it require that consuming classes implement their own C<break>
118 after 'break' => sub {
124 If we try to consume this role in a class that does not have a
125 C<break> method, we will get an exception.
127 You can see that we added a method modifier on C<break>. We want
128 classes that consume this role to implement their own logic for
129 breaking, but we make sure that the C<is_broken> attribute is always
130 set to true when C<break> is called.
146 if ( $self->is_moving ) {
151 =head2 Roles Versus Abstract Base Classes
153 If you are familiar with the concept of abstract base classes in other
154 languages, you may be tempted to use roles in the same way.
156 You I<can> define an "interface-only" role, one that contains I<just>
157 a list of required methods.
159 However, any class which consumes this role must implement all of the
160 required methods, either directly or through inheritance from a
161 parent. You cannot delay the method requirement check so that they can
162 be implemented by future subclasses.
164 Because the role defines the required methods directly, adding a base
165 class to the mix would not achieve anything. We recommend that you
166 simply consume the interface role in each class which implements that
169 =head1 USING METHOD MODIFIERS
171 Method modifiers and roles are a very powerful combination. Often, a
172 role will combine method modifiers and required methods. We already
173 saw one example with our C<Breakable> example.
175 Method modifiers increase the complexity of roles, because they make
176 the role application order relevant. If a class uses multiple roles,
177 each of which modify the same method, those modifiers will be applied
178 in the same order as the roles are used:
186 with 'Breakable', 'ExplodesOnBreakage';
188 Assuming that the new C<ExplodesOnBreakage> method I<also> has an
189 C<after> modifier on C<break>, the C<after> modifiers will run one
190 after the other. The modifier from C<Breakable> will run first, then
191 the one from C<ExplodesOnBreakage>.
193 =head1 METHOD CONFLICTS
195 If a class composes multiple roles, and those roles have methods of
196 the same name, we will have a conflict. In that case, the composing
197 class is required to provide its I<own> method of the same name.
207 If we compose both C<Breakable> and C<Breakdancer> in a class, we must
208 provide our own C<break> method:
210 package FragileDancer;
214 with 'Breakable', 'Breakdancer';
218 =head1 METHOD EXCLUSION AND ALIASING
220 If we want our C<FragileDancer> class to be able to call the methods
221 from both its roles, we can alias the methods:
223 package FragileDancer;
227 with 'Breakable' => { alias => { break => 'break_bone' } },
228 'Breakdancer' => { alias => { break => 'break_dance' } };
230 However, aliasing a method simply makes a I<copy> of the method with
231 the new name. We also need to exclude the original name:
233 with 'Breakable' => {
234 alias => { break => 'break_bone' },
238 alias => { break => 'break_dance' },
242 The exclude parameter prevents the C<break> method from being composed
243 into the C<FragileDancer> class, so we don't have a conflict. This
244 means that C<FragileDancer> does not need to implement its own
247 This is useful, but it's worth noting that this breaks the contract
248 implicit in consuming a role. Our C<FragileDancer> class does both the
249 C<Breakable> and C<BreakDancer>, but does not provide a C<break>
250 method. If some API expects an object that does one of those roles, it
251 probably expects it to implement that method.
253 In some use cases we might alias and exclude methods from roles, but
254 then provide a method of the same name in the class itself.
256 =head1 ROLE EXCLUSION
258 A role can say that it cannot be combined with some other role. This
259 should be used with great caution, since it limits the re-usability of
266 excludes 'BreakDancer';
270 Dave Rolsky E<lt>autarch@urth.orgE<gt>
272 =head1 COPYRIGHT AND LICENSE
274 Copyright 2009 by Infinity Interactive, Inc.
276 L<http://www.iinteractive.com>
278 This library is free software; you can redistribute it and/or modify
279 it under the same terms as Perl itself.