package Mouse::Role;
use Mouse::Exporter; # enables strict and warnings
-our $VERSION = '0.40_08';
+our $VERSION = '0.95';
-use Carp qw(confess);
-use Scalar::Util qw(blessed);
+use Carp ();
+use Scalar::Util ();
-use Mouse::Util qw(not_supported);
-use Mouse::Meta::Role;
use Mouse ();
Mouse::Exporter->setup_import_methods(
Carp::croak "Roles do not support 'extends'";
}
-sub with {
- my $meta = Mouse::Meta::Role->initialize(scalar caller);
- Mouse::Util::apply_all_roles($meta->name, @_);
+sub with {
+ Mouse::Util::apply_all_roles(scalar(caller), @_);
return;
}
$meta->throw_error(q{Usage: has 'name' => ( key => value, ... )})
if @_ % 2; # odd number of arguments
- if(ref $name){ # has [qw(foo bar)] => (...)
- for (@{$name}){
- $meta->add_attribute($_ => @_);
- }
- }
- else{ # has foo => (...)
- $meta->add_attribute($name => @_);
+ 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(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(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 excludes {
- not_supported;
+ Mouse::Util::not_supported();
}
sub init_meta{
=head1 VERSION
-This document describes Mouse version 0.40_08
+This document describes Mouse version 0.95
=head1 SYNOPSIS
- package MyRole;
- use Mouse::Role;
+ package Comparable;
+ use Mouse::Role; # the package is now a Mouse role
-=head1 KEYWORDS
+ # Declare methods that are required by this role
+ requires qw(compare);
-=head2 C<< meta -> Mouse::Meta::Role >>
+ # Define methods this role provides
+ sub equals {
+ my($self, $other) = @_;
+ return $self->compare($other) == 0;
+ }
+
+ # and later
+ package MyObject;
+ use Mouse;
+ with qw(Comparable); # Now MyObject can equals()
-Returns this role's metaclass instance.
+ sub compare {
+ # ...
+ }
-=head2 C<< before (method|methods) -> CodeRef >>
+ my $foo = MyObject->new();
+ my $bar = MyObject->new();
+ $obj->equals($bar); # yes, it is comparable
-Sets up a B<before> method modifier. See L<Moose/before> or
-L<Class::Method::Modifiers/before>.
+=head1 DESCRIPTION
-=head2 C<< after (method|methods) => CodeRef >>
+This module declares the caller class to be a Mouse role.
-Sets up an B<after> method modifier. See L<Moose/after> or
-L<Class::Method::Modifiers/after>.
+The concept of roles is documented in L<Moose::Manual::Roles>.
+This document serves as API documentation.
-=head2 C<< around (method|methods) => CodeRef >>
+=head1 EXPORTED FUNCTIONS
-Sets up an B<around> method modifier. See L<Moose/around> or
-L<Class::Method::Modifiers/around>.
+Mouse::Role supports all of the functions that Mouse exports, but
+differs slightly in how some items are handled (see L</CAVEATS> below
+for details).
-=head2 C<super>
+Mouse::Role also offers two role-specific keywords:
-Sets up the B<super> keyword. See L<Moose/super>.
+=head2 C<< requires(@method_names) >>
-=head2 C<< override method => CodeRef >>
+Roles can require that certain methods are implemented by any class which
+C<does> the role.
-Sets up an B<override> method modifier. See L<Moose/Role/override>.
+Note that attribute accessors also count as methods for the purposes of
+satisfying the requirements of a role.
-=head2 C<inner>
+=head2 C<< excludes(@role_names) >>
-This is not supported in roles and emits an error. See L<Moose/Role>.
+This is exported but not implemented in Mouse.
-=head2 C<< augment method => CodeRef >>
+=head1 IMPORT AND UNIMPORT
+
+=head2 import
-This is not supported in roles and emits an error. See L<Moose/Role>.
+Importing Mouse::Role will give you sugar. C<-traits> are also supported.
-=head2 C<< has (name|names) => parameters >>
+=head2 unimport
-Sets up an attribute (or if passed an arrayref of names, multiple attributes) to
-this role. See L<Mouse/has>.
+Please unimport (C<< no Mouse::Role >>) so that if someone calls one of the
+keywords (such as L</has>) it will break loudly instead breaking subtly.
-=head2 C<< confess(error) -> BOOM >>
+=head1 CAVEATS
-L<Carp/confess> for your convenience.
+Role support has only a few caveats:
-=head2 C<< blessed(value) -> ClassName | undef >>
+=over
-L<Scalar::Util/blessed> for your convenience.
+=item *
-=head1 MISC
+Roles cannot use the C<extends> keyword; it will throw an exception for now.
+The same is true of the C<augment> and C<inner> keywords (not sure those
+really make sense for roles). All other Mouse keywords will be I<deferred>
+so that they can be applied to the consuming class.
-=head2 import
+=item *
-Importing Mouse::Role will give you sugar.
+Role composition does its best to B<not> 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.
-=head2 unimport
+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.
-Please unimport (C<< no Mouse::Role >>) so that if someone calls one of the
-keywords (such as L</has>) it will break loudly instead breaking subtly.
+=back
=head1 SEE ALSO
+L<Mouse>
+
L<Moose::Role>
+L<Moose::Manual::Roles>
+
+L<Moose::Spec::Role>
+
=cut
projects / gitmo/Mouse.git / blobdiff