X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FRole.pm;h=37ff7130d9a68c4ae0ed9e5618f79415941709c4;hb=refs%2Ftags%2F0.99;hp=a883da2f0ad75e2eba6beff219dead2aa32af5fe;hpb=e1737edc1aeb23724d9da1fec93ed82e900d8e00;p=gitmo%2FMoose.git diff --git a/lib/Moose/Role.pm b/lib/Moose/Role.pm index a883da2..37ff713 100644 --- a/lib/Moose/Role.pm +++ b/lib/Moose/Role.pm @@ -1,91 +1,72 @@ - package Moose::Role; - use strict; use warnings; use Scalar::Util 'blessed'; use Carp 'croak'; -use Data::OptList; use Sub::Exporter; -our $VERSION = '0.62_02'; +our $VERSION = '0.99'; $VERSION = eval $VERSION; our $AUTHORITY = 'cpan:STEVAN'; use Moose (); use Moose::Util (); +use Moose::Exporter; use Moose::Meta::Role; use Moose::Util::TypeConstraints; sub extends { - croak "Roles do not currently support 'extends'"; + croak "Roles do not support 'extends' (you can use 'with' to specialize a role)"; } sub with { - Moose::Util::apply_all_roles( Moose::Meta::Role->initialize(shift), @_ ); + Moose::Util::apply_all_roles( shift, @_ ); } sub requires { - my $meta = Moose::Meta::Role->initialize(shift); + my $meta = shift; croak "Must specify at least one method" unless @_; $meta->add_required_methods(@_); } sub excludes { - my $meta = Moose::Meta::Role->initialize(shift); + my $meta = shift; croak "Must specify at least one role" unless @_; $meta->add_excluded_roles(@_); } sub has { - my $meta = Moose::Meta::Role->initialize(shift); + my $meta = shift; my $name = shift; croak 'Usage: has \'name\' => ( key => value, ... )' if @_ == 1; - my %options = @_; + my %options = ( definition_context => Moose::Util::_caller_info(), @_ ); my $attrs = ( ref($name) eq 'ARRAY' ) ? $name : [ ($name) ]; $meta->add_attribute( $_, %options ) for @$attrs; } -sub before { - my $meta = Moose::Meta::Role->initialize(shift); +sub _add_method_modifier { + my $type = shift; + my $meta = shift; my $code = pop @_; for (@_) { croak "Roles do not currently support " . ref($_) - . " references for before method modifiers" + . " references for $type method modifiers" if ref $_; - $meta->add_before_method_modifier( $_, $code ); + my $add_method = "add_${type}_method_modifier"; + $meta->$add_method( $_, $code ); } } -sub after { - my $meta = Moose::Meta::Role->initialize(shift); +sub before { _add_method_modifier('before', @_) } - my $code = pop @_; - for (@_) { - croak "Roles do not currently support " - . ref($_) - . " references for after method modifiers" - if ref $_; - $meta->add_after_method_modifier( $_, $code ); - } -} +sub after { _add_method_modifier('after', @_) } -sub around { - my $meta = Moose::Meta::Role->initialize(shift); - my $code = pop @_; - for (@_) { - croak "Roles do not currently support " - . ref($_) - . " references for around method modifiers" - if ref $_; - $meta->add_around_method_modifier( $_, $code ); - } -} +sub around { _add_method_modifier('around', @_) } # see Moose.pm for discussion sub super { @@ -94,7 +75,7 @@ sub super { } sub override { - my $meta = Moose::Meta::Role->initialize(shift); + my $meta = shift; my ( $name, $code ) = @_; $meta->add_override_method_modifier( $name, $code ); } @@ -107,9 +88,9 @@ sub augment { croak "Roles cannot support 'augment'"; } -my $exporter = Moose::Exporter->setup_import_methods( - with_caller => [ - qw( with requires excludes has before after around override make_immutable ) +Moose::Exporter->setup_import_methods( + with_meta => [ + qw( with requires excludes has before after around override ) ], as_is => [ qw( extends super inner augment ), @@ -122,8 +103,12 @@ sub init_meta { shift; my %args = @_; - my $role = $args{for_class} - or Moose->throw_error("Cannot call init_meta without specifying a for_class"); + 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"; @@ -134,8 +119,11 @@ sub init_meta { my $meta; if ($role->can('meta')) { $meta = $role->meta(); - (blessed($meta) && $meta->isa('Moose::Meta::Role')) - || Moose->throw_error("You already have a &meta function, but it does not return a Moose::Meta::Role"); + + 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); @@ -187,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 @@ -210,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 @@ -233,6 +219,38 @@ 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: @@ -259,23 +277,11 @@ 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 -All complex software has bugs lurking in it, and this module is no -exception. If you find a bug please either email me, or add the bug -to cpan-RT. +See L for details on reporting bugs. =head1 AUTHOR @@ -285,7 +291,7 @@ Christian Hansen Echansen@cpan.orgE =head1 COPYRIGHT AND LICENSE -Copyright 2006-2008 by Infinity Interactive, Inc. +Copyright 2006-2010 by Infinity Interactive, Inc. L