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