-
-
07 Nov 2021 03:41:58 UTC
- Distribution: Moose
- Source (raw)
- Browse (raw)
- Changes
- Homepage
- How to Contribute
- Repository
- Issues (71)
- Testers (2841 / 3 / 1)
- Kwalitee
Bus factor: 3- 92.11% Coverage
- License: perl_5
- Perl: v5.8.3
- Activity
24 month- Tools
- Download (881.54KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
and 142 contributors-
Stevan Little
-
Dave Rolsky
-
Jesse Luehrs
-
Shawn M Moore
-
יובל קוג'מן (Yuval Kogman)
-
Florian Ragwitz
-
Hans Dieter Pearcey
-
Chris Prather
-
Matt S Trout
-
Upasana Shukla
-
Graham Knop
-
Tomas Doran
-
Ricardo Signes
-
Guillermo Roditi
-
John Napiorkowski
-
Aankhen
-
Todd Hepler
-
Jonathan Rockway
-
Gerda Shank
-
Perlover
-
Shlomi Fish
-
Brad Bowman
-
Justin Hunter
-
Kent Fredric
-
Paul Driver
-
Anders Nor Berle
-
Brian Manning
-
gfx
-
Jay Hannah
-
Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯
-
Leon Brocard
-
Olivier Mengué
-
Rafael Kitover
-
Christian Hansen
-
Cory Watson
-
Dagfinn Ilmari Mannsåker
-
Paul Jamieson Fenwick
-
Robert Buels
-
Dan Dascalescu
-
Marcel Grünauer
-
Scott McWhirter
-
Ævar Arnfjörð Bjarmason
-
Daisuke Maki (lestrrat)
-
Dylan William Hardison
-
Patrick Donelan
-
Stefan O'Rear
-
Tokuhiro Matsuno
-
Ash Berlin
-
Chris Weyl
-
Eric Wilhelm
-
Jess Robinson
-
Marc Mims
-
Marcus Ramberg
-
Mark Allen
-
Mateu X Hunter
-
matthof
-
Robert 'phaylon' Sedlacek
-
Zachary Lome
-
Aran Clary Deltac
-
Chip
-
Christopher J. Madsen
-
Curtis Jewell
-
Evan Carroll
-
Mark A. Stratman
-
Mark Fowler
-
Matthew Horsfall
-
mauke
-
Michael LaGrasta
-
Michael Rykov
-
Mike Whitaker
-
Moritz Onken
-
Nelo Onyiah
-
Nick Perez
-
Robert Boone
-
Robin V
-
rodrigolive
-
shelling
-
Thomas Sibley
-
Tom Hukins
-
Wallace Reis
-
Aaron Cohen
-
Adam J. Foxson
-
Adam Kennedy
-
Andy Jack
-
Anirvan Chatterjee
-
Ansgar Burchardt
-
A. Sinan Unur
-
Ben Hutton
-
Brendan Byrd
-
Chad Granum
-
Chankey Pathak
-
Chia-liang Kao
-
Christian Walde (Mithaldu)
-
chromatic
-
Dann
-
Dave Romano
-
David Leadbeater
-
David Steinbrunner
-
dmaestro
-
E. Choroba
-
franck cuny
-
Frew Schmidt
-
gregor herrmann
-
hakim
-
Henry Van Styn
-
James Marca
-
Jason May
-
Jay Allen
-
Jay Kuri
-
Jeff Bisbee
-
Jens Berthold
-
Jesse Vincent
-
joel
-
John Douglas Porter
-
John Goulah
-
Justin DeVuyst
-
Kang-min Liu
-
Leon Timmermans
-
Mark O Grady
-
Matt Kraai
-
Michael Schout
-
Nathan Gray
-
Olaf Alders
-
Olof Johansson
-
Paul Cochrane
-
Paweł Murias
-
Pedro Melo
-
Peter Shangov
-
Philippe Bruhat (BooK)
-
Philipp Gortan
-
Phillip Smith
-
Piotr Roszatycki
-
pktm
-
rouzier
-
Sam Vilain
-
sherrardb
-
Simon Reinhardt
-
sue spence
-
Tuomas Jormola
-
wickline
-
Yanick Champoux
-
Zoffix Znet
- Dependencies
- Carp
- Class::Load
- Class::Load::XS
- Data::OptList
- Devel::GlobalDestruction
- Devel::OverloadInfo
- Devel::StackTrace
- Dist::CheckConflicts
- Eval::Closure
- List::Util
- MRO::Compat
- Module::Runtime
- Module::Runtime::Conflicts
- Package::DeprecationManager
- Package::Stash
- Package::Stash::XS
- Params::Util
- Scalar::Util
- Sub::Exporter
- Sub::Util
- Try::Tiny
- parent
- strict
- warnings
- Reverse dependencies
- CPAN Testers List
- Dependency graph
- NAME
- VERSION
- WHAT IS A ROLE?
- A SIMPLE ROLE
- REQUIRED METHODS
- CONSUMING ROLES
- USING METHOD MODIFIERS
- METHOD CONFLICTS
- METHOD EXCLUSION AND ALIASING
- OVERLOADING
- ROLE EXCLUSION
- ADDING A ROLE TO AN OBJECT INSTANCE
- AUTHORS
- COPYRIGHT AND LICENSE
NAME
Moose::Manual::Roles - Roles, an alternative to deep hierarchies and base classes
VERSION
version 2.2201
WHAT IS A ROLE?
A role encapsulates some piece of behavior or state that can be shared between classes. It is something that classes do. It is important to understand that roles are not classes. You cannot inherit from a role, and a role cannot be instantiated. We sometimes say that roles are consumed, either by classes or other roles.
Instead, a role is composed into a class. In practical terms, this means that all of the methods, method modifiers, and attributes defined in a role are added directly to (we sometimes say "flattened into") the class that consumes the role. These attributes and methods then appear as if they were defined in the class itself. A subclass of the consuming class will inherit all of these methods and attributes.
Moose roles are similar to mixins or interfaces in other languages and are based on the original concept of Traits for the Smalltalk-80 dialect Squeak.
Besides defining their own methods and attributes, roles can also require that the consuming class define certain methods of its own. You could have a role that consisted only of a list of required methods, in which case the role would be very much like a Java interface.
Note that attribute accessors also count as methods for the purposes of satisfying the requirements of a role.
A SIMPLE ROLE
Creating a role looks a lot like creating a Moose class:
package Breakable; use Moose::Role; has 'is_broken' => ( is => 'rw', isa => 'Bool', ); sub break { my $self = shift; print "I broke\n"; $self->is_broken(1); }
Except for our use of Moose::Role, this looks just like a class definition with Moose. However, this is not a class, and it cannot be instantiated.
Instead, its attributes and methods will be composed into classes which use the role:
package Car; use Moose; with 'Breakable'; has 'engine' => ( is => 'ro', isa => 'Engine', );
The
with
function composes roles into a class. Once that is done, theCar
class has anis_broken
attribute and abreak
method. TheCar
class alsodoes('Breakable')
:my $car = Car->new( engine => Engine->new ); print $car->is_broken ? 'Busted' : 'Still working'; $car->break; print $car->is_broken ? 'Busted' : 'Still working'; $car->does('Breakable'); # true
This prints:
Still working I broke Busted
We could use this same role in a
Bone
class:package Bone; use Moose; with 'Breakable'; has 'marrow' => ( is => 'ro', isa => 'Marrow', );
See also Moose::Cookbook::Roles::Comparable_CodeReuse for an example.
It's possible to compose existing roles into new roles. For example, we can have a
HandleWithCare
class which applies both theBreakable
andPackage
roles to any class which consumes it:package HandleWithCare; use Moose::Role; with 'Breakable', 'Package';
REQUIRED METHODS
As mentioned previously, a role can require that consuming classes provide one or more methods. Using our
Breakable
example, let's make it require that consuming classes implement their ownbreak
methods:package Breakable; use Moose::Role; requires 'break'; has 'is_broken' => ( is => 'rw', isa => 'Bool', ); after 'break' => sub { my $self = shift; $self->is_broken(1); };
If we try to consume this role in a class that does not have a
break
method, we will get an exception.You can see that we added a method modifier on
break
. We want classes that consume this role to implement their own logic for breaking, but we make sure that theis_broken
attribute is always set to true whenbreak
is called.package Car use Moose; with 'Breakable'; has 'engine' => ( is => 'ro', isa => 'Engine', ); sub break { my $self = shift; if ( $self->is_moving ) { $self->stop; } }
Roles Versus Abstract Base Classes
If you are familiar with the concept of abstract base classes in other languages, you may be tempted to use roles in the same way.
You can define an "interface-only" role, one that contains just a list of required methods.
However, any class which consumes this role must implement all of the required methods, either directly or through inheritance from a parent. You cannot delay the method requirement check so that they can be implemented by future subclasses.
Because the role defines the required methods directly, adding a base class to the mix would not achieve anything. We recommend that you simply consume the interface role in each class which implements that interface.
CONSUMING ROLES
Roles are consumed using the
with
function.Most of the time, you should only use one
with
, even if you are consuming multiple roles. If you consume roles using multiplewith
statements Moose cannot detect method conflicts between those roles.Roles can be consumed by classes or by other roles. When a class consumes a role which in turn consumes other roles, the class gets all of the roles applied at once.
Required Methods Provided by Attributes
As mentioned before, a role's required method may also be satisfied by an attribute accessor. However, the call to
has
which defines an attribute happens at runtime. This means that you must define the attribute before consuming the role, or else the role will not see the generated accessor. These attributes are Moose Attributes.package Breakable; use Moose::Role; requires 'stress'; ######## package Car; use Moose; has 'stress' => ( is => 'ro', isa => 'Int', ); with 'Breakable';
In general, we recommend that you always consume roles after declaring all your attributes.
It may also be the case that a class wants to consume two roles where one role has an attribute providing a required method for another. For example:
package Breakable; use Moose::Role; requires 'stress'; ######## package Stressable; use Moose::Role; has 'stress' => ( is => 'ro', isa => 'Int', ); ######## package Car; use Moose; # XXX - this will not work with 'Breakable', 'Stressable';
However, this won't work. The problem is that the accessor methods created for the
stress
attribute won't be present in the class when the required method checks are done.There are two possible workarounds. The recommended one is to use "stub" subroutine(s) in the role providing the accessor(s):
package Stressable; use Moose::Role; sub stress; has 'stress' => ( is => 'ro', isa => 'Int', );
The
sub stress;
line is called a "forward" declaration in the Perl documentation. It creates what is called a "stub" subroutine, a declaration without a body. This is good enough to satisfy the required method checks done by Moose. The stub will not interfere with the creation of a real subroutine later.The other alternative is to use two separate calls to
with
in the consuming class:package Car; use Moose; # Not recommended with 'Stressable'; with 'Breakable';
Each
with
is run as it is seen. The first call will consume just theStressable
role, which will add thestress
attribute to theCar
package, which in turn will create an accessor method namedstress
. Then when theBreakable
role is consumed, the method it requires already exists.However, as mentioned earlier, multiple
with
declarations are not recommended, because method conflicts between the roles cannot be seen. In the example above, if bothStressable
andBreakable
contained methods of the same name, what would happen is that the version inStressable
would silently override the one inBreakable
.USING METHOD MODIFIERS
Method modifiers and roles are a very powerful combination. Often, a role will combine method modifiers and required methods. We already saw one example with our
Breakable
example.Method modifiers increase the complexity of roles, because they make the role application order relevant. If a class uses multiple roles, each of which modify the same method, those modifiers will be applied in the same order as the roles are used:
package MovieCar; use Moose; extends 'Car'; with 'Breakable', 'ExplodesOnBreakage';
Assuming that the new
ExplodesOnBreakage
role also has anafter
modifier onbreak
, theafter
modifiers will run one after the other. The modifier fromBreakable
will run first, then the one fromExplodesOnBreakage
.METHOD CONFLICTS
If a class composes multiple roles, and those roles have methods of the same name, we will have a conflict. In that case, the composing class is required to provide its own method of the same name.
package Breakdancer; use Moose::Role; sub break { }
If we compose both
Breakable
andBreakdancer
in a class, we must provide our ownbreak
method:package FragileDancer; use Moose; with 'Breakable', 'Breakdancer'; sub break { ... }
A role can be a collection of other roles:
package Break::Bundle; use Moose::Role; with ('Breakable', 'Breakdancer');
When a role consumes another a role, the consuming role's methods silently win in any conflict, and the consumed role's methods are simply ignored.
METHOD EXCLUSION AND ALIASING
If we want our
FragileDancer
class to be able to call the methods from both its roles, we can alias the methods:package FragileDancer; use Moose; with 'Breakable' => { -alias => { break => 'break_bone' } }, 'Breakdancer' => { -alias => { break => 'break_dance' } };
However, aliasing a method simply makes a copy of the method with the new name. We also need to exclude the original name:
with 'Breakable' => { -alias => { break => 'break_bone' }, -excludes => 'break', }, 'Breakdancer' => { -alias => { break => 'break_dance' }, -excludes => 'break', };
The excludes parameter prevents the
break
method from being composed into theFragileDancer
class, so we don't have a conflict. This means thatFragileDancer
does not need to implement its ownbreak
method.This is useful, but it's worth noting that this breaks the contract implicit in consuming a role. Our
FragileDancer
class does both theBreakable
andBreakDancer
, but does not provide abreak
method. If some API expects an object that does one of those roles, it probably expects it to implement that method.In some use cases we might alias and exclude methods from roles, but then provide a method of the same name in the class itself.
Also see Moose::Cookbook::Roles::Restartable_AdvancedComposition for an example.
OVERLOADING
When a Moose role uses overloading, that overloading is composed into any classes that consume the role. This includes the setting of the
fallback
value for that role's overloading. Just as with methods and attributes, when a role consumes another role, that other role's overloading settings are applied to the role.Just as with methods, there can be conflicts with overloading implementations between multiple roles when they are all consumed by a class. If two roles both provide different overloading implementations for a given operator, that is a conflict. If two roles both implement overloading and have different
fallback
values, that is also considered a conflict. These conflicts are detected when multiple roles are being composed into a class together.When a role consumes another role, the consuming role's overloading fallback and operator implementations silently "win" the conflict.
ROLE EXCLUSION
A role can say that it cannot be combined with some other role. This should be used with great caution, since it limits the re-usability of the role.
package Breakable; use Moose::Role; excludes 'BreakDancer';
ADDING A ROLE TO AN OBJECT INSTANCE
You may want to add a role to an object instance, rather than to a class. For example, you may want to add debug tracing to one instance of an object while debugging a particular bug. Another use case might be to dynamically change objects based on a user's configuration, as a plugin system.
The best way to do this is to use the
apply_all_roles()
function from Moose::Util:use Moose::Util qw( apply_all_roles ); my $car = Car->new; apply_all_roles( $car, 'Breakable' );
This function can apply more than one role at a time, and will do so using the normal Moose role combination system. We recommend using this function to apply roles to an object. This is what Moose uses internally when you call
with
.Handling required attributes for roles.
Application of some roles will require additional parameters being specified to satisfy them, for example:
{ package Car; use Moose; } { package Breakable; use Moose::Role; has 'breakable_parts' => ( is => 'ro', required => 1 ); } my $car = Car->new; # next line dies with: Attribute (breakable_parts) is required apply_all_roles( $car, 'Breakable' );
This will require passing the additional parameters at application time as follows:
apply_all_roles( $car, 'Breakable' => { rebless_params => { # Parameters to 'Breakable' breakable_parts => [qw( tires wheels windscreen )], } });
Obviously, this interface is better simplified as a method on
Car
:sub make_breakable { my ( $self, %params ) = @_; apply_all_roles($self, 'Breakable', { rebless_params => \%params }); } my $car = Car->new(); $car->make_breakable( breakable_parts => [qw( tires wheels windscreen )] );
AUTHORS
Stevan Little <stevan@cpan.org>
Dave Rolsky <autarch@urth.org>
Jesse Luehrs <doy@cpan.org>
Shawn M Moore <sartak@cpan.org>
יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
Karen Etheridge <ether@cpan.org>
Florian Ragwitz <rafl@debian.org>
Hans Dieter Pearcey <hdp@cpan.org>
Chris Prather <chris@prather.org>
Matt S Trout <mstrout@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2006 by Infinity Interactive, Inc.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
Module Install Instructions
To install Moose, copy and paste the appropriate command in to your terminal.
cpanm Moose
perl -MCPAN -e shell install Moose
For more information on module installation, please visit the detailed CPAN module installation guide.