5 use Scalar::Util 'blessed';
7 use Class::Load 'is_class_loaded';
15 use Moose::Meta::Role;
16 use Moose::Util::TypeConstraints;
19 croak "Roles do not support 'extends' (you can use 'with' to specialize a role)";
23 Moose::Util::apply_all_roles( shift, @_ );
28 croak "Must specify at least one method" unless @_;
29 $meta->add_required_methods(@_);
34 croak "Must specify at least one role" unless @_;
35 $meta->add_excluded_roles(@_);
41 croak 'Usage: has \'name\' => ( key => value, ... )' if @_ == 1;
42 my %context = Moose::Util::_caller_info;
43 $context{context} = 'has declaration';
44 $context{type} = 'role';
45 my %options = ( definition_context => \%context, @_ );
46 my $attrs = ( ref($name) eq 'ARRAY' ) ? $name : [ ($name) ];
47 $meta->add_attribute( $_, %options ) for @$attrs;
50 sub _add_method_modifier {
54 if ( ref($_[0]) eq 'Regexp' ) {
55 croak "Roles do not currently support regex "
56 . " references for $type method modifiers";
59 Moose::Util::add_method_modifier($meta, $type, \@_);
62 sub before { _add_method_modifier('before', @_) }
64 sub after { _add_method_modifier('after', @_) }
66 sub around { _add_method_modifier('around', @_) }
68 # see Moose.pm for discussion
70 return unless $Moose::SUPER_BODY;
71 $Moose::SUPER_BODY->(@Moose::SUPER_ARGS);
76 my ( $name, $code ) = @_;
77 $meta->add_override_method_modifier( $name, $code );
81 croak "Roles cannot support 'inner'";
85 croak "Roles cannot support 'augment'";
88 Moose::Exporter->setup_import_methods(
90 qw( with requires excludes has before after around override )
93 qw( extends super inner augment ),
95 \&Scalar::Util::blessed,
103 my $role = $args{for_class};
107 Moose->throw_error("Cannot call init_meta without specifying a for_class");
110 my $metaclass = $args{metaclass} || "Moose::Meta::Role";
111 my $meta_name = exists $args{meta_name} ? $args{meta_name} : 'meta';
113 Moose->throw_error("The Metaclass $metaclass must be loaded. (Perhaps you forgot to 'use $metaclass'?)")
114 unless is_class_loaded($metaclass);
116 Moose->throw_error("The Metaclass $metaclass must be a subclass of Moose::Meta::Role.")
117 unless $metaclass->isa('Moose::Meta::Role');
119 # make a subtype for each Moose role
120 role_type $role unless find_type_constraint($role);
123 if ( $meta = Class::MOP::get_metaclass_by_name($role) ) {
124 unless ( $meta->isa("Moose::Meta::Role") ) {
125 my $error_message = "$role already has a metaclass, but it does not inherit $metaclass ($meta).";
126 if ( $meta->isa('Moose::Meta::Class') ) {
127 Moose->throw_error($error_message . ' You cannot make the same thing a role and a class. Remove either Moose or Moose::Role.');
129 Moose->throw_error($error_message);
134 $meta = $metaclass->initialize($role);
137 if (defined $meta_name) {
138 # also check for inherited non moose 'meta' method?
139 my $existing = $meta->get_method($meta_name);
140 if ($existing && !$existing->isa('Class::MOP::Method::Meta')) {
141 Carp::cluck "Moose::Role is overwriting an existing method named "
142 . "$meta_name in role $role with a method "
143 . "which returns the class's metaclass. If this is "
144 . "actually what you want, you should remove the "
145 . "existing method, otherwise, you should rename or "
146 . "disable this generated method using the "
147 . "'-meta_name' option to 'use Moose::Role'.";
149 $meta->_add_meta_method($meta_name);
157 # ABSTRACT: The Moose Role
166 use Moose::Role; # automatically turns on strict and warnings
171 my ($self, $other) = @_;
172 !$self->equal($other);
175 # ... then in your classes
178 use Moose; # automatically turns on strict and warnings
183 my ($self, $other) = @_;
184 $self->as_float == $other->as_float;
200 my $currency1 = Currency->new(...);
201 my $currency2 = Currency->new(...);
202 Comparator->new(compare_to => $currency1)->equal($currency2);
206 The concept of roles is documented in L<Moose::Manual::Roles>. This document
207 serves as API documentation.
209 =head1 EXPORTED FUNCTIONS
211 Moose::Role currently supports all of the functions that L<Moose> exports, but
212 differs slightly in how some items are handled (see L</CAVEATS> below for
215 Moose::Role also offers two role-specific keyword exports:
219 =item B<requires (@method_names)>
221 Roles can require that certain methods are implemented by any class which
224 Note that attribute accessors also count as methods for the purposes
225 of satisfying the requirements of a role.
227 =item B<excludes (@role_names)>
229 Roles can C<exclude> other roles, in effect saying "I can never be combined
230 with these C<@role_names>". This is a feature which should not be used
237 Moose::Role offers a way to remove the keywords it exports, through the
238 C<unimport> method. You simply have to say C<no Moose::Role> at the bottom of
239 your code for this to work.
243 When you use Moose::Role, you can specify traits which will be applied to your
246 use Moose::Role -traits => 'My::Trait';
248 This is very similar to the attribute traits feature. When you do
249 this, your class's C<meta> object will have the specified traits
250 applied to it. See L<Moose/Metaclass and Trait Name Resolution> for more
253 =head1 APPLYING ROLES
255 In addition to being applied to a class using the 'with' syntax (see
256 L<Moose::Manual::Roles>) and using the L<Moose::Util> 'apply_all_roles'
257 method, roles may also be applied to an instance of a class using
258 L<Moose::Util> 'apply_all_roles' or the role's metaclass:
260 MyApp::Test::SomeRole->meta->apply( $instance );
262 Doing this creates a new, mutable, anonymous subclass, applies the role to that,
263 and reblesses. In a debugger, for example, you will see class names of the
264 form C< Moose::Meta::Class::__ANON__::SERIAL::6 >, which means that doing a
265 'ref' on your instance may not return what you expect. See L<Moose::Object> for
268 Additional params may be added to the new instance by providing
269 'rebless_params'. See L<Moose::Meta::Role::Application::ToInstance>.
273 Role support has only a few caveats:
279 Roles cannot use the C<extends> keyword; it will throw an exception for now.
280 The same is true of the C<augment> and C<inner> keywords (not sure those
281 really make sense for roles). All other Moose keywords will be I<deferred>
282 so that they can be applied to the consuming class.
286 Role composition does its best to B<not> be order-sensitive when it comes to
287 conflict resolution and requirements detection. However, it is order-sensitive
288 when it comes to method modifiers. All before/around/after modifiers are
289 included whenever a role is composed into a class, and then applied in the order
290 in which the roles are used. This also means that there is no conflict for
291 before/around/after modifiers.
293 In most cases, this will be a non-issue; however, it is something to keep in
294 mind when using method modifiers in a role. You should never assume any
301 See L<Moose/BUGS> for details on reporting bugs.