From: Dave Rolsky Date: Tue, 24 Mar 2009 02:42:57 +0000 (-0500) Subject: API docs for Moose::Meta::Role X-Git-Tag: 0.72_01~30 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=705d4cfdfef0059144251081a8a99ab6aa60c8ad;p=gitmo%2FMoose.git API docs for Moose::Meta::Role --- diff --git a/lib/Moose/Meta/Role.pm b/lib/Moose/Meta/Role.pm index f1fd0c7..804e78e 100644 --- a/lib/Moose/Meta/Role.pm +++ b/lib/Moose/Meta/Role.pm @@ -723,174 +723,237 @@ Moose::Meta::Role - The Moose Role metaclass =head1 DESCRIPTION -Please see L for more information about roles. -For the most part, this has no user-serviceable parts inside -this module. It's API is still subject to some change (although -probably not that much really). +This class is a subclass of L that provides +additional Moose-specific functionality. + +It's API looks a lot like L, but internally it +implements many things differently. This may change in the future. =head1 METHODS +=head2 Construction + =over 4 -=item B +=item B<< Moose::Meta::Role->initialize($role_name) >> -=item B +This method creates a new role object with the provided name. -=item B +=item B<< Moose::Meta::Role->combine( [ $role => { ... } ], [ $role ], ... ) >> -=item B +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 C +and C keys to control how methods are composed from the role. -=item B +The return value is a new L that +represents the combined roles. -=back +=item B<< Moose::Meta::Role->create($name, %options) >> -=over 4 +This method is identical to the L C +method. + +=item B<< Moose::Meta::Role->create_anon_role >> -=item B +This method is identical to the L +C method. -=item B +=item B<< $metarole->is_anon_role >> -=item B +Returns true if the role is an anonymous role. =back +=head2 Role application + =over 4 -=item B +=item B<< $metarole->apply( $thing, @options ) >> -=item B +This method applies a role to the given C<$thing>. That can be another +L, object, a L object, or a +(non-meta) object instance. -=item B +The options are passed directly to the constructor for the appropriate +L subclass. =back +=head2 Roles and other roles + =over 4 -=item B +=item B<< $metarole->get_roles >> -=item B +This returns an array reference of roles which this role does. This +list may include duplicates. -=item B +=item B<< $metarole->calculate_all_roles >> -=item B +This returns a I list of all roles that this role does, and +all the roles that its roles do. -=item B +=item B<< $metarole->does_role($role_name) >> -=back +Given a role I, returns true if this role does the given +role. -=over 4 +=item B<< $metarole->add_role($role) >> -=item B +Given a L object, this adds the role to the list of +roles that the role does. -=item B +=item B<< $metarole->get_excluded_roles_list >> -=item B +Returns a list of role names which this role excludes. -=item B +=item B<< $metarole->excludes_role($role_name) >> -=item B +Given a role I, returns true if this role excludes the named +role. -=item B +=item B<< $metarole->add_excluded_roles(@role_names) >> -=item B +Given one or more role names, adds those roles to the list of excluded +roles. -=item B +=back -=item B +=head2 Methods -=item B +The methods for dealing with a role's methods are all identical in API +and behavior to the same methods in L. -=item B +=over 4 -=back +=item B<< $metarole->method_metaclass >> -=over 4 +Returns the method metaclass name for the role. This defaults to +L. -=item B +=item B<< $metarole->get_method($name) >> -=item B +=item B<< $metarole->has_method($name) >> -=item B +=item B<< $metarole->add_method( $name, $body ) >> -=item B +=item B<< $metarole->get_method_list >> -=item B +=item B<< $metarole->get_method_map >> -=item B +=item B<< $metarole->find_method_by_name($name) >> + +These methods are all identical to the methods of the same name in +L =back +=head2 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 +L. + +However, attributes stored in this class are I 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 C method. + +This is quite likely to change in the future. + =over 4 -=item B +=item B<< $metarole->get_attribute($attribute_name) >> + +=item B<< $metarole->has_attribute($attribute_name) >> -=item B +=item B<< $metarole->get_attribute_map >> -=item B +=item B<< $metarole->get_attribute_list >> -=item B +=item B<< $metarole->add_attribute($name, %options) >> -=item B +=item B<< $metarole->remove_attribute($attribute_name) >> =back +=head2 Required methods + =over 4 -=item B +=item B<< $metarole->get_required_method_list >> -=item B +Returns the list of methods required by the role. -=item B +=item B<< $metarole->requires_method($name) >> -=item B +Returns true if the role requires the named method. -=over 4 +=item B<< $metarole->add_required_methods(@names >> -=back +Adds the named methods to the roles list of required methods. -=item B +=item B<< $metarole->remove_required_methods(@names) >> -=item B +Removes the named methods to the roles list of required methods. -=item B +=back + +=head2 Method modifiers -=item B +These methods act like their counterparts in L and +L. + +However, method modifiers are simply stored internally, and are not +applied until the role itself is applied to a class. =over 4 -=back +=item B<< $metarole->add_after_method_modifier($method_name, $method) >> -=item B +=item B<< $metarole->add_around_method_modifier($method_name, $method) >> -=item B +=item B<< $metarole->add_before_method_modifier($method_name, $method) >> -=item B +=item B<< $metarole->add_override_method_modifier($method_name, $method) >> -=item B +These methods all add an appropriate modifier to the internal list of +modifiers. -=over 4 +=item B<< $metarole->has_after_method_modifiers >> -=back +=item B<< $metarole->has_around_method_modifiers >> + +=item B<< $metarole->has_before_method_modifiers >> + +=item B<< $metarole->has_override_method_modifier >> -=item B +Return true if the role has any modifiers of the given type. -=item B +=item B<< $metarole->get_after_method_modifiers($method_name) >> -=item B +=item B<< $metarole->get_around_method_modifiers($method_name) >> -=item B +=item B<< $metarole->get_before_method_modifiers($method_name) >> -=item B +Given a method name, returns a list of the appropriate modifiers for +that method. + +=item B<< $metarole->get_override_method_modifier($method_name) >> + +Given a method name, returns the override method modifier for that +method, if it has one. =back -=over 4 +=head2 Introspection -=item B +=over 4 -=item B +=item B<< Moose::Meta::Role->meta >> -=item B +This will return a L instance for this class. =back diff --git a/xt/pod_coverage.t b/xt/pod_coverage.t index f71b846..8969c75 100644 --- a/xt/pod_coverage.t +++ b/xt/pod_coverage.t @@ -47,7 +47,15 @@ my %trustme = ( ) ], 'Moose::Meta::Method::Destructor' => [ 'initialize_body', 'options' ], - 'Moose::Role' => [ + 'Moose::Meta::Role' => [ + qw( alias_method + get_method_modifier_list + reset_package_cache_flag + update_package_cache_flag + wrap_method_body + ) + ], + 'Moose::Role' => [ qw( after around augment