1Moose::Manual::Roles(3)User Contributed Perl DocumentatioMnoose::Manual::Roles(3)
2
6 Moose::Manual::Roles - Roles, an alternative to deep hierarchies and
7 base classes
8
10 version 2.2201
11
13 A role encapsulates some piece of behavior or state that can be shared
14 between classes. It is something that classes do. It is important to
15 understand that roles are not classes. You cannot inherit from a role,
16 and a role cannot be instantiated. We sometimes say that roles are
17 consumed, either by classes or other roles.
18 Instead, a role is composed into a class. In practical terms, this
20 means that all of the methods, method modifiers, and attributes defined
21 in a role are added directly to (we sometimes say "flattened into") the
22 class that consumes the role. These attributes and methods then appear
23 as if they were defined in the class itself. A subclass of the
24 consuming class will inherit all of these methods and attributes.
25 Moose roles are similar to mixins or interfaces in other languages and
27 are based on the original concept of Traits
28 <http://scg.unibe.ch/research/traits/> for the Smalltalk-80 dialect
29 Squeak.
30 Besides defining their own methods and attributes, roles can also
32 require that the consuming class define certain methods of its own. You
33 could have a role that consisted only of a list of required methods, in
34 which case the role would be very much like a Java interface.
35 Note that attribute accessors also count as methods for the purposes of
37 satisfying the requirements of a role.
38
40 Creating a role looks a lot like creating a Moose class:
41 package Breakable;
43 use Moose::Role;
45 has 'is_broken' => (
47 is => 'rw',
48 isa => 'Bool',
49 );
50 sub break {
52 my $self = shift;
53 print "I broke\n";
55 $self->is_broken(1);
57 }
58 Except for our use of Moose::Role, this looks just like a class
60 definition with Moose. However, this is not a class, and it cannot be
61 instantiated.
62 Instead, its attributes and methods will be composed into classes which
64 use the role:
65 package Car;
67 use Moose;
69 with 'Breakable';
71 has 'engine' => (
73 is => 'ro',
74 isa => 'Engine',
75 );
76 The "with" function composes roles into a class. Once that is done, the
78 "Car" class has an "is_broken" attribute and a "break" method. The
79 "Car" class also "does('Breakable')":
80 my $car = Car->new( engine => Engine->new );
82 print $car->is_broken ? 'Busted' : 'Still working';
84 $car->break;
85 print $car->is_broken ? 'Busted' : 'Still working';
86 $car->does('Breakable'); # true
88 This prints:
90 Still working
92 I broke
93 Busted
94 We could use this same role in a "Bone" class:
96 package Bone;
98 use Moose;
100 with 'Breakable';
102 has 'marrow' => (
104 is => 'ro',
105 isa => 'Marrow',
106 );
107 See also Moose::Cookbook::Roles::Comparable_CodeReuse for an example.
109 It's possible to compose existing roles into new roles. For example, we
111 can have a "HandleWithCare" class which applies both the "Breakable"
112 and "Package" roles to any class which consumes it:
113 package HandleWithCare;
115 use Moose::Role;
117 with 'Breakable', 'Package';
119
121 As mentioned previously, a role can require that consuming classes
122 provide one or more methods. Using our "Breakable" example, let's make
123 it require that consuming classes implement their own "break" methods:
124 package Breakable;
126 use Moose::Role;
128 requires 'break';
130 has 'is_broken' => (
132 is => 'rw',
133 isa => 'Bool',
134 );
135 after 'break' => sub {
137 my $self = shift;
138 $self->is_broken(1);
140 };
141 If we try to consume this role in a class that does not have a "break"
143 method, we will get an exception.
144 You can see that we added a method modifier on "break". We want classes
146 that consume this role to implement their own logic for breaking, but
147 we make sure that the "is_broken" attribute is always set to true when
148 "break" is called.
149 package Car
151 use Moose;
153 with 'Breakable';
155 has 'engine' => (
157 is => 'ro',
158 isa => 'Engine',
159 );
160 sub break {
162 my $self = shift;
163 if ( $self->is_moving ) {
165 $self->stop;
166 }
167 }
168 Roles Versus Abstract Base Classes
170 If you are familiar with the concept of abstract base classes in other
171 languages, you may be tempted to use roles in the same way.
172 You can define an "interface-only" role, one that contains just a list
174 of required methods.
175 However, any class which consumes this role must implement all of the
177 required methods, either directly or through inheritance from a parent.
178 You cannot delay the method requirement check so that they can be
179 implemented by future subclasses.
180 Because the role defines the required methods directly, adding a base
182 class to the mix would not achieve anything. We recommend that you
183 simply consume the interface role in each class which implements that
184 interface.
185
187 Roles are consumed using the "with" function.
188 Most of the time, you should only use one "with", even if you are
190 consuming multiple roles. If you consume roles using multiple "with"
191 statements Moose cannot detect method conflicts between those roles.
192 Roles can be consumed by classes or by other roles. When a class
194 consumes a role which in turn consumes other roles, the class gets all
195 of the roles applied at once.
196 Required Methods Provided by Attributes
198 As mentioned before, a role's required method may also be satisfied by
199 an attribute accessor. However, the call to "has" which defines an
200 attribute happens at runtime. This means that you must define the
201 attribute before consuming the role, or else the role will not see the
202 generated accessor. These attributes are Moose Attributes.
203 package Breakable;
205 use Moose::Role;
207 requires 'stress';
209 ########
211 package Car;
213 use Moose;
215 has 'stress' => (
217 is => 'ro',
218 isa => 'Int',
219 );
220 with 'Breakable';
222 In general, we recommend that you always consume roles after declaring
224 all your attributes.
225 It may also be the case that a class wants to consume two roles where
227 one role has an attribute providing a required method for another. For
228 example:
229 package Breakable;
231 use Moose::Role;
233 requires 'stress';
235 ########
237 package Stressable;
239 use Moose::Role;
241 has 'stress' => (
243 is => 'ro',
244 isa => 'Int',
245 );
246 ########
248 package Car;
250 use Moose;
252 # XXX - this will not work
254 with 'Breakable', 'Stressable';
255 However, this won't work. The problem is that the accessor methods
257 created for the "stress" attribute won't be present in the class when
258 the required method checks are done.
259 There are two possible workarounds. The recommended one is to use
261 "stub" subroutine(s) in the role providing the accessor(s):
262 package Stressable;
264 use Moose::Role;
266 sub stress;
268 has 'stress' => (
269 is => 'ro',
270 isa => 'Int',
271 );
272 The "sub stress;" line is called a "forward" declaration in the Perl
274 documentation. It creates what is called a "stub" subroutine, a
275 declaration without a body. This is good enough to satisfy the required
276 method checks done by Moose. The stub will not interfere with the
277 creation of a real subroutine later.
278 The other alternative is to use two separate calls to "with" in the
280 consuming class:
281 package Car;
283 use Moose;
285 # Not recommended
287 with 'Stressable';
288 with 'Breakable';
289 Each "with" is run as it is seen. The first call will consume just the
291 "Stressable" role, which will add the "stress" attribute to the "Car"
292 package, which in turn will create an accessor method named "stress".
293 Then when the "Breakable" role is consumed, the method it requires
294 already exists.
295 However, as mentioned earlier, multiple "with" declarations are not
297 recommended, because method conflicts between the roles cannot be seen.
298 In the example above, if both "Stressable" and "Breakable" contained
299 methods of the same name, what would happen is that the version in
300 "Stressable" would silently override the one in "Breakable".
301
303 Method modifiers and roles are a very powerful combination. Often, a
304 role will combine method modifiers and required methods. We already saw
305 one example with our "Breakable" example.
306 Method modifiers increase the complexity of roles, because they make
308 the role application order relevant. If a class uses multiple roles,
309 each of which modify the same method, those modifiers will be applied
310 in the same order as the roles are used:
311 package MovieCar;
313 use Moose;
315 extends 'Car';
317 with 'Breakable', 'ExplodesOnBreakage';
319 Assuming that the new "ExplodesOnBreakage" role also has an "after"
321 modifier on "break", the "after" modifiers will run one after the
322 other. The modifier from "Breakable" will run first, then the one from
323 "ExplodesOnBreakage".
324
326 If a class composes multiple roles, and those roles have methods of the
327 same name, we will have a conflict. In that case, the composing class
328 is required to provide its own method of the same name.
329 package Breakdancer;
331 use Moose::Role;
333 sub break {
335 }
337 If we compose both "Breakable" and "Breakdancer" in a class, we must
339 provide our own "break" method:
340 package FragileDancer;
342 use Moose;
344 with 'Breakable', 'Breakdancer';
346 sub break { ... }
348 A role can be a collection of other roles:
350 package Break::Bundle;
352 use Moose::Role;
354 with ('Breakable', 'Breakdancer');
356 When a role consumes another a role, the consuming role's methods
358 silently win in any conflict, and the consumed role's methods are
359 simply ignored.
360
362 If we want our "FragileDancer" class to be able to call the methods
363 from both its roles, we can alias the methods:
364 package FragileDancer;
366 use Moose;
368 with 'Breakable' => { -alias => { break => 'break_bone' } },
370 'Breakdancer' => { -alias => { break => 'break_dance' } };
371 However, aliasing a method simply makes a copy of the method with the
373 new name. We also need to exclude the original name:
374 with 'Breakable' => {
376 -alias => { break => 'break_bone' },
377 -excludes => 'break',
378 },
379 'Breakdancer' => {
380 -alias => { break => 'break_dance' },
381 -excludes => 'break',
382 };
383 The excludes parameter prevents the "break" method from being composed
385 into the "FragileDancer" class, so we don't have a conflict. This means
386 that "FragileDancer" does not need to implement its own "break" method.
387 This is useful, but it's worth noting that this breaks the contract
389 implicit in consuming a role. Our "FragileDancer" class does both the
390 "Breakable" and "BreakDancer", but does not provide a "break" method.
391 If some API expects an object that does one of those roles, it probably
392 expects it to implement that method.
393 In some use cases we might alias and exclude methods from roles, but
395 then provide a method of the same name in the class itself.
396 Also see Moose::Cookbook::Roles::Restartable_AdvancedComposition for an
398 example.
399
401 When a Moose role uses overloading, that overloading is composed into
402 any classes that consume the role. This includes the setting of the
403 "fallback" value for that role's overloading. Just as with methods and
404 attributes, when a role consumes another role, that other role's
405 overloading settings are applied to the role.
406 Just as with methods, there can be conflicts with overloading
408 implementations between multiple roles when they are all consumed by a
409 class. If two roles both provide different overloading implementations
410 for a given operator, that is a conflict. If two roles both implement
411 overloading and have different "fallback" values, that is also
412 considered a conflict. These conflicts are detected when multiple roles
413 are being composed into a class together.
414 When a role consumes another role, the consuming role's overloading
416 fallback and operator implementations silently "win" the conflict.
417
419 A role can say that it cannot be combined with some other role. This
420 should be used with great caution, since it limits the re-usability of
421 the role.
422 package Breakable;
424 use Moose::Role;
426 excludes 'BreakDancer';
428
430 You may want to add a role to an object instance, rather than to a
431 class. For example, you may want to add debug tracing to one instance
432 of an object while debugging a particular bug. Another use case might
433 be to dynamically change objects based on a user's configuration, as a
434 plugin system.
435 The best way to do this is to use the "apply_all_roles()" function from
437 Moose::Util:
438 use Moose::Util qw( apply_all_roles );
440 my $car = Car->new;
442 apply_all_roles( $car, 'Breakable' );
443 This function can apply more than one role at a time, and will do so
445 using the normal Moose role combination system. We recommend using this
446 function to apply roles to an object. This is what Moose uses
447 internally when you call "with".
448 Handling required attributes for roles.
450 Application of some roles will require additional parameters being
451 specified to satisfy them, for example:
452 {
454 package Car;
455 use Moose;
456 }
457 {
458 package Breakable;
459 use Moose::Role;
460 has 'breakable_parts' => ( is => 'ro', required => 1 );
462 }
463 my $car = Car->new;
465 # next line dies with: Attribute (breakable_parts) is required
467 apply_all_roles( $car, 'Breakable' );
468 This will require passing the additional parameters at application time
470 as follows:
471 apply_all_roles( $car, 'Breakable' => {
473 rebless_params => {
474 # Parameters to 'Breakable'
475 breakable_parts => [qw( tires wheels windscreen )],
476 }
477 });
478 Obviously, this interface is better simplified as a method on "Car":
480 sub make_breakable {
482 my ( $self, %params ) = @_;
483 apply_all_roles($self, 'Breakable', { rebless_params => \%params });
484 }
485 my $car = Car->new();
487 $car->make_breakable( breakable_parts => [qw( tires wheels windscreen )] );
488
490 • Stevan Little <stevan@cpan.org>
491 • Dave Rolsky <autarch@urth.org>
493 • Jesse Luehrs <doy@cpan.org>
495 • Shawn M Moore <sartak@cpan.org>
497 • יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
499 • Karen Etheridge <ether@cpan.org>
501 • Florian Ragwitz <rafl@debian.org>
503 • Hans Dieter Pearcey <hdp@cpan.org>
505 • Chris Prather <chris@prather.org>
507 • Matt S Trout <mstrout@cpan.org>
509
511 This software is copyright (c) 2006 by Infinity Interactive, Inc.
512 This is free software; you can redistribute it and/or modify it under
514 the same terms as the Perl 5 programming language system itself.
515perl v5.36.0 2022-07-22 Moose::Manual::Roles(3)