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
30 Note that attribute accessors also count as methods for the
31 purposes of satisfying the requirements of a role.
35 Creating a role looks a lot like creating a Moose class:
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
58 Instead, its attributes and methods will be composed into classes
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')>:
76 my $car = Car->new( engine => Engine->new );
78 print $car->is_broken ? 'Still working' : 'Busted';
80 print $car->is_broken ? 'Still working' : 'Busted';
82 $car->does('Breakable'); # true
90 We could use this same role in a C<Bone> class:
103 =head1 REQUIRED METHODS
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>
121 after 'break' => sub {
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.
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.
149 if ( $self->is_moving ) {
154 =head2 Roles Versus Abstract Base Classes
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.
159 You I<can> define an "interface-only" role, one that contains I<just>
160 a list of required methods.
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.
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
172 =head1 USING METHOD MODIFIERS
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.
178 Method modifiers increase the complexity of roles, because they make
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:
189 with 'Breakable', 'ExplodesOnBreakage';
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>.
196 =head1 METHOD CONFLICTS
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.
210 If we compose both C<Breakable> and C<Breakdancer> in a class, we must
211 provide our own C<break> method:
213 package FragileDancer;
217 with 'Breakable', 'Breakdancer';
221 =head1 METHOD EXCLUSION AND ALIASING
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:
226 package FragileDancer;
230 with 'Breakable' => { -alias => { break => 'break_bone' } },
231 'Breakdancer' => { -alias => { break => 'break_dance' } };
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:
236 with 'Breakable' => {
237 -alias => { break => 'break_bone' },
238 -excludes => 'break',
241 -alias => { break => 'break_dance' },
242 -excludes => 'break',
245 The excludes parameter prevents the C<break> method from being composed
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
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.
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.
259 =head1 ROLE EXCLUSION
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
269 excludes 'BreakDancer';
273 Dave Rolsky E<lt>autarch@urth.orgE<gt>
275 =head1 COPYRIGHT AND LICENSE
277 Copyright 2009 by Infinity Interactive, Inc.
279 L<http://www.iinteractive.com>
281 This library is free software; you can redistribute it and/or modify
282 it under the same terms as Perl itself.