.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 "Mouse::Role 3pm"
.TH Mouse::Role 3pm 2024-01-11 "perl v5.38.2" "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
Mouse::Role \- The Mouse Role
.SH VERSION
.IX Header "VERSION"
This document describes Mouse version v2.5.10
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&    package Comparable;
\&    use Mouse::Role; # the package is now a Mouse role
\&
\&    # Declare methods that are required by this role
\&    requires qw(compare);
\&
\&    # Define methods this role provides
\&    sub equals {
\&        my($self, $other) = @_;
\&        return $self\->compare($other) == 0;
\&    }
\&
\&    # and later
\&    package MyObject;
\&    use Mouse;
\&    with qw(Comparable); # Now MyObject can equals()
\&
\&    sub compare {
\&        # ...
\&    }
\&
\&    my $foo = MyObject\->new();
\&    my $bar = MyObject\->new();
\&    $obj\->equals($bar); # yes, it is comparable
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module declares the caller class to be a Mouse role.
.PP
The concept of roles is documented in Moose::Manual::Roles.
This document serves as API documentation.
.SH "EXPORTED FUNCTIONS"
.IX Header "EXPORTED FUNCTIONS"
Mouse::Role supports all of the functions that Mouse exports, but
differs slightly in how some items are handled (see "CAVEATS" below
for details).
.PP
Mouse::Role also offers two role-specific keywords:
.ie n .SS requires(@method_names)
.el .SS \f(CWrequires(@method_names)\fP
.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.
.ie n .SS excludes(@role_names)
.el .SS \f(CWexcludes(@role_names)\fP
.IX Subsection "excludes(@role_names)"
This is exported but not implemented in Mouse.
.SH "IMPORT AND UNIMPORT"
.IX Header "IMPORT AND UNIMPORT"
.SS import
.IX Subsection "import"
Importing Mouse::Role will give you sugar. \f(CW\*(C`\-traits\*(C'\fR are also supported.
.SS unimport
.IX Subsection "unimport"
Please unimport (\f(CW\*(C`no Mouse::Role\*(C'\fR) so that if someone calls one of the
keywords (such as "has") it will break loudly instead breaking subtly.
.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 Mouse 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 "SEE ALSO"
.IX Header "SEE ALSO"
Mouse
.PP
Moose::Role
.PP
Moose::Manual::Roles
.PP
Moose::Spec::Role