X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FRole.pm;h=3cb69a4300e7c8817bbea9c2d6b13a6fddf11ed3;hb=6d0815b59db07f71cdbfd978ed6f574e57e2b3ea;hp=e4289ce4e68955f3c7f899a55e229664cc5e3cfa;hpb=a4e516f663c16c559013862e7f51b0aec4fc3e5b;p=gitmo%2FMoose.git diff --git a/lib/Moose/Role.pm b/lib/Moose/Role.pm index e4289ce..3cb69a4 100644 --- a/lib/Moose/Role.pm +++ b/lib/Moose/Role.pm @@ -1,190 +1,142 @@ - package Moose::Role; - use strict; use warnings; use Scalar::Util 'blessed'; -use Carp 'confess'; -use Sub::Name 'subname'; +use Carp 'croak'; -use Data::OptList; use Sub::Exporter; -our $VERSION = '0.07'; +our $VERSION = '0.93'; +$VERSION = eval $VERSION; our $AUTHORITY = 'cpan:STEVAN'; -use Moose (); +use Moose (); +use Moose::Util (); +use Moose::Exporter; use Moose::Meta::Role; use Moose::Util::TypeConstraints; -{ - my ( $CALLER, %METAS ); +sub extends { + croak "Roles do not support 'extends' (you can use 'with' to specialize a role)"; +} - sub _find_meta { - my $role = $CALLER; +sub with { + Moose::Util::apply_all_roles( shift, @_ ); +} - return $METAS{$role} if exists $METAS{$role}; +sub requires { + my $meta = shift; + croak "Must specify at least one method" unless @_; + $meta->add_required_methods(@_); +} - # make a subtype for each Moose class - subtype $role - => as 'Role' - => where { $_->does($role) } - => optimize_as { blessed($_[0]) && $_[0]->can('does') && $_[0]->does($role) } - unless find_type_constraint($role); +sub excludes { + my $meta = shift; + croak "Must specify at least one role" unless @_; + $meta->add_excluded_roles(@_); +} - my $meta; - if ($role->can('meta')) { - $meta = $role->meta(); - (blessed($meta) && $meta->isa('Moose::Meta::Role')) - || confess "You already have a &meta function, but it does not return a Moose::Meta::Role"; - } - else { - $meta = Moose::Meta::Role->initialize($role); - $meta->alias_method('meta' => sub { $meta }); - } +sub has { + my $meta = shift; + my $name = shift; + croak 'Usage: has \'name\' => ( key => value, ... )' if @_ == 1; + my %options = ( definition_context => Moose::Util::_caller_info(), @_ ); + my $attrs = ( ref($name) eq 'ARRAY' ) ? $name : [ ($name) ]; + $meta->add_attribute( $_, %options ) for @$attrs; +} - return $METAS{$role} = $meta; +sub _add_method_modifier { + my $type = shift; + my $meta = shift; + my $code = pop @_; + + for (@_) { + croak "Roles do not currently support " + . ref($_) + . " references for $type method modifiers" + if ref $_; + my $add_method = "add_${type}_method_modifier"; + $meta->$add_method( $_, $code ); } +} +sub before { _add_method_modifier('before', @_) } - my %exports = ( - extends => sub { - my $meta = _find_meta(); - return subname 'Moose::Role::extends' => sub { - confess "Moose::Role does not currently support 'extends'" - }; - }, - with => sub { - my $meta = _find_meta(); - return subname 'Moose::Role::with' => sub (@) { - my (@args) = @_; - confess "Must specify at least one role" unless @args; - - my $roles = Data::OptList::mkopt(\@args); - - #use Data::Dumper; - #warn Dumper $roles; - - Class::MOP::load_class($_->[0]) for @$roles; - - ($_->[0]->can('meta') && $_->[0]->meta->isa('Moose::Meta::Role')) - || confess "You can only consume roles, " . $_->[0] . " is not a Moose role" - foreach @$roles; - - if (scalar @$roles == 1) { - my ($role, $params) = @{$roles->[0]}; - $role->meta->apply($meta, (defined $params ? %$params : ())); - } - else { - Moose::Meta::Role->combine( - @$roles - )->apply($meta); - } - }; - }, - requires => sub { - my $meta = _find_meta(); - return subname 'Moose::Role::requires' => sub (@) { - confess "Must specify at least one method" unless @_; - $meta->add_required_methods(@_); - }; - }, - excludes => sub { - my $meta = _find_meta(); - return subname 'Moose::Role::excludes' => sub (@) { - confess "Must specify at least one role" unless @_; - $meta->add_excluded_roles(@_); - }; - }, - has => sub { - my $meta = _find_meta(); - return subname 'Moose::Role::has' => sub ($;%) { - my ($name, %options) = @_; - $meta->add_attribute($name, %options) - }; - }, - before => sub { - my $meta = _find_meta(); - return subname 'Moose::Role::before' => sub (@&) { - my $code = pop @_; - $meta->add_before_method_modifier($_, $code) for @_; - }; - }, - after => sub { - my $meta = _find_meta(); - return subname 'Moose::Role::after' => sub (@&) { - my $code = pop @_; - $meta->add_after_method_modifier($_, $code) for @_; - }; - }, - around => sub { - my $meta = _find_meta(); - return subname 'Moose::Role::around' => sub (@&) { - my $code = pop @_; - $meta->add_around_method_modifier($_, $code) for @_; - }; - }, - super => sub { - { - no strict 'refs'; - $Moose::SUPER_SLOT{$CALLER} = \*{"${CALLER}::super"}; - } - my $meta = _find_meta(); - return subname 'Moose::Role::super' => sub {}; - }, - override => sub { - my $meta = _find_meta(); - return subname 'Moose::Role::override' => sub ($&) { - my ($name, $code) = @_; - $meta->add_override_method_modifier($name, $code); - }; - }, - inner => sub { - my $meta = _find_meta(); - return subname 'Moose::Role::inner' => sub { - confess "Moose::Role cannot support 'inner'"; - }; - }, - augment => sub { - my $meta = _find_meta(); - return subname 'Moose::Role::augment' => sub { - confess "Moose::Role cannot support 'augment'"; - }; - }, - confess => sub { - return \&Carp::confess; - }, - blessed => sub { - return \&Scalar::Util::blessed; - } - ); +sub after { _add_method_modifier('after', @_) } - my $exporter = Sub::Exporter::build_exporter({ - exports => \%exports, - groups => { - default => [':all'] - } - }); +sub around { _add_method_modifier('around', @_) } - sub import { - $CALLER = - ref $_[1] && defined $_[1]->{into} ? $_[1]->{into} - : ref $_[1] - && defined $_[1]->{into_level} ? caller( $_[1]->{into_level} ) - : caller(); +# see Moose.pm for discussion +sub super { + return unless $Moose::SUPER_BODY; + $Moose::SUPER_BODY->(@Moose::SUPER_ARGS); +} + +sub override { + my $meta = shift; + my ( $name, $code ) = @_; + $meta->add_override_method_modifier( $name, $code ); +} + +sub inner { + croak "Roles cannot support 'inner'"; +} + +sub augment { + croak "Roles cannot support 'augment'"; +} + +Moose::Exporter->setup_import_methods( + with_meta => [ + qw( with requires excludes has before after around override ) + ], + as_is => [ + qw( extends super inner augment ), + \&Carp::confess, + \&Scalar::Util::blessed, + ], +); + +sub init_meta { + shift; + my %args = @_; + + my $role = $args{for_class}; + + unless ($role) { + require Moose; + Moose->throw_error("Cannot call init_meta without specifying a for_class"); + } + my $metaclass = $args{metaclass} || "Moose::Meta::Role"; - strict->import; - warnings->import; + # make a subtype for each Moose class + role_type $role unless find_type_constraint($role); - # we should never export to main - return if $CALLER eq 'main'; + # FIXME copy from Moose.pm + my $meta; + if ($role->can('meta')) { + $meta = $role->meta(); - goto $exporter; - }; + unless ( blessed($meta) && $meta->isa('Moose::Meta::Role') ) { + require Moose; + Moose->throw_error("You already have a &meta function, but it does not return a Moose::Meta::Role"); + } + } + else { + $meta = $metaclass->initialize($role); + $meta->add_method( + 'meta' => sub { + # re-initialize so it inherits properly + $metaclass->initialize( ref($_[0]) || $_[0] ); + } + ); + } + + return $meta; } 1; @@ -223,13 +175,8 @@ Moose::Role - The Moose Role =head1 DESCRIPTION -Role support in Moose is pretty solid at this point. However, the best -documentation is still the the test suite. It is fairly safe to assume Perl 6 -style behavior and then either refer to the test suite, or ask questions on -#moose if something doesn't quite do what you expect. - -We are planning writing some more documentation in the near future, but nothing -is ready yet, sorry. +The concept of roles is documented in L. This document +serves as API documentation. =head1 EXPORTED FUNCTIONS @@ -246,6 +193,9 @@ Moose::Role also offers two role-specific keyword exports: Roles can require that certain methods are implemented by any class which C the role. +Note that attribute accessors also count as methods for the purposes +of satisfying the requirements of a role. + =item B Roles can C other roles, in effect saying "I can never be combined @@ -254,6 +204,53 @@ lightly. =back +=head2 B + +Moose::Role offers a way to remove the keywords it exports, through the +C method. You simply have to say C at the bottom of +your code for this to work. + +=head2 B<< Moose::Role->init_meta(for_class => $role, metaclass => $metaclass) >> + +The C method sets up the metaclass object for the role +specified by C. It also injects a a C accessor into +the role so you can get at this object. + +The default metaclass is L. You can specify an +alternate metaclass with the C parameter. + +=head1 METACLASS + +When you use Moose::Role, you can specify which metaclass to use: + + use Moose::Role -metaclass => 'My::Meta::Role'; + +You can also specify traits which will be applied to your role metaclass: + + use Moose::Role -traits => 'My::Trait'; + +This is very similar to the attribute traits feature. When you do +this, your class's C object will have the specified traits +applied to it. See L for more +details. + +=head1 APPLYING ROLES + +In addition to being applied to a class using the 'with' syntax (see +L) and using the L 'apply_all_roles' +method, roles may also be applied to an instance of a class using +L 'apply_all_roles' or the role's metaclass: + + MyApp::Test::SomeRole->meta->apply( $instance ); + +Doing this creates a new, mutable, anonymous subclass, applies the role to that, +and reblesses. In a debugger, for example, you will see class names of the +form C< Class::MOP::Class::__ANON__::SERIAL::6 >, which means that doing a 'ref' +on your instance may not return what you expect. See L for 'DOES'. + +Additional params may be added to the new instance by providing 'rebless_params'. +See L. + =head1 CAVEATS Role support has only a few caveats: @@ -280,16 +277,6 @@ In most cases, this will be a non-issue; however, it is something to keep in mind when using method modifiers in a role. You should never assume any ordering. -=item * - -The C keyword currently only works with actual methods. A method -modifier (before/around/after and override) will not count as a fufillment -of the requirement, and neither will an autogenerated accessor for an attribute. - -It is likely that attribute accessors will eventually be allowed to fufill those -requirements, or we will introduce a C keyword of some kind -instead. This decision has not yet been finalized. - =back =head1 BUGS @@ -306,7 +293,7 @@ Christian Hansen Echansen@cpan.orgE =head1 COPYRIGHT AND LICENSE -Copyright 2006-2008 by Infinity Interactive, Inc. +Copyright 2006-2009 by Infinity Interactive, Inc. L