check if the metaclass is loaded
[gitmo/Moose.git] / lib / Moose / Role.pm
CommitLineData
e185c027 1package Moose::Role;
d1e17c7f 2use strict;
3use warnings;
e185c027 4
e65dccbc 5use Scalar::Util 'blessed';
f4f808de 6use Carp 'croak';
e185c027 7
2d562421 8use Sub::Exporter;
9
d7d8a8c7 10use Moose ();
11use Moose::Util ();
e65dccbc 12
c36b393c 13use Moose::Exporter;
e185c027 14use Moose::Meta::Role;
7eaef7ad 15use Moose::Util::TypeConstraints;
e185c027 16
e606ae5f 17sub extends {
887e3bf0 18 croak "Roles do not support 'extends' (you can use 'with' to specialize a role)";
e606ae5f 19}
20
21sub with {
d5447d26 22 Moose::Util::apply_all_roles( shift, @_ );
e606ae5f 23}
24
25sub requires {
d5447d26 26 my $meta = shift;
e606ae5f 27 croak "Must specify at least one method" unless @_;
28 $meta->add_required_methods(@_);
29}
30
31sub excludes {
d5447d26 32 my $meta = shift;
e606ae5f 33 croak "Must specify at least one role" unless @_;
34 $meta->add_excluded_roles(@_);
35}
2d562421 36
e606ae5f 37sub has {
d5447d26 38 my $meta = shift;
e606ae5f 39 my $name = shift;
40 croak 'Usage: has \'name\' => ( key => value, ... )' if @_ == 1;
833b56a7 41 my %options = ( definition_context => Moose::Util::_caller_info(), @_ );
e606ae5f 42 my $attrs = ( ref($name) eq 'ARRAY' ) ? $name : [ ($name) ];
43 $meta->add_attribute( $_, %options ) for @$attrs;
44}
2d562421 45
2e3c7aa0 46sub _add_method_modifier {
47 my $type = shift;
d5447d26 48 my $meta = shift;
d9add270 49
50 if ( ref($_[0]) eq 'Regexp' ) {
51 croak "Roles do not currently support regex "
52 . " references for $type method modifiers";
e606ae5f 53 }
d9add270 54
55 Moose::Util::add_method_modifier($meta, $type, \@_);
e606ae5f 56}
2d562421 57
2e3c7aa0 58sub before { _add_method_modifier('before', @_) }
2d562421 59
2e3c7aa0 60sub after { _add_method_modifier('after', @_) }
fb1e11d5 61
2e3c7aa0 62sub around { _add_method_modifier('around', @_) }
fb1e11d5 63
e606ae5f 64# see Moose.pm for discussion
65sub super {
66 return unless $Moose::SUPER_BODY;
67 $Moose::SUPER_BODY->(@Moose::SUPER_ARGS);
68}
69
70sub override {
d5447d26 71 my $meta = shift;
e606ae5f 72 my ( $name, $code ) = @_;
73 $meta->add_override_method_modifier( $name, $code );
74}
75
76sub inner {
b8945921 77 croak "Roles cannot support 'inner'";
e606ae5f 78}
79
80sub augment {
b8945921 81 croak "Roles cannot support 'augment'";
e606ae5f 82}
83
c36b393c 84Moose::Exporter->setup_import_methods(
d5447d26 85 with_meta => [
d4783454 86 qw( with requires excludes has before after around override )
e606ae5f 87 ],
88 as_is => [
89 qw( extends super inner augment ),
90 \&Carp::confess,
91 \&Scalar::Util::blessed,
92 ],
93);
94
95sub init_meta {
96 shift;
97 my %args = @_;
98
70ea9161 99 my $role = $args{for_class};
100
101 unless ($role) {
102 require Moose;
103 Moose->throw_error("Cannot call init_meta without specifying a for_class");
104 }
e606ae5f 105
106 my $metaclass = $args{metaclass} || "Moose::Meta::Role";
2937ed18 107 my $meta_name = exists $args{meta_name} ? $args{meta_name} : 'meta';
e606ae5f 108
ed544690 109 Moose->throw_error("The Metaclass $metaclass must be a subclass of Moose::Meta::Role.")
110 unless $metaclass->isa('Moose::Meta::Role');
111
112 # make a subtype for each Moose role
e606ae5f 113 role_type $role unless find_type_constraint($role);
114
e606ae5f 115 my $meta;
ed544690 116 if ( $meta = Class::MOP::get_metaclass_by_name($role) ) {
117 unless ( $meta->isa("Moose::Meta::Role") ) {
118 my $error_message = "$role already has a metaclass, but it does not inherit $metaclass ($meta).";
119 if ( $meta->isa('Moose::Meta::Class') ) {
120 Moose->throw_error($error_message . ' You cannot make the same thing a role and a class. Remove either Moose or Moose::Role.');
121 } else {
122 Moose->throw_error($error_message);
123 }
70ea9161 124 }
e606ae5f 125 }
126 else {
127 $meta = $metaclass->initialize($role);
ed544690 128 }
e606ae5f 129
2937ed18 130 if (defined $meta_name) {
ed544690 131 # also check for inherited non moose 'meta' method?
2937ed18 132 my $existing = $meta->get_method($meta_name);
d65bfd76 133 if ($existing && !$existing->isa('Class::MOP::Method::Meta')) {
df100ac2 134 Carp::cluck "Moose::Role is overwriting an existing method named "
2937ed18 135 . "$meta_name in role $role with a method "
136 . "which returns the class's metaclass. If this is "
137 . "actually what you want, you should remove the "
138 . "existing method, otherwise, you should rename or "
139 . "disable this generated method using the "
140 . "'-meta_name' option to 'use Moose::Role'.";
d65bfd76 141 }
2937ed18 142 $meta->_add_meta_method($meta_name);
d31f9614 143 }
e606ae5f 144
145 return $meta;
e185c027 146}
147
1481;
149
ad46f524 150# ABSTRACT: The Moose Role
151
e185c027 152__END__
153
154=pod
155
76d37e5a 156=head1 SYNOPSIS
157
158 package Eq;
85424612 159 use Moose::Role; # automatically turns on strict and warnings
fb1e11d5 160
e46edf94 161 requires 'equal';
fb1e11d5 162
163 sub no_equal {
76d37e5a 164 my ($self, $other) = @_;
165 !$self->equal($other);
166 }
fb1e11d5 167
76d37e5a 168 # ... then in your classes
fb1e11d5 169
76d37e5a 170 package Currency;
85424612 171 use Moose; # automatically turns on strict and warnings
fb1e11d5 172
76d37e5a 173 with 'Eq';
fb1e11d5 174
76d37e5a 175 sub equal {
176 my ($self, $other) = @_;
bdabd620 177 $self->as_float == $other->as_float;
76d37e5a 178 }
179
36fa7a87 180 # ... and also
181
182 package Comparator;
183 use Moose;
184
185 has compare_to => (
186 is => 'ro',
187 does => 'Eq',
188 handles => 'Eq',
189 );
190
191 # ... which allows
192
193 my $currency1 = Currency->new(...);
194 my $currency2 = Currency->new(...);
195 Comparator->new(compare_to => $currency1)->equal($currency2);
196
e185c027 197=head1 DESCRIPTION
198
46b73973 199The concept of roles is documented in L<Moose::Manual::Roles>. This document
69161799 200serves as API documentation.
76d37e5a 201
2c0cbef7 202=head1 EXPORTED FUNCTIONS
203
85424612 204Moose::Role currently supports all of the functions that L<Moose> exports, but
cec39889 205differs slightly in how some items are handled (see L</CAVEATS> below for
85424612 206details).
76d37e5a 207
85424612 208Moose::Role also offers two role-specific keyword exports:
e185c027 209
210=over 4
211
2c0cbef7 212=item B<requires (@method_names)>
76d37e5a 213
fb1e11d5 214Roles can require that certain methods are implemented by any class which
85424612 215C<does> the role.
9e93dd19 216
92fcea04 217Note that attribute accessors also count as methods for the purposes
218of satisfying the requirements of a role.
219
2c0cbef7 220=item B<excludes (@role_names)>
221
9e93dd19 222Roles can C<exclude> other roles, in effect saying "I can never be combined
fb1e11d5 223with these C<@role_names>". This is a feature which should not be used
85424612 224lightly.
9e93dd19 225
2c0cbef7 226=back
227
d31f9614 228=head2 B<unimport>
229
230Moose::Role offers a way to remove the keywords it exports, through the
231C<unimport> method. You simply have to say C<no Moose::Role> at the bottom of
232your code for this to work.
233
c1381000 234=head1 METACLASS
235
0f9d92ef 236When you use Moose::Role, you can specify traits which will be applied to your
237role metaclass:
c1381000 238
239 use Moose::Role -traits => 'My::Trait';
240
241This is very similar to the attribute traits feature. When you do
242this, your class's C<meta> object will have the specified traits
8a8856de 243applied to it. See L<Moose/Metaclass and Trait Name Resolution> for more
244details.
c1381000 245
b9cb323b 246=head1 APPLYING ROLES
247
248In addition to being applied to a class using the 'with' syntax (see
249L<Moose::Manual::Roles>) and using the L<Moose::Util> 'apply_all_roles'
250method, roles may also be applied to an instance of a class using
251L<Moose::Util> 'apply_all_roles' or the role's metaclass:
252
253 MyApp::Test::SomeRole->meta->apply( $instance );
254
255Doing this creates a new, mutable, anonymous subclass, applies the role to that,
256and reblesses. In a debugger, for example, you will see class names of the
0f9d92ef 257form C< Moose::Meta::Class::__ANON__::SERIAL::6 >, which means that doing a
258'ref' on your instance may not return what you expect. See L<Moose::Object> for
259'DOES'.
b9cb323b 260
0f9d92ef 261Additional params may be added to the new instance by providing
262'rebless_params'. See L<Moose::Meta::Role::Application::ToInstance>.
b9cb323b 263
2c0cbef7 264=head1 CAVEATS
265
85424612 266Role support has only a few caveats:
2c0cbef7 267
268=over 4
76d37e5a 269
76d37e5a 270=item *
271
fb1e11d5 272Roles cannot use the C<extends> keyword; it will throw an exception for now.
273The same is true of the C<augment> and C<inner> keywords (not sure those
274really make sense for roles). All other Moose keywords will be I<deferred>
85424612 275so that they can be applied to the consuming class.
76d37e5a 276
fb1e11d5 277=item *
2c0cbef7 278
85424612 279Role composition does its best to B<not> be order-sensitive when it comes to
280conflict resolution and requirements detection. However, it is order-sensitive
281when it comes to method modifiers. All before/around/after modifiers are
282included whenever a role is composed into a class, and then applied in the order
283in which the roles are used. This also means that there is no conflict for
284before/around/after modifiers.
2c0cbef7 285
85424612 286In most cases, this will be a non-issue; however, it is something to keep in
287mind when using method modifiers in a role. You should never assume any
2c0cbef7 288ordering.
289
e185c027 290=back
291
292=head1 BUGS
293
d4048ef3 294See L<Moose/BUGS> for details on reporting bugs.
e185c027 295
68117c45 296=cut