Merge branch 'master' into topic/cmop-merge
[gitmo/Moose.git] / lib / Moose / Meta / Role.pm
CommitLineData
e185c027 1
2package Moose::Meta::Role;
3
4use strict;
5use warnings;
6use metaclass;
7
21f1e231 8use Scalar::Util 'blessed';
b6a00b82 9use Carp 'confess';
963c24e1 10use Devel::GlobalDestruction 'in_global_destruction';
bdabd620 11
8ee73eeb 12use Moose::Meta::Class;
f785aad8 13use Moose::Meta::Role::Attribute;
39b3bc94 14use Moose::Meta::Role::Method;
d67145ed 15use Moose::Meta::Role::Method::Required;
bb153262 16use Moose::Meta::Role::Method::Conflicting;
699a2e32 17use Moose::Meta::Method::Meta;
f785aad8 18use Moose::Util qw( ensure_all_roles );
d2782813 19use Class::MOP::MiniTrait;
8ee73eeb 20
72276e04 21use base 'Class::MOP::Module',
22 'Class::MOP::Mixin::HasAttributes',
23 'Class::MOP::Mixin::HasMethods';
80572233 24
d2782813 25Class::MOP::MiniTrait::apply(__PACKAGE__, 'Moose::Meta::Object::Trait');
26
fb1e11d5 27## ------------------------------------------------------------------
28## NOTE:
29## I normally don't do this, but I am doing
30## a whole bunch of meta-programmin in this
31## module, so it just makes sense. For a clearer
d03bd989 32## picture of what is going on in the next
33## several lines of code, look at the really
fb1e11d5 34## big comment at the end of this file (right
35## before the POD).
36## - SL
37## ------------------------------------------------------------------
80572233 38
21716c07 39my $META = __PACKAGE__->meta;
40
41## ------------------------------------------------------------------
42## attributes ...
e185c027 43
21716c07 44# NOTE:
45# since roles are lazy, we hold all the attributes
fb1e11d5 46# of the individual role in 'statis' until which
47# time when it is applied to a class. This means
48# keeping a lot of things in hash maps, so we are
21716c07 49# using a little of that meta-programmin' magic
d03bd989 50# here an saving lots of extra typin. And since
fb1e11d5 51# many of these attributes above require similar
52# functionality to support them, so we again use
53# the wonders of meta-programmin' to deliver a
21716c07 54# very compact solution to this normally verbose
55# problem.
56# - SL
57
58foreach my $action (
fb1e11d5 59 {
60 name => 'excluded_roles_map',
61 attr_reader => 'get_excluded_roles_map' ,
21716c07 62 methods => {
fb1e11d5 63 add => 'add_excluded_roles',
55f28f0a 64 get_keys => 'get_excluded_roles_list',
fb1e11d5 65 existence => 'excludes_role',
21716c07 66 }
67 },
fb1e11d5 68 {
69 name => 'required_methods',
21716c07 70 attr_reader => 'get_required_methods_map',
71 methods => {
7c62cb0a 72 remove => 'remove_required_methods',
73 get_values => 'get_required_method_list',
74 existence => 'requires_method',
21716c07 75 }
d03bd989 76 },
21716c07 77) {
fb1e11d5 78
21716c07 79 my $attr_reader = $action->{attr_reader};
80 my $methods = $action->{methods};
fb1e11d5 81
82 # create the attribute
83 $META->add_attribute($action->{name} => (
84 reader => $attr_reader,
85 default => sub { {} }
86 ));
87
88 # create some helper methods
21716c07 89 $META->add_method($methods->{add} => sub {
90 my ($self, @values) = @_;
fb1e11d5 91 $self->$attr_reader->{$_} = undef foreach @values;
21716c07 92 }) if exists $methods->{add};
fb1e11d5 93
55f28f0a 94 $META->add_method($methods->{get_keys} => sub {
21716c07 95 my ($self) = @_;
fb1e11d5 96 keys %{$self->$attr_reader};
55f28f0a 97 }) if exists $methods->{get_keys};
fb1e11d5 98
8a0bfed9 99 $META->add_method($methods->{get_values} => sub {
100 my ($self) = @_;
101 values %{$self->$attr_reader};
102 }) if exists $methods->{get_values};
103
21716c07 104 $META->add_method($methods->{get} => sub {
105 my ($self, $name) = @_;
fb1e11d5 106 $self->$attr_reader->{$name}
107 }) if exists $methods->{get};
108
21716c07 109 $META->add_method($methods->{existence} => sub {
110 my ($self, $name) = @_;
fb1e11d5 111 exists $self->$attr_reader->{$name} ? 1 : 0;
112 }) if exists $methods->{existence};
113
21716c07 114 $META->add_method($methods->{remove} => sub {
115 my ($self, @values) = @_;
116 delete $self->$attr_reader->{$_} foreach @values;
fb1e11d5 117 }) if exists $methods->{remove};
21716c07 118}
d79e62fd 119
b05518b2 120$META->add_attribute(
121 'method_metaclass',
122 reader => 'method_metaclass',
123 default => 'Moose::Meta::Role::Method',
124);
125
77ed8b8d 126$META->add_attribute(
127 'required_method_metaclass',
128 reader => 'required_method_metaclass',
129 default => 'Moose::Meta::Role::Method::Required',
130);
131
eec8ca8a 132$META->add_attribute(
bb153262 133 'conflicting_method_metaclass',
134 reader => 'conflicting_method_metaclass',
135 default => 'Moose::Meta::Role::Method::Conflicting',
eec8ca8a 136);
137
07de7559 138$META->add_attribute(
139 'application_to_class_class',
140 reader => 'application_to_class_class',
141 default => 'Moose::Meta::Role::Application::ToClass',
142);
143
144$META->add_attribute(
145 'application_to_role_class',
146 reader => 'application_to_role_class',
147 default => 'Moose::Meta::Role::Application::ToRole',
148);
149
150$META->add_attribute(
151 'application_to_instance_class',
152 reader => 'application_to_instance_class',
153 default => 'Moose::Meta::Role::Application::ToInstance',
154);
155
d037bb62 156$META->add_attribute(
157 'applied_attribute_metaclass',
158 reader => 'applied_attribute_metaclass',
159 default => 'Moose::Meta::Attribute',
160);
161
f785aad8 162# More or less copied from Moose::Meta::Class
163sub initialize {
164 my $class = shift;
165 my $pkg = shift;
6f73c555 166
167 if (defined(my $meta = Class::MOP::get_metaclass_by_name($pkg))) {
168 return $meta;
169 }
170
171 my %options = @_;
172
173 my $meta = $class->SUPER::initialize(
f785aad8 174 $pkg,
175 'attribute_metaclass' => 'Moose::Meta::Role::Attribute',
6f73c555 176 %options,
177 );
178
179 Class::MOP::weaken_metaclass($pkg) if $options{weaken};
180
181 return $meta;
f785aad8 182}
80572233 183
f785aad8 184sub reinitialize {
21716c07 185 my $self = shift;
f785aad8 186 my $pkg = shift;
187
188 my $meta = blessed $pkg ? $pkg : Class::MOP::class_of($pkg);
189
190 my %existing_classes;
191 if ($meta) {
192 %existing_classes = map { $_ => $meta->$_() } qw(
193 attribute_metaclass
194 method_metaclass
195 wrapped_method_metaclass
196 required_method_metaclass
197 conflicting_method_metaclass
198 application_to_class_class
199 application_to_role_class
200 application_to_instance_class
d037bb62 201 applied_attribute_metaclass
f785aad8 202 );
70ea9161 203 }
f785aad8 204
6f73c555 205 my %options = @_;
206 $options{weaken} = Class::MOP::metaclass_is_weak($meta->name)
207 if !exists $options{weaken}
208 && blessed($meta)
209 && $meta->isa('Moose::Meta::Role');
210
6feff4da 211 # don't need to remove generated metaobjects here yet, since we don't
212 # yet generate anything in roles. this may change in the future though...
213 # keep an eye on that
214 my $new_meta = $self->SUPER::reinitialize(
f785aad8 215 $pkg,
216 %existing_classes,
6f73c555 217 %options,
f785aad8 218 );
6feff4da 219 $new_meta->_restore_metaobjects_from($meta)
220 if $meta && $meta->isa('Moose::Meta::Role');
221 return $new_meta;
222}
223
224sub _restore_metaobjects_from {
225 my $self = shift;
226 my ($old_meta) = @_;
227
228 $self->_restore_metamethods_from($old_meta);
229 $self->_restore_metaattributes_from($old_meta);
f785aad8 230}
231
232sub add_attribute {
233 my $self = shift;
234
235 if (blessed $_[0] && ! $_[0]->isa('Moose::Meta::Role::Attribute') ) {
236 my $class = ref $_[0];
237 Moose->throw_error( "Cannot add a $class as an attribute to a role" );
21716c07 238 }
8c063f8e 239 elsif (!blessed($_[0]) && defined($_[0]) && $_[0] =~ /^\+(.*)/) {
576cd474 240 Moose->throw_error( "has '+attr' is not supported in roles" );
241 }
f785aad8 242
243 return $self->SUPER::add_attribute(@_);
244}
245
246sub _attach_attribute {
247 my ( $self, $attribute ) = @_;
248
249 $attribute->attach_to_role($self);
21716c07 250}
e185c027 251
16d721b3 252sub add_required_methods {
253 my $self = shift;
254
255 for (@_) {
256 my $method = $_;
c9d7e396 257 if (!blessed($method)) {
16d721b3 258 $method = $self->required_method_metaclass->new(
259 name => $method,
260 );
261 }
262 $self->get_required_methods_map->{$method->name} = $method;
263 }
264}
265
bb153262 266sub add_conflicting_method {
09eeab06 267 my $self = shift;
268
269 my $method;
270 if (@_ == 1 && blessed($_[0])) {
271 $method = shift;
272 }
273 else {
bb153262 274 $method = $self->conflicting_method_metaclass->new(@_);
09eeab06 275 }
276
277 $self->add_required_methods($method);
278}
279
21716c07 280## ------------------------------------------------------------------
281## method modifiers
282
21716c07 283# NOTE:
fb1e11d5 284# the before/around/after method modifiers are
21716c07 285# stored by name, but there can be many methods
286# then associated with that name. So again we have
287# lots of similar functionality, so we can do some
288# meta-programmin' and save some time.
289# - SL
290
291foreach my $modifier_type (qw[ before around after ]) {
fb1e11d5 292
293 my $attr_reader = "get_${modifier_type}_method_modifiers_map";
d03bd989 294
fb1e11d5 295 # create the attribute ...
296 $META->add_attribute("${modifier_type}_method_modifiers" => (
297 reader => $attr_reader,
298 default => sub { {} }
d03bd989 299 ));
fb1e11d5 300
301 # and some helper methods ...
21716c07 302 $META->add_method("get_${modifier_type}_method_modifiers" => sub {
303 my ($self, $method_name) = @_;
fb1e11d5 304 #return () unless exists $self->$attr_reader->{$method_name};
d9847263 305 my $mm = $self->$attr_reader->{$method_name};
306 $mm ? @$mm : ();
21716c07 307 });
fb1e11d5 308
21716c07 309 $META->add_method("has_${modifier_type}_method_modifiers" => sub {
310 my ($self, $method_name) = @_;
311 # NOTE:
fb1e11d5 312 # for now we assume that if it exists,..
21716c07 313 # it has at least one modifier in it
314 (exists $self->$attr_reader->{$method_name}) ? 1 : 0;
fb1e11d5 315 });
316
21716c07 317 $META->add_method("add_${modifier_type}_method_modifier" => sub {
318 my ($self, $method_name, $method) = @_;
fb1e11d5 319
320 $self->$attr_reader->{$method_name} = []
21716c07 321 unless exists $self->$attr_reader->{$method_name};
fb1e11d5 322
21716c07 323 my $modifiers = $self->$attr_reader->{$method_name};
fb1e11d5 324
21716c07 325 # NOTE:
fb1e11d5 326 # check to see that we aren't adding the
327 # same code twice. We err in favor of the
21716c07 328 # first on here, this may not be as expected
329 foreach my $modifier (@{$modifiers}) {
330 return if $modifier == $method;
331 }
fb1e11d5 332
21716c07 333 push @{$modifiers} => $method;
334 });
fb1e11d5 335
21716c07 336}
1331430a 337
21716c07 338## ------------------------------------------------------------------
339## override method mofidiers
0558683c 340
fb1e11d5 341$META->add_attribute('override_method_modifiers' => (
342 reader => 'get_override_method_modifiers_map',
343 default => sub { {} }
344));
345
21716c07 346# NOTE:
fb1e11d5 347# these are a little different because there
21716c07 348# can only be one per name, whereas the other
349# method modifiers can have multiples.
350# - SL
0558683c 351
21716c07 352sub add_override_method_modifier {
353 my ($self, $method_name, $method) = @_;
354 (!$self->has_method($method_name))
c245d69b 355 || Moose->throw_error("Cannot add an override of method '$method_name' " .
4c0b3599 356 "because there is a local version of '$method_name'");
fb1e11d5 357 $self->get_override_method_modifiers_map->{$method_name} = $method;
21716c07 358}
0558683c 359
21716c07 360sub has_override_method_modifier {
361 my ($self, $method_name) = @_;
362 # NOTE:
fb1e11d5 363 # for now we assume that if it exists,..
21716c07 364 # it has at least one modifier in it
fb1e11d5 365 (exists $self->get_override_method_modifiers_map->{$method_name}) ? 1 : 0;
21716c07 366}
0558683c 367
21716c07 368sub get_override_method_modifier {
369 my ($self, $method_name) = @_;
fb1e11d5 370 $self->get_override_method_modifiers_map->{$method_name};
21716c07 371}
0558683c 372
21716c07 373## general list accessor ...
80572233 374
21716c07 375sub get_method_modifier_list {
376 my ($self, $modifier_type) = @_;
fb1e11d5 377 my $accessor = "get_${modifier_type}_method_modifiers_map";
21716c07 378 keys %{$self->$accessor};
379}
e185c027 380
699a2e32 381sub _meta_method_class { 'Moose::Meta::Method::Meta' }
e606ae5f 382
21716c07 383## ------------------------------------------------------------------
80572233 384## subroles
385
278ca49c 386$META->add_attribute('roles' => (
21716c07 387 reader => 'get_roles',
388 default => sub { [] }
389));
390
80572233 391sub add_role {
392 my ($self, $role) = @_;
393 (blessed($role) && $role->isa('Moose::Meta::Role'))
c245d69b 394 || Moose->throw_error("Roles must be instances of Moose::Meta::Role");
80572233 395 push @{$self->get_roles} => $role;
e606ae5f 396 $self->reset_package_cache_flag;
80572233 397}
398
b8aeb4dc 399sub calculate_all_roles {
400 my $self = shift;
401 my %seen;
fb1e11d5 402 grep {
403 !$seen{$_->name}++
404 } ($self, map {
405 $_->calculate_all_roles
406 } @{ $self->get_roles });
b8aeb4dc 407}
408
80572233 409sub does_role {
560c498d 410 my ($self, $role) = @_;
411 (defined $role)
c245d69b 412 || Moose->throw_error("You must supply a role name to look for");
560c498d 413 my $role_name = blessed $role ? $role->name : $role;
bdabd620 414 # if we are it,.. then return true
415 return 1 if $role_name eq $self->name;
416 # otherwise.. check our children
80572233 417 foreach my $role (@{$self->get_roles}) {
bdabd620 418 return 1 if $role->does_role($role_name);
80572233 419 }
420 return 0;
421}
422
1db8ecc7 423sub find_method_by_name { (shift)->get_method(@_) }
093b12c2 424
21716c07 425## ------------------------------------------------------------------
fb1e11d5 426## role construction
21716c07 427## ------------------------------------------------------------------
e185c027 428
21716c07 429sub apply {
f315aab3 430 my ($self, $other, %args) = @_;
bca01282 431
432 (blessed($other))
c245d69b 433 || Moose->throw_error("You must pass in an blessed instance");
d03bd989 434
07de7559 435 my $application_class;
1c9db35c 436 if ($other->isa('Moose::Meta::Role')) {
07de7559 437 $application_class = $self->application_to_role_class;
1c9db35c 438 }
439 elsif ($other->isa('Moose::Meta::Class')) {
07de7559 440 $application_class = $self->application_to_class_class;
d03bd989 441 }
1c9db35c 442 else {
07de7559 443 $application_class = $self->application_to_instance_class;
d03bd989 444 }
07de7559 445
446 Class::MOP::load_class($application_class);
4c52e860 447
448 my $deprecation_check = 0;
449
450 if ( exists $args{excludes} && !exists $args{'-excludes'} ) {
451 $args{'-excludes'} = delete $args{excludes};
452 $deprecation_check = 1;
453 }
454 if ( exists $args{alias} && !exists $args{'-alias'} ) {
455 $args{'-alias'} = delete $args{alias};
456 $deprecation_check = 1;
457 }
458
459 if ( $deprecation_check ) {
4c52e860 460 Moose::Deprecated::deprecated(
461 feature => 'alias or excludes',
462 message =>
463 'The alias and excludes options for role application'.
464 ' have been renamed -alias and -excludes'.
465 " (${\$other->name} is consuming ${\$self->name}".
466 " - do you need to upgrade ${\$other->name}?)"
467 );
468 }
469
470 if ( exists $args{'-excludes'} ) {
4c52e860 471 # I wish we had coercion here :)
472 $args{'-excludes'} = (
473 ref $args{'-excludes'} eq 'ARRAY'
474 ? $args{'-excludes'}
475 : [ $args{'-excludes'} ]
476 );
477 }
478
f315aab3 479 return $application_class->new(%args)->apply($self, $other, \%args);
0558683c 480}
481
4701ceff 482sub composition_class_roles { }
483
21716c07 484sub combine {
a4e516f6 485 my ($class, @role_specs) = @_;
d03bd989 486
d03bd989 487 require Moose::Meta::Role::Composite;
488
28412c0b 489 my (@roles, %role_params);
490 while (@role_specs) {
560c498d 491 my ($role, $params) = @{ splice @role_specs, 0, 1 };
492 my $requested_role
493 = blessed $role
494 ? $role
495 : Class::MOP::class_of($role);
31d96c3e 496
6bdef412 497 my $actual_role = $requested_role->_role_for_combination($params);
31d96c3e 498 push @roles => $actual_role;
499
28412c0b 500 next unless defined $params;
31d96c3e 501 $role_params{$actual_role->name} = $params;
28412c0b 502 }
d03bd989 503
fb1e11d5 504 my $c = Moose::Meta::Role::Composite->new(roles => \@roles);
7071e2cb 505 return $c->apply_params(\%role_params);
0558683c 506}
507
6bdef412 508sub _role_for_combination {
436d7a28 509 my ($self, $params) = @_;
510 return $self;
511}
512
b6a00b82 513sub create {
2d5f3fab 514 my ( $role, $package_name, %options ) = @_;
b6a00b82 515
2d5f3fab 516 $options{package} = $package_name;
b6a00b82 517
518 (ref $options{attributes} eq 'HASH')
519 || confess "You must pass a HASH ref of attributes"
520 if exists $options{attributes};
521
522 (ref $options{methods} eq 'HASH')
523 || confess "You must pass a HASH ref of methods"
524 if exists $options{methods};
525
2937ed18 526 $options{meta_name} = 'meta'
527 unless exists $options{meta_name};
528
2d5f3fab 529 my (%initialize_options) = %options;
b6a00b82 530 delete @initialize_options{qw(
531 package
532 attributes
533 methods
2937ed18 534 meta_name
b6a00b82 535 version
536 authority
537 )};
538
539 my $meta = $role->initialize( $package_name => %initialize_options );
540
6a4a7c31 541 $meta->_instantiate_module( $options{version}, $options{authority} );
542
2937ed18 543 $meta->_add_meta_method($options{meta_name})
544 if defined $options{meta_name};
b6a00b82 545
546 if (exists $options{attributes}) {
547 foreach my $attribute_name (keys %{$options{attributes}}) {
548 my $attr = $options{attributes}->{$attribute_name};
f785aad8 549 $meta->add_attribute(
550 $attribute_name => blessed $attr ? $attr : %{$attr} );
b6a00b82 551 }
552 }
553
554 if (exists $options{methods}) {
555 foreach my $method_name (keys %{$options{methods}}) {
556 $meta->add_method($method_name, $options{methods}->{$method_name});
557 }
558 }
559
560 return $meta;
561}
562
c23885b1 563sub consumers {
564 my $self = shift;
565 my @consumers;
566 for my $meta (Class::MOP::get_all_metaclass_instances) {
567 next if $meta->name eq $self->name;
568 next unless $meta->isa('Moose::Meta::Class')
569 || $meta->isa('Moose::Meta::Role');
570 push @consumers, $meta->name
571 if $meta->does_role($self->name);
572 }
573 return @consumers;
574}
575
c9ee520d 576# anonymous roles. most of it is copied straight out of Class::MOP::Class.
577# an intrepid hacker might find great riches if he unifies this code with that
578# code in Class::MOP::Module or Class::MOP::Package
579{
580 # NOTE:
581 # this should be sufficient, if you have a
582 # use case where it is not, write a test and
583 # I will change it.
584 my $ANON_ROLE_SERIAL = 0;
585
586 # NOTE:
587 # we need a sufficiently annoying prefix
588 # this should suffice for now, this is
589 # used in a couple of places below, so
590 # need to put it up here for now.
591 my $ANON_ROLE_PREFIX = 'Moose::Meta::Role::__ANON__::SERIAL::';
592
593 sub is_anon_role {
594 my $self = shift;
595 no warnings 'uninitialized';
596 $self->name =~ /^$ANON_ROLE_PREFIX/;
597 }
598
599 sub create_anon_role {
600 my ($role, %options) = @_;
6f73c555 601 $options{weaken} = 1 unless exists $options{weaken};
c9ee520d 602 my $package_name = $ANON_ROLE_PREFIX . ++$ANON_ROLE_SERIAL;
603 return $role->create($package_name, %options);
604 }
605
606 # NOTE:
607 # this will only get called for
608 # anon-roles, all other calls
609 # are assumed to occur during
610 # global destruction and so don't
611 # really need to be handled explicitly
612 sub DESTROY {
613 my $self = shift;
614
963c24e1 615 return if in_global_destruction(); # it'll happen soon anyway and this just makes things more complicated
c9ee520d 616
617 no warnings 'uninitialized';
618 return unless $self->name =~ /^$ANON_ROLE_PREFIX/;
619
620 # XXX: is this necessary for us? I don't understand what it's doing
621 # -sartak
622
623 # Moose does a weird thing where it replaces the metaclass for
624 # class when fixing metaclass incompatibility. In that case,
625 # we don't want to clean out the namespace now. We can detect
626 # that because Moose will explicitly update the singleton
627 # cache in Class::MOP.
628 #my $current_meta = Class::MOP::get_metaclass_by_name($self->name);
629 #return if $current_meta ne $self;
630
631 my ($serial_id) = ($self->name =~ /^$ANON_ROLE_PREFIX(\d+)/);
632 no strict 'refs';
633 foreach my $key (keys %{$ANON_ROLE_PREFIX . $serial_id}) {
634 delete ${$ANON_ROLE_PREFIX . $serial_id}{$key};
635 }
636 delete ${'main::' . $ANON_ROLE_PREFIX}{$serial_id . '::'};
637 }
638}
639
fb1e11d5 640#####################################################################
641## NOTE:
d03bd989 642## This is Moose::Meta::Role as defined by Moose (plus the use of
643## MooseX::AttributeHelpers module). It is here as a reference to
fb1e11d5 644## make it easier to see what is happening above with all the meta
645## programming. - SL
646#####################################################################
647#
648# has 'roles' => (
a40b446a 649# metaclass => 'Array',
fb1e11d5 650# reader => 'get_roles',
764a7831 651# isa => 'ArrayRef[Moose::Meta::Role]',
fb1e11d5 652# default => sub { [] },
653# provides => {
654# 'push' => 'add_role',
655# }
656# );
d03bd989 657#
fb1e11d5 658# has 'excluded_roles_map' => (
a40b446a 659# metaclass => 'Hash',
fb1e11d5 660# reader => 'get_excluded_roles_map',
661# isa => 'HashRef[Str]',
662# provides => {
663# # Not exactly set, cause it sets multiple
664# 'set' => 'add_excluded_roles',
665# 'keys' => 'get_excluded_roles_list',
666# 'exists' => 'excludes_role',
667# }
668# );
d03bd989 669#
fb1e11d5 670# has 'required_methods' => (
a40b446a 671# metaclass => 'Hash',
fb1e11d5 672# reader => 'get_required_methods_map',
72264f10 673# isa => 'HashRef[Moose::Meta::Role::Method::Required]',
d03bd989 674# provides => {
675# # not exactly set, or delete since it works for multiple
fb1e11d5 676# 'set' => 'add_required_methods',
677# 'delete' => 'remove_required_methods',
678# 'keys' => 'get_required_method_list',
d03bd989 679# 'exists' => 'requires_method',
fb1e11d5 680# }
681# );
d03bd989 682#
683# # the before, around and after modifiers are
684# # HASH keyed by method-name, with ARRAY of
fb1e11d5 685# # CODE refs to apply in that order
d03bd989 686#
fb1e11d5 687# has 'before_method_modifiers' => (
a40b446a 688# metaclass => 'Hash',
fb1e11d5 689# reader => 'get_before_method_modifiers_map',
690# isa => 'HashRef[ArrayRef[CodeRef]]',
691# provides => {
692# 'keys' => 'get_before_method_modifiers',
d03bd989 693# 'exists' => 'has_before_method_modifiers',
694# # This actually makes sure there is an
fb1e11d5 695# # ARRAY at the given key, and pushed onto
696# # it. It also checks for duplicates as well
d03bd989 697# # 'add' => 'add_before_method_modifier'
698# }
fb1e11d5 699# );
d03bd989 700#
fb1e11d5 701# has 'after_method_modifiers' => (
a40b446a 702# metaclass => 'Hash',
fb1e11d5 703# reader =>'get_after_method_modifiers_map',
704# isa => 'HashRef[ArrayRef[CodeRef]]',
705# provides => {
706# 'keys' => 'get_after_method_modifiers',
d03bd989 707# 'exists' => 'has_after_method_modifiers',
708# # This actually makes sure there is an
fb1e11d5 709# # ARRAY at the given key, and pushed onto
d03bd989 710# # it. It also checks for duplicates as well
711# # 'add' => 'add_after_method_modifier'
712# }
fb1e11d5 713# );
d03bd989 714#
fb1e11d5 715# has 'around_method_modifiers' => (
a40b446a 716# metaclass => 'Hash',
fb1e11d5 717# reader =>'get_around_method_modifiers_map',
718# isa => 'HashRef[ArrayRef[CodeRef]]',
719# provides => {
720# 'keys' => 'get_around_method_modifiers',
d03bd989 721# 'exists' => 'has_around_method_modifiers',
722# # This actually makes sure there is an
fb1e11d5 723# # ARRAY at the given key, and pushed onto
d03bd989 724# # it. It also checks for duplicates as well
725# # 'add' => 'add_around_method_modifier'
726# }
fb1e11d5 727# );
d03bd989 728#
fb1e11d5 729# # override is similar to the other modifiers
730# # except that it is not an ARRAY of code refs
731# # but instead just a single name->code mapping
d03bd989 732#
fb1e11d5 733# has 'override_method_modifiers' => (
a40b446a 734# metaclass => 'Hash',
fb1e11d5 735# reader =>'get_override_method_modifiers_map',
d03bd989 736# isa => 'HashRef[CodeRef]',
fb1e11d5 737# provides => {
738# 'keys' => 'get_override_method_modifier',
d03bd989 739# 'exists' => 'has_override_method_modifier',
740# 'add' => 'add_override_method_modifier', # checks for local method ..
fb1e11d5 741# }
742# );
d03bd989 743#
fb1e11d5 744#####################################################################
745
746
e185c027 7471;
748
ad46f524 749# ABSTRACT: The Moose Role metaclass
750
e185c027 751__END__
752
753=pod
754
e185c027 755=head1 DESCRIPTION
756
705d4cfd 757This class is a subclass of L<Class::MOP::Module> that provides
758additional Moose-specific functionality.
759
760It's API looks a lot like L<Moose::Meta::Class>, but internally it
761implements many things differently. This may change in the future.
79592a54 762
cf3bb5c5 763=head1 INHERITANCE
764
765C<Moose::Meta::Role> is a subclass of L<Class::MOP::Module>.
766
e185c027 767=head1 METHODS
768
705d4cfd 769=head2 Construction
770
e185c027 771=over 4
772
705d4cfd 773=item B<< Moose::Meta::Role->initialize($role_name) >>
e185c027 774
705d4cfd 775This method creates a new role object with the provided name.
e185c027 776
705d4cfd 777=item B<< Moose::Meta::Role->combine( [ $role => { ... } ], [ $role ], ... ) >>
78cd1d3b 778
705d4cfd 779This method accepts a list of array references. Each array reference
560c498d 780should contain a role name or L<Moose::Meta::Role> object as its first element. The second element is
c8b8d92f 781an optional hash reference. The hash reference can contain C<-excludes>
782and C<-alias> keys to control how methods are composed from the role.
e606ae5f 783
705d4cfd 784The return value is a new L<Moose::Meta::Role::Composite> that
785represents the combined roles.
db1ab48d 786
4701ceff 787=item B<< $metarole->composition_class_roles >>
788
789When combining multiple roles using C<combine>, this method is used to obtain a
790list of role names to be applied to the L<Moose::Meta::Role::Composite>
791instance returned by C<combine>. The default implementation returns an empty
792list. Extensions that need to hook into role combination may wrap this method
793to return additional role names.
794
705d4cfd 795=item B<< Moose::Meta::Role->create($name, %options) >>
e185c027 796
705d4cfd 797This method is identical to the L<Moose::Meta::Class> C<create>
798method.
799
800=item B<< Moose::Meta::Role->create_anon_role >>
e185c027 801
705d4cfd 802This method is identical to the L<Moose::Meta::Class>
803C<create_anon_class> method.
e185c027 804
705d4cfd 805=item B<< $metarole->is_anon_role >>
e185c027 806
705d4cfd 807Returns true if the role is an anonymous role.
e185c027 808
c23885b1 809=item B<< $metarole->consumers >>
810
811Returns a list of names of classes and roles which consume this role.
812
e185c027 813=back
814
705d4cfd 815=head2 Role application
816
e185c027 817=over 4
818
705d4cfd 819=item B<< $metarole->apply( $thing, @options ) >>
80572233 820
705d4cfd 821This method applies a role to the given C<$thing>. That can be another
822L<Moose::Meta::Role>, object, a L<Moose::Meta::Class> object, or a
823(non-meta) object instance.
80572233 824
705d4cfd 825The options are passed directly to the constructor for the appropriate
826L<Moose::Meta::Role::Application> subclass.
80572233 827
d05235e1 828Note that this will apply the role even if the C<$thing> in question already
829C<does> this role. L<Moose::Util/does_role> is a convenient wrapper for
830finding out if role application is necessary.
831
80572233 832=back
833
705d4cfd 834=head2 Roles and other roles
835
80572233 836=over 4
837
705d4cfd 838=item B<< $metarole->get_roles >>
d79e62fd 839
705d4cfd 840This returns an array reference of roles which this role does. This
841list may include duplicates.
d79e62fd 842
705d4cfd 843=item B<< $metarole->calculate_all_roles >>
d79e62fd 844
705d4cfd 845This returns a I<unique> list of all roles that this role does, and
846all the roles that its roles do.
d79e62fd 847
560c498d 848=item B<< $metarole->does_role($role) >>
2b14ac61 849
560c498d 850Given a role I<name> or L<Moose::Meta::Role> object, returns true if this role
851does the given role.
d79e62fd 852
705d4cfd 853=item B<< $metarole->add_role($role) >>
d79e62fd 854
705d4cfd 855Given a L<Moose::Meta::Role> object, this adds the role to the list of
856roles that the role does.
68efb014 857
705d4cfd 858=item B<< $metarole->get_excluded_roles_list >>
be4427d0 859
705d4cfd 860Returns a list of role names which this role excludes.
e185c027 861
705d4cfd 862=item B<< $metarole->excludes_role($role_name) >>
e185c027 863
705d4cfd 864Given a role I<name>, returns true if this role excludes the named
865role.
e606ae5f 866
705d4cfd 867=item B<< $metarole->add_excluded_roles(@role_names) >>
e606ae5f 868
705d4cfd 869Given one or more role names, adds those roles to the list of excluded
870roles.
bdabd620 871
705d4cfd 872=back
e185c027 873
705d4cfd 874=head2 Methods
093b12c2 875
705d4cfd 876The methods for dealing with a role's methods are all identical in API
877and behavior to the same methods in L<Class::MOP::Class>.
638853cb 878
705d4cfd 879=over 4
53dd42d8 880
705d4cfd 881=item B<< $metarole->method_metaclass >>
e185c027 882
705d4cfd 883Returns the method metaclass name for the role. This defaults to
884L<Moose::Meta::Role::Method>.
e185c027 885
705d4cfd 886=item B<< $metarole->get_method($name) >>
e185c027 887
705d4cfd 888=item B<< $metarole->has_method($name) >>
e185c027 889
705d4cfd 890=item B<< $metarole->add_method( $name, $body ) >>
e185c027 891
705d4cfd 892=item B<< $metarole->get_method_list >>
e185c027 893
705d4cfd 894=item B<< $metarole->find_method_by_name($name) >>
895
896These methods are all identical to the methods of the same name in
8f6cbfcd 897L<Class::MOP::Package>
e185c027 898
899=back
900
705d4cfd 901=head2 Attributes
902
903As with methods, the methods for dealing with a role's attribute are
904all identical in API and behavior to the same methods in
905L<Class::MOP::Class>.
906
907However, attributes stored in this class are I<not> stored as
908objects. Rather, the attribute definition is stored as a hash
909reference. When a role is composed into a class, this hash reference
910is passed directly to the metaclass's C<add_attribute> method.
911
912This is quite likely to change in the future.
913
e185c027 914=over 4
915
705d4cfd 916=item B<< $metarole->get_attribute($attribute_name) >>
917
918=item B<< $metarole->has_attribute($attribute_name) >>
1331430a 919
705d4cfd 920=item B<< $metarole->get_attribute_list >>
1331430a 921
705d4cfd 922=item B<< $metarole->add_attribute($name, %options) >>
1331430a 923
705d4cfd 924=item B<< $metarole->remove_attribute($attribute_name) >>
1331430a 925
926=back
927
705d4cfd 928=head2 Required methods
929
0558683c 930=over 4
931
705d4cfd 932=item B<< $metarole->get_required_method_list >>
0558683c 933
705d4cfd 934Returns the list of methods required by the role.
0558683c 935
705d4cfd 936=item B<< $metarole->requires_method($name) >>
0558683c 937
705d4cfd 938Returns true if the role requires the named method.
0558683c 939
0ecff16b 940=item B<< $metarole->add_required_methods(@names) >>
0558683c 941
b3c1586a 942Adds the named methods to the role's list of required methods.
0558683c 943
705d4cfd 944=item B<< $metarole->remove_required_methods(@names) >>
0558683c 945
2dda1d28 946Removes the named methods from the role's list of required methods.
0558683c 947
bb153262 948=item B<< $metarole->add_conflicting_method(%params) >>
09eeab06 949
bb153262 950Instantiate the parameters as a L<Moose::Meta::Role::Method::Conflicting>
09eeab06 951object, then add it to the required method list.
952
705d4cfd 953=back
954
955=head2 Method modifiers
0558683c 956
fa907f2e 957These methods act like their counterparts in L<Class::MOP::Class> and
705d4cfd 958L<Moose::Meta::Class>.
959
960However, method modifiers are simply stored internally, and are not
961applied until the role itself is applied to a class.
0558683c 962
963=over 4
964
705d4cfd 965=item B<< $metarole->add_after_method_modifier($method_name, $method) >>
0558683c 966
705d4cfd 967=item B<< $metarole->add_around_method_modifier($method_name, $method) >>
0558683c 968
705d4cfd 969=item B<< $metarole->add_before_method_modifier($method_name, $method) >>
0558683c 970
705d4cfd 971=item B<< $metarole->add_override_method_modifier($method_name, $method) >>
0558683c 972
705d4cfd 973These methods all add an appropriate modifier to the internal list of
974modifiers.
0558683c 975
705d4cfd 976=item B<< $metarole->has_after_method_modifiers >>
0558683c 977
705d4cfd 978=item B<< $metarole->has_around_method_modifiers >>
979
980=item B<< $metarole->has_before_method_modifiers >>
981
982=item B<< $metarole->has_override_method_modifier >>
0558683c 983
705d4cfd 984Return true if the role has any modifiers of the given type.
0558683c 985
705d4cfd 986=item B<< $metarole->get_after_method_modifiers($method_name) >>
0558683c 987
705d4cfd 988=item B<< $metarole->get_around_method_modifiers($method_name) >>
0558683c 989
705d4cfd 990=item B<< $metarole->get_before_method_modifiers($method_name) >>
0558683c 991
705d4cfd 992Given a method name, returns a list of the appropriate modifiers for
993that method.
994
995=item B<< $metarole->get_override_method_modifier($method_name) >>
996
997Given a method name, returns the override method modifier for that
998method, if it has one.
0558683c 999
1000=back
1001
705d4cfd 1002=head2 Introspection
505065c4 1003
705d4cfd 1004=over 4
505065c4 1005
705d4cfd 1006=item B<< Moose::Meta::Role->meta >>
505065c4 1007
705d4cfd 1008This will return a L<Class::MOP::Class> instance for this class.
505065c4 1009
1010=back
1011
e185c027 1012=head1 BUGS
1013
d4048ef3 1014See L<Moose/BUGS> for details on reporting bugs.
e185c027 1015
b8aeb4dc 1016=cut