.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Moose::Role 3"
.TH Moose::Role 3 "2021-11-07" "perl v5.26.3" "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::Role \- The Moose Role
.SH "VERSION"
.IX Header "VERSION"
version 2.2201
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  package Eq;
\&  use Moose::Role; # automatically turns on strict and warnings
\&
\&  requires \*(Aqequal\*(Aq;
\&
\&  sub no_equal {
\&      my ($self, $other) = @_;
\&      !$self\->equal($other);
\&  }
\&
\&  # ... then in your classes
\&
\&  package Currency;
\&  use Moose; # automatically turns on strict and warnings
\&
\&  with \*(AqEq\*(Aq;
\&
\&  sub equal {
\&      my ($self, $other) = @_;
\&      $self\->as_float == $other\->as_float;
\&  }
\&
\&  # ... and also
\&
\&  package Comparator;
\&  use Moose;
\&
\&  has compare_to => (
\&      is      => \*(Aqro\*(Aq,
\&      does    => \*(AqEq\*(Aq,
\&      handles => \*(AqEq\*(Aq,
\&  );
\&
\&  # ... which allows
\&
\&  my $currency1 = Currency\->new(...);
\&  my $currency2 = Currency\->new(...);
\&  Comparator\->new(compare_to => $currency1)\->equal($currency2);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The concept of roles is documented in Moose::Manual::Roles. This document
serves as \s-1API\s0 documentation.
.SH "EXPORTED FUNCTIONS"
.IX Header "EXPORTED FUNCTIONS"
Moose::Role currently supports all of the functions that Moose exports, but
differs slightly in how some items are handled (see \*(L"\s-1CAVEATS\*(R"\s0 below for
details).
.PP
Moose::Role also offers two role-specific keyword exports:
.SS "requires (@method_names)"
.IX Subsection "requires (@method_names)"
Roles can require that certain methods are implemented by any class which
\&\f(CW\*(C`does\*(C'\fR the role.
.PP
Note that attribute accessors also count as methods for the purposes
of satisfying the requirements of a role.
.SS "excludes (@role_names)"
.IX Subsection "excludes (@role_names)"
Roles can \f(CW\*(C`exclude\*(C'\fR other roles, in effect saying "I can never be combined
with these \f(CW@role_names\fR". This is a feature which should not be used
lightly.
.SS "no Moose::Role"
.IX Subsection "no Moose::Role"
Moose::Role offers a way to remove the keywords it exports, through the
\&\f(CW\*(C`unimport\*(C'\fR method. You simply have to say \f(CW\*(C`no Moose::Role\*(C'\fR at the bottom of
your code for this to work.
.SH "METACLASS"
.IX Header "METACLASS"
When you use Moose::Role, you can specify traits which will be applied to your
role metaclass:
.PP
.Vb 1
\&    use Moose::Role \-traits => \*(AqMy::Trait\*(Aq;
.Ve
.PP
This is very similar to the attribute traits feature. When you do
this, your class's \f(CW\*(C`meta\*(C'\fR object will have the specified traits
applied to it. See \*(L"Metaclass and Trait Name Resolution\*(R" in Moose for more
details.
.PP
All role metaclasses (note, not the role itself) extend Moose::Meta::Role.
You can test if a package is a role or not using \*(L"is_role\*(R" in Moose::Util.
.SH "APPLYING ROLES"
.IX Header "APPLYING ROLES"
In addition to being applied to a class using the 'with' syntax (see
Moose::Manual::Roles) and using the Moose::Util 'apply_all_roles'
method, roles may also be applied to an instance of a class using
Moose::Util 'apply_all_roles' or the role's metaclass:
.PP
.Vb 1
\&   MyApp::Test::SomeRole\->meta\->apply( $instance );
.Ve
.PP
Doing this creates a new, mutable, anonymous subclass, applies the role to that,
and reblesses. In a debugger, for example, you will see class names of the
form \f(CW\*(C` Moose::Meta::Class::_\|_ANON_\|_::SERIAL::6 \*(C'\fR, which means that doing a
\&'ref' on your instance may not return what you expect. See Moose::Object for
\&'\s-1DOES\s0'.
.PP
Additional params may be added to the new instance by providing
\&'rebless_params'. See Moose::Meta::Role::Application::ToInstance.
.SH "CAVEATS"
.IX Header "CAVEATS"
Role support has only a few caveats:
.IP "\(bu" 4
Roles cannot use the \f(CW\*(C`extends\*(C'\fR keyword; it will throw an exception for now.
The same is true of the \f(CW\*(C`augment\*(C'\fR and \f(CW\*(C`inner\*(C'\fR keywords (not sure those
really make sense for roles). All other Moose keywords will be \fIdeferred\fR
so that they can be applied to the consuming class.
.IP "\(bu" 4
Role composition does its best to \fBnot\fR be order-sensitive when it comes to
conflict resolution and requirements detection. However, it is order-sensitive
when it comes to method modifiers. All before/around/after modifiers are
included whenever a role is composed into a class, and then applied in the order
in which the roles are used. This also means that there is no conflict for
before/around/after modifiers.
.Sp
In most cases, this will be a non-issue; however, it is something to keep in
mind when using method modifiers in a role. You should never assume any
ordering.
.SH "BUGS"
.IX Header "BUGS"
See \*(L"\s-1BUGS\*(R"\s0 in Moose for details on reporting bugs.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Stevan Little <stevan@cpan.org>
.IP "\(bu" 4
Dave Rolsky <autarch@urth.org>
.IP "\(bu" 4
Jesse Luehrs <doy@cpan.org>
.IP "\(bu" 4
Shawn M Moore <sartak@cpan.org>
.IP "\(bu" 4
יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
.IP "\(bu" 4
Karen Etheridge <ether@cpan.org>
.IP "\(bu" 4
Florian Ragwitz <rafl@debian.org>
.IP "\(bu" 4
Hans Dieter Pearcey <hdp@cpan.org>
.IP "\(bu" 4
Chris Prather <chris@prather.org>
.IP "\(bu" 4
Matt S Trout <mstrout@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2006 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.