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>. Roles do not
12 participate in inheritance, and a role cannot be instantiated. We
13 sometimes say that classes I<consume> 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.
21 Moose roles are similar to mixins or interfaces in other languages.
23 Besides defining their own methods and attributes, roles can also
24 require that the consuming class define certain methods of its
25 own. You could have a role that consisted only of a list of required
26 methods, in which case the role would be very much like a Java
31 Creating a role looks a lot like creating a Moose class:
50 Except for our use of L<Moose::Role>, this looks just like a class
51 definition with Moose. However, this is not a class, and it cannot be
54 Instead, its attributes and methods will be composed into classes
68 The C<with> function composes roles into a class. Once that is done,
69 the C<Car> class has an C<is_broken> attribute and a C<break>
70 method. The C<Car> class also C<does('Breakable')>:
72 my $car = Car->new( engine => Engine->new );
74 print $car->is_broken ? 'Still working' : 'Busted';
76 print $car->is_broken ? 'Still working' : 'Busted';
78 $car->does('Breakable'); # true
86 We could use this same role in a C<Bone> class:
99 =head1 REQUIRED METHODS
101 As mentioned previously, a role can require that consuming classes
102 provide one or more methods. Using our C<Breakable> example, let's
103 make it require that consuming classes implement their own C<break>
117 after 'break' => sub {
123 If we try to consume this role in a class that does not have a
124 C<break> method, we will get an exception.
126 You can see that we added a method modifier on C<break>. We want
127 classes that consume this role to implement their own logic for
128 breaking, but we make sure that the C<is_broken> attribute is always
129 set to true when C<break> is called.
145 if ( $self->is_moving ) {
150 =head1 USING METHOD MODIFIERS
152 Method modifiers and roles are a very powerful combination. Often, a
153 role will combine method modifiers and required methods. We already
154 saw one example with our C<Breakable> example.
156 Method modifiers increase the complexity of roles, because they make
157 the role application order relevant. If a class uses multiple roles,
158 each of which modify the same method, those modifiers will be applied
159 in the same order as the roles are used:
167 with 'Breakable', 'ExplodesOnBreakage';
169 Assuming that the new C<ExplodesOnBreakage> method I<also> has an
170 C<after> modifier on C<break>, the C<after> modifiers will run one
171 after the other. The modifier from C<Breakable> will run first, then
172 the one from C<ExplodesOnBreakage>.
174 =head1 METHOD CONFLICTS
176 If a class composes multiple roles, and those roles have methods of
177 the same name, we will have a conflict. In that case, the composing
178 class is required to provide its I<own> method of the same name.
188 If we compose both C<Breakable> and C<Breakdancer> in a class, we must
189 provide our own C<break> method:
191 package FragileDancer;
195 with 'Breakable', 'Breakdancer';
199 =head1 METHOD EXCLUSION AND ALIASING
201 If we want our C<FragileDancer> class to be able to call the methods
202 from both its roles, we can alias the methods:
204 package FragileDancer;
208 with 'Breakable' => { alias => { break => 'break_bone' } },
209 'Breakdancer' => { alias => { break => 'break_dance' } };
211 However, aliasing a method simply makes a I<copy> of the method with
212 the new name. We also need to exclude the original name:
214 with 'Breakable' => {
215 alias => { break => 'break_bone' },
219 alias => { break => 'break_dance' },
223 The exclude parameter prevents the C<break> method from being composed
224 into the C<FragileDancer> class, so we don't have a conflict. This
225 means that C<FragileDancer> does not need to implement its own
228 This is useful, but it's worth noting that this breaks the contract
229 implicit in consuming a role. Our C<FragileDancer> class does both the
230 C<Breakable> and C<BreakDancer>, but does not provide a C<break>
231 method. If some API expects an object that does one of those roles, it
232 probably expects it to implement that method.
234 In some use cases we might alias and exclude methods from roles, but
235 then provide a method of the same name in the class itself.
237 =head1 ROLE EXCLUSION
239 A role can say that it cannot be combined with some other role. This
240 should be used with great caution, since it limits the re-usability of
247 excludes 'BreakDancer';
251 Dave Rolsky E<lt>autarch@urth.orgE<gt>
253 =head1 COPYRIGHT AND LICENSE
255 Copyright 2009 by Infinity Interactive, Inc.
257 L<http://www.iinteractive.com>
259 This library is free software; you can redistribute it and/or modify
260 it under the same terms as Perl itself.