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