/ 
Moose-0.81
River stage four • 2950 direct dependents • 4061 total dependents
/ Moose::Meta::Role

NAME

Moose::Meta::Role - The Moose Role metaclass

DESCRIPTION

This class is a subclass of Class::MOP::Module that provides additional Moose-specific functionality.

It's API looks a lot like Moose::Meta::Class, but internally it implements many things differently. This may change in the future.

INHERITANCE

Moose::Meta::Role is a subclass of Class::MOP::Module.

METHODS

Construction

Moose::Meta::Role->initialize($role_name)

This method creates a new role object with the provided name.

Moose::Meta::Role->combine( [ $role => { ... } ], [ $role ], ... )

This method accepts a list of array references. Each array reference should contain a role name as its first element. The second element is an optional hash reference. The hash reference can contain exclude and alias keys to control how methods are composed from the role.

The return value is a new Moose::Meta::Role::Composite that represents the combined roles.

Moose::Meta::Role->create($name, %options)

This method is identical to the Moose::Meta::Class create method.

Moose::Meta::Role->create_anon_role

This method is identical to the Moose::Meta::Class create_anon_class method.

$metarole->is_anon_role

Returns true if the role is an anonymous role.

Role application

$metarole->apply( $thing, @options )

This method applies a role to the given $thing. That can be another Moose::Meta::Role, object, a Moose::Meta::Class object, or a (non-meta) object instance.

The options are passed directly to the constructor for the appropriate Moose::Meta::Role::Application subclass.

Note that this will apply the role even if the $thing in question already does this role. "does_role" in Moose::Util is a convenient wrapper for finding out if role application is necessary.

Roles and other roles

$metarole->get_roles

This returns an array reference of roles which this role does. This list may include duplicates.

$metarole->calculate_all_roles

This returns a unique list of all roles that this role does, and all the roles that its roles do.

$metarole->does_role($role_name)

Given a role name, returns true if this role does the given role.

$metarole->add_role($role)

Given a Moose::Meta::Role object, this adds the role to the list of roles that the role does.

$metarole->get_excluded_roles_list

Returns a list of role names which this role excludes.

$metarole->excludes_role($role_name)

Given a role name, returns true if this role excludes the named role.

$metarole->add_excluded_roles(@role_names)

Given one or more role names, adds those roles to the list of excluded roles.

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.

$metarole->method_metaclass

Returns the method metaclass name for the role. This defaults to Moose::Meta::Role::Method.

$metarole->get_method($name)
$metarole->has_method($name)
$metarole->add_method( $name, $body )
$metarole->get_method_list
$metarole->get_method_map
$metarole->find_method_by_name($name)

These methods are all identical to the methods of the same name in Class::MOP::Class

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.

However, attributes stored in this class are not 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 add_attribute method.

This is quite likely to change in the future.

$metarole->get_attribute($attribute_name)
$metarole->has_attribute($attribute_name)
$metarole->get_attribute_map
$metarole->get_attribute_list
$metarole->add_attribute($name, %options)
$metarole->remove_attribute($attribute_name)

Required methods

$metarole->get_required_method_list

Returns the list of methods required by the role.

$metarole->requires_method($name)

Returns true if the role requires the named method.

$metarole->add_required_methods(@names)

Adds the named methods to the role's list of required methods.

$metarole->remove_required_methods(@names)

Removes the named methods from the role's list of required methods.

$metarole->add_conflicting_method(%params)

Instantiate the parameters as a Moose::Meta::Role::Method::Conflicting object, then add it to the required method list.

Method modifiers

These methods act like their counterparts in Class::Mop::Class and Moose::Meta::Class.

However, method modifiers are simply stored internally, and are not applied until the role itself is applied to a class.

$metarole->add_after_method_modifier($method_name, $method)
$metarole->add_around_method_modifier($method_name, $method)
$metarole->add_before_method_modifier($method_name, $method)
$metarole->add_override_method_modifier($method_name, $method)

These methods all add an appropriate modifier to the internal list of modifiers.

$metarole->has_after_method_modifiers
$metarole->has_around_method_modifiers
$metarole->has_before_method_modifiers
$metarole->has_override_method_modifier

Return true if the role has any modifiers of the given type.

$metarole->get_after_method_modifiers($method_name)
$metarole->get_around_method_modifiers($method_name)
$metarole->get_before_method_modifiers($method_name)

Given a method name, returns a list of the appropriate modifiers for that method.

$metarole->get_override_method_modifier($method_name)

Given a method name, returns the override method modifier for that method, if it has one.

Introspection

Moose::Meta::Role->meta

This will return a Class::MOP::Class instance for this class.

BUGS

All complex software has bugs lurking in it, and this module is no exception. If you find a bug please either email me, or add the bug to cpan-RT.

AUTHOR

Stevan Little <stevan@iinteractive.com>

COPYRIGHT AND LICENSE

Copyright 2006-2009 by Infinity Interactive, Inc.

http://www.iinteractive.com

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.