5 use Scalar::Util 'blessed';
10 our $AUTHORITY = 'cpan:STEVAN';
16 use Moose::Meta::Role;
17 use Moose::Util::TypeConstraints;
20 croak "Roles do not support 'extends' (you can use 'with' to specialize a role)";
24 Moose::Util::apply_all_roles( shift, @_ );
29 croak "Must specify at least one method" unless @_;
30 $meta->add_required_methods(@_);
35 croak "Must specify at least one role" unless @_;
36 $meta->add_excluded_roles(@_);
42 croak 'Usage: has \'name\' => ( key => value, ... )' if @_ == 1;
43 my %options = ( definition_context => Moose::Util::_caller_info(), @_ );
44 my $attrs = ( ref($name) eq 'ARRAY' ) ? $name : [ ($name) ];
45 $meta->add_attribute( $_, %options ) for @$attrs;
48 sub _add_method_modifier {
52 if ( ref($_[0]) eq 'Regexp' ) {
53 croak "Roles do not currently support regex "
54 . " references for $type method modifiers";
57 Moose::Util::add_method_modifier($meta, $type, \@_);
60 sub before { _add_method_modifier('before', @_) }
62 sub after { _add_method_modifier('after', @_) }
64 sub around { _add_method_modifier('around', @_) }
66 # see Moose.pm for discussion
68 return unless $Moose::SUPER_BODY;
69 $Moose::SUPER_BODY->(@Moose::SUPER_ARGS);
74 my ( $name, $code ) = @_;
75 $meta->add_override_method_modifier( $name, $code );
79 croak "Roles cannot support 'inner'";
83 croak "Roles cannot support 'augment'";
86 Moose::Exporter->setup_import_methods(
88 qw( with requires excludes has before after around override )
91 qw( extends super inner augment ),
93 \&Scalar::Util::blessed,
101 my $role = $args{for_class};
105 Moose->throw_error("Cannot call init_meta without specifying a for_class");
108 my $metaclass = $args{metaclass} || "Moose::Meta::Role";
109 my $meta_name = exists $args{meta_name} ? $args{meta_name} : 'meta';
111 Moose->throw_error("The Metaclass $metaclass must be a subclass of Moose::Meta::Role.")
112 unless $metaclass->isa('Moose::Meta::Role');
114 # make a subtype for each Moose role
115 role_type $role unless find_type_constraint($role);
118 if ( $meta = Class::MOP::get_metaclass_by_name($role) ) {
119 unless ( $meta->isa("Moose::Meta::Role") ) {
120 my $error_message = "$role already has a metaclass, but it does not inherit $metaclass ($meta).";
121 if ( $meta->isa('Moose::Meta::Class') ) {
122 Moose->throw_error($error_message . ' You cannot make the same thing a role and a class. Remove either Moose or Moose::Role.');
124 Moose->throw_error($error_message);
129 $meta = $metaclass->initialize($role);
132 if (defined $meta_name) {
133 # also check for inherited non moose 'meta' method?
134 my $existing = $meta->get_method($meta_name);
135 if ($existing && !$existing->isa('Class::MOP::Method::Meta')) {
136 Carp::cluck "Moose::Role is overwriting an existing method named "
137 . "$meta_name in role $role with a method "
138 . "which returns the class's metaclass. If this is "
139 . "actually what you want, you should remove the "
140 . "existing method, otherwise, you should rename or "
141 . "disable this generated method using the "
142 . "'-meta_name' option to 'use Moose::Role'.";
144 $meta->_add_meta_method($meta_name);
152 # ABSTRACT: The Moose Role
161 use Moose::Role; # automatically turns on strict and warnings
166 my ($self, $other) = @_;
167 !$self->equal($other);
170 # ... then in your classes
173 use Moose; # automatically turns on strict and warnings
178 my ($self, $other) = @_;
179 $self->as_float == $other->as_float;
184 The concept of roles is documented in L<Moose::Manual::Roles>. This document
185 serves as API documentation.
187 =head1 EXPORTED FUNCTIONS
189 Moose::Role currently supports all of the functions that L<Moose> exports, but
190 differs slightly in how some items are handled (see L</CAVEATS> below for
193 Moose::Role also offers two role-specific keyword exports:
197 =item B<requires (@method_names)>
199 Roles can require that certain methods are implemented by any class which
202 Note that attribute accessors also count as methods for the purposes
203 of satisfying the requirements of a role.
205 =item B<excludes (@role_names)>
207 Roles can C<exclude> other roles, in effect saying "I can never be combined
208 with these C<@role_names>". This is a feature which should not be used
215 Moose::Role offers a way to remove the keywords it exports, through the
216 C<unimport> method. You simply have to say C<no Moose::Role> at the bottom of
217 your code for this to work.
219 =head2 B<< Moose::Role->init_meta(for_class => $role, metaclass => $metaclass) >>
221 The C<init_meta> method sets up the metaclass object for the role
222 specified by C<for_class>. It also injects a a C<meta> accessor into
223 the role so you can get at this object.
225 The default metaclass is L<Moose::Meta::Role>. You can specify an
226 alternate metaclass with the C<metaclass> parameter.
230 When you use Moose::Role, you can specify which metaclass to use:
232 use Moose::Role -metaclass => 'My::Meta::Role';
234 You can also specify traits which will be applied to your role metaclass:
236 use Moose::Role -traits => 'My::Trait';
238 This is very similar to the attribute traits feature. When you do
239 this, your class's C<meta> object will have the specified traits
240 applied to it. See L<Moose/Metaclass and Trait Name Resolution> for more
243 =head1 APPLYING ROLES
245 In addition to being applied to a class using the 'with' syntax (see
246 L<Moose::Manual::Roles>) and using the L<Moose::Util> 'apply_all_roles'
247 method, roles may also be applied to an instance of a class using
248 L<Moose::Util> 'apply_all_roles' or the role's metaclass:
250 MyApp::Test::SomeRole->meta->apply( $instance );
252 Doing this creates a new, mutable, anonymous subclass, applies the role to that,
253 and reblesses. In a debugger, for example, you will see class names of the
254 form C< Class::MOP::Class::__ANON__::SERIAL::6 >, which means that doing a 'ref'
255 on your instance may not return what you expect. See L<Moose::Object> for 'DOES'.
257 Additional params may be added to the new instance by providing 'rebless_params'.
258 See L<Moose::Meta::Role::Application::ToInstance>.
262 Role support has only a few caveats:
268 Roles cannot use the C<extends> keyword; it will throw an exception for now.
269 The same is true of the C<augment> and C<inner> keywords (not sure those
270 really make sense for roles). All other Moose keywords will be I<deferred>
271 so that they can be applied to the consuming class.
275 Role composition does its best to B<not> be order-sensitive when it comes to
276 conflict resolution and requirements detection. However, it is order-sensitive
277 when it comes to method modifiers. All before/around/after modifiers are
278 included whenever a role is composed into a class, and then applied in the order
279 in which the roles are used. This also means that there is no conflict for
280 before/around/after modifiers.
282 In most cases, this will be a non-issue; however, it is something to keep in
283 mind when using method modifiers in a role. You should never assume any
290 See L<Moose/BUGS> for details on reporting bugs.