.\" Automatically generated by Pod::Man 4.10 (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::Meta::Role 3pm"
.TH Moose::Meta::Role 3pm "2018-11-02" "perl v5.28.0" "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.2011
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class is a subclass of Class::MOP::Module that provides
additional Moose-specific functionality.
.PP
Its \s-1API\s0 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( [ \f(CI$role\fI => { ... } ], [ \f(CI$role\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
\fI\f(CI$metarole\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, \f(CI%options\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
\fI\f(CI$metarole\fI\->is_anon_role\fR
.IX Subsection "$metarole->is_anon_role"
.PP
Returns true if the role is an anonymous role.
.PP
\fI\f(CI$metarole\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"
\fI\f(CI$metarole\fI\->apply( \f(CI$thing\fI, \f(CI@options\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.  \*(L"does_role\*(R" 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"
\fI\f(CI$metarole\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
\fI\f(CI$metarole\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
\fI\f(CI$metarole\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
\fI\f(CI$metarole\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
\fI\f(CI$metarole\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
\fI\f(CI$metarole\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
\fI\f(CI$metarole\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 \s-1API\s0
and behavior to the same methods in Class::MOP::Class.
.PP
\fI\f(CI$metarole\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
\fI\f(CI$metarole\fI\->get_method($name)\fR
.IX Subsection "$metarole->get_method($name)"
.PP
\fI\f(CI$metarole\fI\->has_method($name)\fR
.IX Subsection "$metarole->has_method($name)"
.PP
\fI\f(CI$metarole\fI\->add_method( \f(CI$name\fI, \f(CI$body\fI )\fR
.IX Subsection "$metarole->add_method( $name, $body )"
.PP
\fI\f(CI$metarole\fI\->get_method_list\fR
.IX Subsection "$metarole->get_method_list"
.PP
\fI\f(CI$metarole\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::Package
.SS "Attributes"
.IX Subsection "Attributes"
As with methods, the methods for dealing with a role's attribute are
all identical in \s-1API\s0 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
\fI\f(CI$metarole\fI\->get_attribute($attribute_name)\fR
.IX Subsection "$metarole->get_attribute($attribute_name)"
.PP
\fI\f(CI$metarole\fI\->has_attribute($attribute_name)\fR
.IX Subsection "$metarole->has_attribute($attribute_name)"
.PP
\fI\f(CI$metarole\fI\->get_attribute_list\fR
.IX Subsection "$metarole->get_attribute_list"
.PP
\fI\f(CI$metarole\fI\->add_attribute($name, \f(CI%options\fI)\fR
.IX Subsection "$metarole->add_attribute($name, %options)"
.PP
\fI\f(CI$metarole\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 \s-1API\s0 and
behavior to the same methods in Class::MOP::Class.
.PP
\fI\f(CI$metarole\fI\->is_overloaded\fR
.IX Subsection "$metarole->is_overloaded"
.PP
\fI\f(CI$metarole\fI\->get_overloaded_operator($op)\fR
.IX Subsection "$metarole->get_overloaded_operator($op)"
.PP
\fI\f(CI$metarole\fI\->has_overloaded_operator($op)\fR
.IX Subsection "$metarole->has_overloaded_operator($op)"
.PP
\fI\f(CI$metarole\fI\->get_overload_list\fR
.IX Subsection "$metarole->get_overload_list"
.PP
\fI\f(CI$metarole\fI\->get_all_overloaded_operators\fR
.IX Subsection "$metarole->get_all_overloaded_operators"
.PP
\fI\f(CI$metarole\fI\->add_overloaded_operator($op, \f(CI$impl\fI)\fR
.IX Subsection "$metarole->add_overloaded_operator($op, $impl)"
.PP
\fI\f(CI$metarole\fI\->remove_overloaded_operator($op)\fR
.IX Subsection "$metarole->remove_overloaded_operator($op)"
.SS "Required methods"
.IX Subsection "Required methods"
\fI\f(CI$metarole\fI\->get_required_method_list\fR
.IX Subsection "$metarole->get_required_method_list"
.PP
Returns the list of methods required by the role.
.PP
\fI\f(CI$metarole\fI\->requires_method($name)\fR
.IX Subsection "$metarole->requires_method($name)"
.PP
Returns true if the role requires the named method.
.PP
\fI\f(CI$metarole\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
\fI\f(CI$metarole\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
\fI\f(CI$metarole\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
\fI\f(CI$metarole\fI\->add_after_method_modifier($method_name, \f(CI$method\fI)\fR
.IX Subsection "$metarole->add_after_method_modifier($method_name, $method)"
.PP
\fI\f(CI$metarole\fI\->add_around_method_modifier($method_name, \f(CI$method\fI)\fR
.IX Subsection "$metarole->add_around_method_modifier($method_name, $method)"
.PP
\fI\f(CI$metarole\fI\->add_before_method_modifier($method_name, \f(CI$method\fI)\fR
.IX Subsection "$metarole->add_before_method_modifier($method_name, $method)"
.PP
\fI\f(CI$metarole\fI\->add_override_method_modifier($method_name, \f(CI$method\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
\fI\f(CI$metarole\fI\->has_after_method_modifiers\fR
.IX Subsection "$metarole->has_after_method_modifiers"
.PP
\fI\f(CI$metarole\fI\->has_around_method_modifiers\fR
.IX Subsection "$metarole->has_around_method_modifiers"
.PP
\fI\f(CI$metarole\fI\->has_before_method_modifiers\fR
.IX Subsection "$metarole->has_before_method_modifiers"
.PP
\fI\f(CI$metarole\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
\fI\f(CI$metarole\fI\->get_after_method_modifiers($method_name)\fR
.IX Subsection "$metarole->get_after_method_modifiers($method_name)"
.PP
\fI\f(CI$metarole\fI\->get_around_method_modifiers($method_name)\fR
.IX Subsection "$metarole->get_around_method_modifiers($method_name)"
.PP
\fI\f(CI$metarole\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
\fI\f(CI$metarole\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 \*(L"\s-1BUGS\*(R"\s0 in Moose for details on reporting bugs.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Stevan Little <stevan.little@iinteractive.com>
.IP "\(bu" 4
Dave Rolsky <autarch@urth.org>
.IP "\(bu" 4
Jesse Luehrs <doy@tozt.net>
.IP "\(bu" 4
Shawn M Moore <code@sartak.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@weftsoar.net>
.IP "\(bu" 4
Chris Prather <chris@prather.org>
.IP "\(bu" 4
Matt S Trout <mst@shadowcat.co.uk>
.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.