X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMouse%2FRole.pm;h=c6413d3d065dbc769bd4cd0b9b8b4ff8156e2b54;hb=1746908e63ce233fad3c290d731ac34aff7c2d22;hp=5f620f3c6314fe715279f182fb30a56cb96edb04;hpb=33aaf11b51fd4b31581b8c118af54d8ff64060fb;p=gitmo%2FMouse.git diff --git a/lib/Mouse/Role.pm b/lib/Mouse/Role.pm index 5f620f3..c6413d3 100644 --- a/lib/Mouse/Role.pm +++ b/lib/Mouse/Role.pm @@ -1,207 +1,242 @@ package Mouse::Role; -use strict; -use warnings; -use base 'Exporter'; +use Mouse::Exporter; # enables strict and warnings -use Carp 'confess', 'croak'; -use Scalar::Util 'blessed'; +our $VERSION = '0.85'; -use Mouse::Meta::Role; +use Carp qw(confess); +use Scalar::Util qw(blessed); -our @EXPORT = qw(before after around super override inner augment has extends with requires excludes confess blessed); +use Mouse (); -sub before { - my $meta = Mouse::Meta::Role->initialize(caller); +Mouse::Exporter->setup_import_methods( + as_is => [qw( + extends with + has + before after around + override super + augment inner + + requires excludes + ), + \&Scalar::Util::blessed, + \&Carp::confess, + ], +); + + +sub extends { + Carp::croak "Roles do not support 'extends'"; +} + +sub with { + Mouse::Util::apply_all_roles(scalar(caller), @_); + return; +} + +sub has { + my $meta = Mouse::Meta::Role->initialize(scalar caller); + my $name = shift; + + $meta->throw_error(q{Usage: has 'name' => ( key => value, ... )}) + if @_ % 2; # odd number of arguments + + for my $n(ref($name) ? @{$name} : $name){ + $meta->add_attribute($n => @_); + } + return; +} +sub before { + my $meta = Mouse::Meta::Role->initialize(scalar caller); my $code = pop; - for (@_) { - $meta->add_before_method_modifier($_ => $code); + for my $name($meta->_collect_methods(@_)) { + $meta->add_before_method_modifier($name => $code); } + return; } sub after { - my $meta = Mouse::Meta::Role->initialize(caller); - + my $meta = Mouse::Meta::Role->initialize(scalar caller); my $code = pop; - for (@_) { - $meta->add_after_method_modifier($_ => $code); + for my $name($meta->_collect_methods(@_)) { + $meta->add_after_method_modifier($name => $code); } + return; } sub around { - my $meta = Mouse::Meta::Role->initialize(caller); - + my $meta = Mouse::Meta::Role->initialize(scalar caller); my $code = pop; - for (@_) { - $meta->add_around_method_modifier($_ => $code); + for my $name($meta->_collect_methods(@_)) { + $meta->add_around_method_modifier($name => $code); } + return; } sub super { - return unless $Mouse::SUPER_BODY; + return if !defined $Mouse::SUPER_BODY; $Mouse::SUPER_BODY->(@Mouse::SUPER_ARGS); } sub override { - my $classname = caller; - my $meta = Mouse::Meta::Role->initialize($classname); - - my $name = shift; - my $code = shift; - my $fullname = "${classname}::${name}"; - - defined &$fullname - && confess "Cannot add an override of method '$fullname' " . - "because there is a local version of '$fullname'"; - - $meta->add_override_method_modifier($name => sub { - local $Mouse::SUPER_PACKAGE = shift; - local $Mouse::SUPER_BODY = shift; - local @Mouse::SUPER_ARGS = @_; - - $code->(@_); - }); + # my($name, $code) = @_; + Mouse::Meta::Role->initialize(scalar caller)->add_override_method_modifier(@_); + return; } # We keep the same errors messages as Moose::Role emits, here. sub inner { - croak "Moose::Role cannot support 'inner'"; + Carp::croak "Roles cannot support 'inner'"; } sub augment { - croak "Moose::Role cannot support 'augment'"; + Carp::croak "Roles cannot support 'augment'"; } -sub has { - my $meta = Mouse::Meta::Role->initialize(caller); - - my $name = shift; - my %opts = @_; +sub requires { + my $meta = Mouse::Meta::Role->initialize(scalar caller); + $meta->throw_error("Must specify at least one method") unless @_; + $meta->add_required_methods(@_); + return; +} - $meta->add_attribute($name => \%opts); +sub excludes { + Mouse::Util::not_supported(); } -sub extends { confess "Roles do not currently support 'extends'" } +sub init_meta{ + shift; + my %args = @_; -sub with { - my $meta = Mouse::Meta::Role->initialize(caller); - my $role = shift; - my $args = shift || {}; - confess "Mouse::Role only supports 'with' on individual roles at a time" if @_ || !ref $args; + my $class = $args{for_class} + or Carp::confess("Cannot call init_meta without specifying a for_class"); - Mouse::load_class($role); - $role->meta->apply($meta, %$args); -} + my $metaclass = $args{metaclass} || 'Mouse::Meta::Role'; -sub requires { - my $meta = Mouse::Meta::Role->initialize(caller); - Carp::croak "Must specify at least one method" unless @_; - $meta->add_required_methods(@_); + my $meta = $metaclass->initialize($class); + + $meta->add_method(meta => sub{ + $metaclass->initialize(ref($_[0]) || $_[0]); + }); + + # make a role type for each Mouse role + Mouse::Util::TypeConstraints::role_type($class) + unless Mouse::Util::TypeConstraints::find_type_constraint($class); + + return $meta; } -sub excludes { confess "Mouse::Role does not currently support 'excludes'" } +1; -sub import { - my $class = shift; +__END__ - strict->import; - warnings->import; +=head1 NAME - my $caller = caller; +Mouse::Role - The Mouse Role - # we should never export to main - if ($caller eq 'main') { - warn qq{$class does not export its sugar to the 'main' package.\n}; - return; - } +=head1 VERSION - my $meta = Mouse::Meta::Role->initialize(caller); +This document describes Mouse version 0.85 - no strict 'refs'; - no warnings 'redefine'; - *{$caller.'::meta'} = sub { $meta }; +=head1 SYNOPSIS - Mouse::Role->export_to_level(1, @_); -} + package Comparable; + use Mouse::Role; # the package is now a Mouse role -sub unimport { - my $caller = caller; + # Declare methods that are required by this role + requires qw(compare); - no strict 'refs'; - for my $keyword (@EXPORT) { - delete ${ $caller . '::' }{$keyword}; + # Define methods this role provides + sub equals { + my($self, $other) = @_; + return $self->compare($other) == 0; } -} -1; + # and later + package MyObject; + use Mouse; + with qw(Comparable); # Now MyObject can equals() -__END__ - -=head1 NAME + sub compare { + # ... + } -Mouse::Role - define a role in Mouse + my $foo = MyObject->new(); + my $bar = MyObject->new(); + $obj->equals($bar); # yes, it is comparable -=head1 KEYWORDS +=head1 DESCRIPTION -=head2 meta -> Mouse::Meta::Role +This module declares the caller class to be a Mouse role. -Returns this role's metaclass instance. +The concept of roles is documented in L. +This document serves as API documentation. -=head2 before (method|methods) => Code +=head1 EXPORTED FUNCTIONS -Sets up a "before" method modifier. See L or -L. +Mouse::Role supports all of the functions that Mouse exports, but +differs slightly in how some items are handled (see L below +for details). -=head2 after (method|methods) => Code +Mouse::Role also offers two role-specific keywords: -Sets up an "after" method modifier. See L or -L. +=head2 C<< requires(@method_names) >> -=head2 around (method|methods) => Code +Roles can require that certain methods are implemented by any class which +C the role. -Sets up an "around" method modifier. See L or -L. +Note that attribute accessors also count as methods for the purposes of +satisfying the requirements of a role. -=item B +=head2 C<< excludes(@role_names) >> -Sets up the "super" keyword. See L. +This is exported but not implemented in Mouse. -=item B +=head1 IMPORT AND UNIMPORT -Sets up an "override" method modifier. See L. +=head2 import -=item B +Importing Mouse::Role will give you sugar. C<-traits> are also supported. -This is not supported and emits an error. See L. +=head2 unimport -=item B +Please unimport (C<< no Mouse::Role >>) so that if someone calls one of the +keywords (such as L) it will break loudly instead breaking subtly. -This is not supported and emits an error. See L. +=head1 CAVEATS -=head2 has (name|names) => parameters +Role support has only a few caveats: -Sets up an attribute (or if passed an arrayref of names, multiple attributes) to -this role. See L. +=over -=head2 confess error -> BOOM +=item * -L for your convenience. +Roles cannot use the C keyword; it will throw an exception for now. +The same is true of the C and C keywords (not sure those +really make sense for roles). All other Mouse keywords will be I +so that they can be applied to the consuming class. -=head2 blessed value -> ClassName | undef +=item * -L for your convenience. +Role composition does its best to B be order-sensitive when it comes to +conflict resolution and requirements detection. However, it is order-sensitive +when it comes to method modifiers. All before/around/after modifiers are +included whenever a role is composed into a class, and then applied in the order +in which the roles are used. This also means that there is no conflict for +before/around/after modifiers. -=head1 MISC +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. -=head2 import +=back -Importing Mouse::Role will give you sugar. +=head1 SEE ALSO -=head2 unimport +L -Please unimport Mouse (C) so that if someone calls one of the -keywords (such as L) it will break loudly instead breaking subtly. +L =cut