.\" -*- 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 "Moose::Meta::Role 3pm"
.TH Moose::Meta::Role 3pm 2024-01-21 "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
Moose::Meta::Role \- The Moose Role metaclass
.SH VERSION
.IX Header "VERSION"
version 2.2207
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This class is a subclass of Class::MOP::Module that provides
additional Moose-specific functionality.
.PP
Its API looks a lot like Moose::Meta::Class, but internally it
implements many things differently. This may change in the future.
.SH INHERITANCE
.IX Header "INHERITANCE"
\&\f(CW\*(C`Moose::Meta::Role\*(C'\fR is a subclass of Class::MOP::Module.
.SH METHODS
.IX Header "METHODS"
.SS Construction
.IX Subsection "Construction"
\fIMoose::Meta::Role\->initialize($role_name)\fR
.IX Subsection "Moose::Meta::Role->initialize($role_name)"
.PP
This method creates a new role object with the provided name.
.PP
\fIMoose::Meta::Role\->combine( [ \fR\f(CI$role\fR\fI => { ... } ], [ \fR\f(CI$role\fR\fI ], ... )\fR
.IX Subsection "Moose::Meta::Role->combine( [ $role => { ... } ], [ $role ], ... )"
.PP
This method accepts a list of array references. Each array reference
should contain a role name or Moose::Meta::Role object as its first element. The second element is
an optional hash reference. The hash reference can contain \f(CW\*(C`\-excludes\*(C'\fR
and \f(CW\*(C`\-alias\*(C'\fR keys to control how methods are composed from the role.
.PP
The return value is a new Moose::Meta::Role::Composite that
represents the combined roles.
.PP
\fR\f(CI$metarole\fR\fI\->composition_class_roles\fR
.IX Subsection "$metarole->composition_class_roles"
.PP
When combining multiple roles using \f(CW\*(C`combine\*(C'\fR, this method is used to obtain a
list of role names to be applied to the Moose::Meta::Role::Composite
instance returned by \f(CW\*(C`combine\*(C'\fR. The default implementation returns an empty
list. Extensions that need to hook into role combination may wrap this method
to return additional role names.
.PP
\fIMoose::Meta::Role\->create($name, \fR\f(CI%options\fR\fI)\fR
.IX Subsection "Moose::Meta::Role->create($name, %options)"
.PP
This method is identical to the Moose::Meta::Class \f(CW\*(C`create\*(C'\fR
method.
.PP
\fIMoose::Meta::Role\->create_anon_role\fR
.IX Subsection "Moose::Meta::Role->create_anon_role"
.PP
This method is identical to the Moose::Meta::Class
\&\f(CW\*(C`create_anon_class\*(C'\fR method.
.PP
\fR\f(CI$metarole\fR\fI\->is_anon_role\fR
.IX Subsection "$metarole->is_anon_role"
.PP
Returns true if the role is an anonymous role.
.PP
\fR\f(CI$metarole\fR\fI\->consumers\fR
.IX Subsection "$metarole->consumers"
.PP
Returns a list of names of classes and roles which consume this role.
.SS "Role application"
.IX Subsection "Role application"
\fR\f(CI$metarole\fR\fI\->apply( \fR\f(CI$thing\fR\fI, \fR\f(CI@options\fR\fI )\fR
.IX Subsection "$metarole->apply( $thing, @options )"
.PP
This method applies a role to the given \f(CW$thing\fR. That can be another
Moose::Meta::Role, object, a Moose::Meta::Class object, or a
(non-meta) object instance.
.PP
The options are passed directly to the constructor for the appropriate
Moose::Meta::Role::Application subclass.
.PP
Note that this will apply the role even if the \f(CW$thing\fR in question already
\&\f(CW\*(C`does\*(C'\fR this role.  "does_role" in Moose::Util is a convenient wrapper for
finding out if role application is necessary.
.SS "Roles and other roles"
.IX Subsection "Roles and other roles"
\fR\f(CI$metarole\fR\fI\->get_roles\fR
.IX Subsection "$metarole->get_roles"
.PP
This returns an array reference of roles which this role does. This
list may include duplicates.
.PP
\fR\f(CI$metarole\fR\fI\->calculate_all_roles\fR
.IX Subsection "$metarole->calculate_all_roles"
.PP
This returns a \fIunique\fR list of all roles that this role does, and
all the roles that its roles do.
.PP
\fR\f(CI$metarole\fR\fI\->does_role($role)\fR
.IX Subsection "$metarole->does_role($role)"
.PP
Given a role \fIname\fR or Moose::Meta::Role object, returns true if this role
does the given role.
.PP
\fR\f(CI$metarole\fR\fI\->add_role($role)\fR
.IX Subsection "$metarole->add_role($role)"
.PP
Given a Moose::Meta::Role object, this adds the role to the list of
roles that the role does.
.PP
\fR\f(CI$metarole\fR\fI\->get_excluded_roles_list\fR
.IX Subsection "$metarole->get_excluded_roles_list"
.PP
Returns a list of role names which this role excludes.
.PP
\fR\f(CI$metarole\fR\fI\->excludes_role($role_name)\fR
.IX Subsection "$metarole->excludes_role($role_name)"
.PP
Given a role \fIname\fR, returns true if this role excludes the named
role.
.PP
\fR\f(CI$metarole\fR\fI\->add_excluded_roles(@role_names)\fR
.IX Subsection "$metarole->add_excluded_roles(@role_names)"
.PP
Given one or more role names, adds those roles to the list of excluded
roles.
.SS Methods
.IX Subsection "Methods"
The methods for dealing with a role's methods are all identical in API
and behavior to the same methods in Class::MOP::Class.
.PP
\fR\f(CI$metarole\fR\fI\->method_metaclass\fR
.IX Subsection "$metarole->method_metaclass"
.PP
Returns the method metaclass name for the role. This defaults to
Moose::Meta::Role::Method.
.PP
\fR\f(CI$metarole\fR\fI\->get_method($name)\fR
.IX Subsection "$metarole->get_method($name)"
.PP
\fR\f(CI$metarole\fR\fI\->has_method($name)\fR
.IX Subsection "$metarole->has_method($name)"
.PP
\fR\f(CI$metarole\fR\fI\->add_method( \fR\f(CI$name\fR\fI, \fR\f(CI$body\fR\fI )\fR
.IX Subsection "$metarole->add_method( $name, $body )"
.PP
\fR\f(CI$metarole\fR\fI\->get_method_list\fR
.IX Subsection "$metarole->get_method_list"
.PP
\fR\f(CI$metarole\fR\fI\->find_method_by_name($name)\fR
.IX Subsection "$metarole->find_method_by_name($name)"
.PP
These methods are all identical to the methods of the same name in
Class::MOP::Class
.SS Attributes
.IX Subsection "Attributes"
As with methods, the methods for dealing with a role's attribute are
all identical in API and behavior to the same methods in
Class::MOP::Class.
.PP
However, attributes stored in this class are \fInot\fR stored as
objects. Rather, the attribute definition is stored as a hash
reference. When a role is composed into a class, this hash reference
is passed directly to the metaclass's \f(CW\*(C`add_attribute\*(C'\fR method.
.PP
This is quite likely to change in the future.
.PP
\fR\f(CI$metarole\fR\fI\->get_attribute($attribute_name)\fR
.IX Subsection "$metarole->get_attribute($attribute_name)"
.PP
\fR\f(CI$metarole\fR\fI\->has_attribute($attribute_name)\fR
.IX Subsection "$metarole->has_attribute($attribute_name)"
.PP
\fR\f(CI$metarole\fR\fI\->get_attribute_list\fR
.IX Subsection "$metarole->get_attribute_list"
.PP
\fR\f(CI$metarole\fR\fI\->add_attribute($name, \fR\f(CI%options\fR\fI)\fR
.IX Subsection "$metarole->add_attribute($name, %options)"
.PP
\fR\f(CI$metarole\fR\fI\->remove_attribute($attribute_name)\fR
.IX Subsection "$metarole->remove_attribute($attribute_name)"
.SS "Overload introspection and creation"
.IX Subsection "Overload introspection and creation"
The methods for dealing with a role's overloads are all identical in API and
behavior to the same methods in Class::MOP::Class.
.PP
\fR\f(CI$metarole\fR\fI\->is_overloaded\fR
.IX Subsection "$metarole->is_overloaded"
.PP
\fR\f(CI$metarole\fR\fI\->get_overloaded_operator($op)\fR
.IX Subsection "$metarole->get_overloaded_operator($op)"
.PP
\fR\f(CI$metarole\fR\fI\->has_overloaded_operator($op)\fR
.IX Subsection "$metarole->has_overloaded_operator($op)"
.PP
\fR\f(CI$metarole\fR\fI\->get_overload_list\fR
.IX Subsection "$metarole->get_overload_list"
.PP
\fR\f(CI$metarole\fR\fI\->get_all_overloaded_operators\fR
.IX Subsection "$metarole->get_all_overloaded_operators"
.PP
\fR\f(CI$metarole\fR\fI\->add_overloaded_operator($op, \fR\f(CI$impl\fR\fI)\fR
.IX Subsection "$metarole->add_overloaded_operator($op, $impl)"
.PP
\fR\f(CI$metarole\fR\fI\->remove_overloaded_operator($op)\fR
.IX Subsection "$metarole->remove_overloaded_operator($op)"
.SS "Required methods"
.IX Subsection "Required methods"
\fR\f(CI$metarole\fR\fI\->get_required_method_list\fR
.IX Subsection "$metarole->get_required_method_list"
.PP
Returns the list of methods required by the role.
.PP
\fR\f(CI$metarole\fR\fI\->requires_method($name)\fR
.IX Subsection "$metarole->requires_method($name)"
.PP
Returns true if the role requires the named method.
.PP
\fR\f(CI$metarole\fR\fI\->add_required_methods(@names)\fR
.IX Subsection "$metarole->add_required_methods(@names)"
.PP
Adds the named methods to the role's list of required methods.
.PP
\fR\f(CI$metarole\fR\fI\->remove_required_methods(@names)\fR
.IX Subsection "$metarole->remove_required_methods(@names)"
.PP
Removes the named methods from the role's list of required methods.
.PP
\fR\f(CI$metarole\fR\fI\->add_conflicting_method(%params)\fR
.IX Subsection "$metarole->add_conflicting_method(%params)"
.PP
Instantiate the parameters as a Moose::Meta::Role::Method::Conflicting
object, then add it to the required method list.
.SS "Method modifiers"
.IX Subsection "Method modifiers"
These methods act like their counterparts in Class::MOP::Class and
Moose::Meta::Class.
.PP
However, method modifiers are simply stored internally, and are not applied
until the role itself is applied to a class or object.
.PP
\fR\f(CI$metarole\fR\fI\->add_after_method_modifier($method_name, \fR\f(CI$method\fR\fI)\fR
.IX Subsection "$metarole->add_after_method_modifier($method_name, $method)"
.PP
\fR\f(CI$metarole\fR\fI\->add_around_method_modifier($method_name, \fR\f(CI$method\fR\fI)\fR
.IX Subsection "$metarole->add_around_method_modifier($method_name, $method)"
.PP
\fR\f(CI$metarole\fR\fI\->add_before_method_modifier($method_name, \fR\f(CI$method\fR\fI)\fR
.IX Subsection "$metarole->add_before_method_modifier($method_name, $method)"
.PP
\fR\f(CI$metarole\fR\fI\->add_override_method_modifier($method_name, \fR\f(CI$method\fR\fI)\fR
.IX Subsection "$metarole->add_override_method_modifier($method_name, $method)"
.PP
These methods all add an appropriate modifier to the internal list of
modifiers.
.PP
\fR\f(CI$metarole\fR\fI\->has_after_method_modifiers\fR
.IX Subsection "$metarole->has_after_method_modifiers"
.PP
\fR\f(CI$metarole\fR\fI\->has_around_method_modifiers\fR
.IX Subsection "$metarole->has_around_method_modifiers"
.PP
\fR\f(CI$metarole\fR\fI\->has_before_method_modifiers\fR
.IX Subsection "$metarole->has_before_method_modifiers"
.PP
\fR\f(CI$metarole\fR\fI\->has_override_method_modifier\fR
.IX Subsection "$metarole->has_override_method_modifier"
.PP
Return true if the role has any modifiers of the given type.
.PP
\fR\f(CI$metarole\fR\fI\->get_after_method_modifiers($method_name)\fR
.IX Subsection "$metarole->get_after_method_modifiers($method_name)"
.PP
\fR\f(CI$metarole\fR\fI\->get_around_method_modifiers($method_name)\fR
.IX Subsection "$metarole->get_around_method_modifiers($method_name)"
.PP
\fR\f(CI$metarole\fR\fI\->get_before_method_modifiers($method_name)\fR
.IX Subsection "$metarole->get_before_method_modifiers($method_name)"
.PP
Given a method name, returns a list of the appropriate modifiers for
that method.
.PP
\fR\f(CI$metarole\fR\fI\->get_override_method_modifier($method_name)\fR
.IX Subsection "$metarole->get_override_method_modifier($method_name)"
.PP
Given a method name, returns the override method modifier for that
method, if it has one.
.SS Introspection
.IX Subsection "Introspection"
\fIMoose::Meta::Role\->meta\fR
.IX Subsection "Moose::Meta::Role->meta"
.PP
This will return a Class::MOP::Class instance for this class.
.SH BUGS
.IX Header "BUGS"
See "BUGS" 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.