.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Moose::Manual::Roles 3"
.TH Moose::Manual::Roles 3 "2012-05-07" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Moose::Manual::Roles \- Roles, an alternative to deep hierarchies and base classes
.SH "VERSION"
.IX Header "VERSION"
version 2.0602
.SH "WHAT IS A ROLE?"
.IX Header "WHAT IS A ROLE?"
A role encapsulates some piece of behavior or state that can be shared between
classes. It is something that classes \fIdo\fR. It is important to understand that
\&\fIroles are not classes\fR. You cannot inherit from a role, and a role cannot be
instantiated. We sometimes say that roles are \fIconsumed\fR, either by classes
or other roles.
.PP
Instead, a role is \fIcomposed\fR 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 \*(L"flattened into\*(R") 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.
.PP
Moose roles are similar to mixins or interfaces in other languages.
.PP
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.
.PP
Note that attribute accessors also count as methods for the
purposes of satisfying the requirements of a role.
.SH "A SIMPLE ROLE"
.IX Header "A SIMPLE ROLE"
Creating a role looks a lot like creating a Moose class:
.PP
.Vb 1
\& package Breakable;
\&
\& use Moose::Role;
\&
\& has \*(Aqis_broken\*(Aq => (
\& is => \*(Aqrw\*(Aq,
\& isa => \*(AqBool\*(Aq,
\& );
\&
\& sub break {
\& my $self = shift;
\&
\& print "I broke\en";
\&
\& $self\->is_broken(1);
\& }
.Ve
.PP
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.
.PP
Instead, its attributes and methods will be composed into classes
which use the role:
.PP
.Vb 1
\& package Car;
\&
\& use Moose;
\&
\& with \*(AqBreakable\*(Aq;
\&
\& has \*(Aqengine\*(Aq => (
\& is => \*(Aqro\*(Aq,
\& isa => \*(AqEngine\*(Aq,
\& );
.Ve
.PP
The \f(CW\*(C`with\*(C'\fR function composes roles into a class. Once that is done,
the \f(CW\*(C`Car\*(C'\fR class has an \f(CW\*(C`is_broken\*(C'\fR attribute and a \f(CW\*(C`break\*(C'\fR
method. The \f(CW\*(C`Car\*(C'\fR class also \f(CW\*(C`does(\*(AqBreakable\*(Aq)\*(C'\fR:
.PP
.Vb 1
\& my $car = Car\->new( engine => Engine\->new );
\&
\& print $car\->is_broken ? \*(AqBusted\*(Aq : \*(AqStill working\*(Aq;
\& $car\->break;
\& print $car\->is_broken ? \*(AqBusted\*(Aq : \*(AqStill working\*(Aq;
\&
\& $car\->does(\*(AqBreakable\*(Aq); # true
.Ve
.PP
This prints:
.PP
.Vb 3
\& Still working
\& I broke
\& Busted
.Ve
.PP
We could use this same role in a \f(CW\*(C`Bone\*(C'\fR class:
.PP
.Vb 1
\& package Bone;
\&
\& use Moose;
\&
\& with \*(AqBreakable\*(Aq;
\&
\& has \*(Aqmarrow\*(Aq => (
\& is => \*(Aqro\*(Aq,
\& isa => \*(AqMarrow\*(Aq,
\& );
.Ve
.PP
See also Moose::Cookbook::Roles::Comparable_CodeReuse for an example.
.SH "REQUIRED METHODS"
.IX Header "REQUIRED METHODS"
As mentioned previously, a role can require that consuming classes
provide one or more methods. Using our \f(CW\*(C`Breakable\*(C'\fR example, let's
make it require that consuming classes implement their own \f(CW\*(C`break\*(C'\fR
methods:
.PP
.Vb 1
\& package Breakable;
\&
\& use Moose::Role;
\&
\& requires \*(Aqbreak\*(Aq;
\&
\& has \*(Aqis_broken\*(Aq => (
\& is => \*(Aqrw\*(Aq,
\& isa => \*(AqBool\*(Aq,
\& );
\&
\& after \*(Aqbreak\*(Aq => sub {
\& my $self = shift;
\&
\& $self\->is_broken(1);
\& };
.Ve
.PP
If we try to consume this role in a class that does not have a
\&\f(CW\*(C`break\*(C'\fR method, we will get an exception.
.PP
You can see that we added a method modifier on \f(CW\*(C`break\*(C'\fR. We want
classes that consume this role to implement their own logic for
breaking, but we make sure that the \f(CW\*(C`is_broken\*(C'\fR attribute is always
set to true when \f(CW\*(C`break\*(C'\fR is called.
.PP
.Vb 1
\& package Car
\&
\& use Moose;
\&
\& with \*(AqBreakable\*(Aq;
\&
\& has \*(Aqengine\*(Aq => (
\& is => \*(Aqro\*(Aq,
\& isa => \*(AqEngine\*(Aq,
\& );
\&
\& sub break {
\& my $self = shift;
\&
\& if ( $self\->is_moving ) {
\& $self\->stop;
\& }
\& }
.Ve
.SS "Roles Versus Abstract Base Classes"
.IX Subsection "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.
.PP
You \fIcan\fR define an \*(L"interface-only\*(R" role, one that contains \fIjust\fR
a list of required methods.
.PP
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.
.PP
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.
.SS "Required Attributes"
.IX Subsection "Required Attributes"
As mentioned before, a role's required method may also be satisfied by an
attribute accessor. However, the call to \f(CW\*(C`has\*(C'\fR which defines an attribute
happens at runtime. This means that you must define the attribute \fIbefore\fR
consuming the role, or else the role will not see the generated accessor.
.PP
.Vb 1
\& package Breakable;
\&
\& use Moose::Role;
\&
\& requires \*(Aqstress\*(Aq;
\&
\& package Car;
\&
\& use Moose;
\&
\& has \*(Aqstress\*(Aq => (
\& is => \*(Aqrw\*(Aq,
\& isa => \*(AqInt\*(Aq,
\& );
\&
\& with \*(AqBreakable\*(Aq;
.Ve
.SH "USING METHOD MODIFIERS"
.IX Header "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 \f(CW\*(C`Breakable\*(C'\fR example.
.PP
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:
.PP
.Vb 1
\& package MovieCar;
\&
\& use Moose;
\&
\& extends \*(AqCar\*(Aq;
\&
\& with \*(AqBreakable\*(Aq, \*(AqExplodesOnBreakage\*(Aq;
.Ve
.PP
Assuming that the new \f(CW\*(C`ExplodesOnBreakage\*(C'\fR role \fIalso\fR has an
\&\f(CW\*(C`after\*(C'\fR modifier on \f(CW\*(C`break\*(C'\fR, the \f(CW\*(C`after\*(C'\fR modifiers will run one
after the other. The modifier from \f(CW\*(C`Breakable\*(C'\fR will run first, then
the one from \f(CW\*(C`ExplodesOnBreakage\*(C'\fR.
.SH "METHOD CONFLICTS"
.IX Header "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 \fIown\fR method of the same name.
.PP
.Vb 1
\& package Breakdancer;
\&
\& use Moose::Role
\&
\& sub break {
\&
\& }
.Ve
.PP
If we compose both \f(CW\*(C`Breakable\*(C'\fR and \f(CW\*(C`Breakdancer\*(C'\fR in a class, we must
provide our own \f(CW\*(C`break\*(C'\fR method:
.PP
.Vb 1
\& package FragileDancer;
\&
\& use Moose;
\&
\& with \*(AqBreakable\*(Aq, \*(AqBreakdancer\*(Aq;
\&
\& sub break { ... }
.Ve
.PP
A role can be a collection of other roles:
.PP
.Vb 1
\& package Break::Bundle;
\&
\& use Moose::Role;
\&
\& with (\*(AqBreakable\*(Aq, \*(AqBreakdancer\*(Aq);
.Ve
.SH "METHOD EXCLUSION AND ALIASING"
.IX Header "METHOD EXCLUSION AND ALIASING"
If we want our \f(CW\*(C`FragileDancer\*(C'\fR class to be able to call the methods
from both its roles, we can alias the methods:
.PP
.Vb 1
\& package FragileDancer;
\&
\& use Moose;
\&
\& with \*(AqBreakable\*(Aq => { \-alias => { break => \*(Aqbreak_bone\*(Aq } },
\& \*(AqBreakdancer\*(Aq => { \-alias => { break => \*(Aqbreak_dance\*(Aq } };
.Ve
.PP
However, aliasing a method simply makes a \fIcopy\fR of the method with
the new name. We also need to exclude the original name:
.PP
.Vb 8
\& with \*(AqBreakable\*(Aq => {
\& \-alias => { break => \*(Aqbreak_bone\*(Aq },
\& \-excludes => \*(Aqbreak\*(Aq,
\& },
\& \*(AqBreakdancer\*(Aq => {
\& \-alias => { break => \*(Aqbreak_dance\*(Aq },
\& \-excludes => \*(Aqbreak\*(Aq,
\& };
.Ve
.PP
The excludes parameter prevents the \f(CW\*(C`break\*(C'\fR method from being composed
into the \f(CW\*(C`FragileDancer\*(C'\fR class, so we don't have a conflict. This
means that \f(CW\*(C`FragileDancer\*(C'\fR does not need to implement its own
\&\f(CW\*(C`break\*(C'\fR method.
.PP
This is useful, but it's worth noting that this breaks the contract
implicit in consuming a role. Our \f(CW\*(C`FragileDancer\*(C'\fR class does both the
\&\f(CW\*(C`Breakable\*(C'\fR and \f(CW\*(C`BreakDancer\*(C'\fR, but does not provide a \f(CW\*(C`break\*(C'\fR
method. If some \s-1API\s0 expects an object that does one of those roles, it
probably expects it to implement that method.
.PP
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.
.PP
Also see Moose::Cookbook::Roles::Restartable_AdvancedComposition for an example.
.SH "ROLE EXCLUSION"
.IX Header "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.
.PP
.Vb 1
\& package Breakable;
\&
\& use Moose::Role;
\&
\& excludes \*(AqBreakDancer\*(Aq;
.Ve
.SH "ADDING A ROLE TO AN OBJECT INSTANCE"
.IX Header "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.
.PP
The best way to do this is to use the \f(CW\*(C`apply_all_roles()\*(C'\fR function from
Moose::Util:
.PP
.Vb 1
\& use Moose::Util qw( apply_all_roles );
\&
\& my $car = Car\->new;
\& apply_all_roles( $car, \*(AqBreakable\*(Aq );
.Ve
.PP
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
\&\f(CW\*(C`with\*(C'\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Moose is maintained by the Moose Cabal, along with the help of many contributors. See \*(L"\s-1CABAL\s0\*(R" in Moose and \*(L"\s-1CONTRIBUTORS\s0\*(R" in Moose for details.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2012 by Infinity Interactive, Inc..
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.