Mouse::Util::does_role() respects $thing->does() method
[gitmo/Mouse.git] / lib / Mouse / Role.pm
index 33350cc..eb2ec97 100644 (file)
@@ -1,11 +1,12 @@
 package Mouse::Role;
-use Mouse::Util qw(not_supported); # enables strict and warnings
+use Mouse::Exporter; # enables strict and warnings
 
-use Carp ();
+our $VERSION = '0.95';
+
+use Carp         ();
 use Scalar::Util ();
 
 use Mouse ();
-use Mouse::Exporter;
 
 Mouse::Exporter->setup_import_methods(
     as_is => [qw(
@@ -23,31 +24,53 @@ Mouse::Exporter->setup_import_methods(
 );
 
 
-sub before {
+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(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;
 }
 
 
@@ -59,6 +82,7 @@ sub super {
 sub override {
     # 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.
@@ -70,46 +94,36 @@ sub augment {
     Carp::croak "Roles cannot support 'augment'";
 }
 
-sub has {
-    my $meta = Mouse::Meta::Role->initialize(scalar caller);
-    my $name = shift;
-
-    $meta->add_attribute($_ => @_) for ref($name) ? @{$name} : $name;
-}
-
-sub extends  {
-    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 requires {
     my $meta = Mouse::Meta::Role->initialize(scalar caller);
     $meta->throw_error("Must specify at least one method") unless @_;
     $meta->add_required_methods(@_);
+    return;
 }
 
 sub excludes {
-    not_supported;
+    Mouse::Util::not_supported();
 }
 
 sub init_meta{
-    my($class, %args) = @_;
+    shift;
+    my %args = @_;
 
-    my $for_class = $args{for_class}
+    my $class = $args{for_class}
         or Carp::confess("Cannot call init_meta without specifying a for_class");
 
     my $metaclass  = $args{metaclass}  || 'Mouse::Meta::Role';
 
-    my $meta = $metaclass->initialize($for_class);
+    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;
 }
 
@@ -121,75 +135,112 @@ __END__
 
 Mouse::Role - The Mouse Role
 
+=head1 VERSION
+
+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;
+    }
 
-Returns this role's metaclass instance.
+    # and later
+    package MyObject;
+    use Mouse;
+    with qw(Comparable); # Now MyObject can equals()
 
-=head2 C<< before (method|methods) -> CodeRef >>
+    sub compare {
+        # ...
+    }
 
-Sets up a B<before> method modifier. See L<Moose/before> or
-L<Class::Method::Modifiers/before>.
+    my $foo = MyObject->new();
+    my $bar = MyObject->new();
+    $obj->equals($bar); # yes, it is comparable
 
-=head2 C<< after (method|methods) => CodeRef >>
+=head1 DESCRIPTION
 
-Sets up an B<after> method modifier. See L<Moose/after> or
-L<Class::Method::Modifiers/after>.
+This module declares the caller class to be a Mouse role.
 
-=head2 C<< around (method|methods) => CodeRef >>
+The concept of roles is documented in L<Moose::Manual::Roles>.
+This document serves as API documentation.
 
-Sets up an B<around> method modifier. See L<Moose/around> or
-L<Class::Method::Modifiers/around>.
+=head1 EXPORTED FUNCTIONS
 
-=head2 C<super>
+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).
 
-Sets up the B<super> keyword. See L<Moose/super>.
+Mouse::Role also offers two role-specific keywords:
 
-=head2  C<< override method => CodeRef >>
+=head2 C<< requires(@method_names) >>
 
-Sets up an B<override> method modifier. See L<Moose/Role/override>.
+Roles can require that certain methods are implemented by any class which
+C<does> the role.
 
-=head2 C<inner>
+Note that attribute accessors also count as methods for the purposes of
+satisfying the requirements of a role.
 
-This is not supported in roles and emits an error. See L<Moose/Role>.
+=head2 C<< excludes(@role_names) >>
 
-=head2 C<< augment method => CodeRef >>
+This is exported but not implemented in Mouse.
 
-This is not supported in roles and emits an error. See L<Moose/Role>.
+=head1 IMPORT AND UNIMPORT
 
-=head2 C<< has (name|names) => parameters >>
+=head2 import
 
-Sets up an attribute (or if passed an arrayref of names, multiple attributes) to
-this role. See L<Mouse/has>.
+Importing Mouse::Role will give you sugar. C<-traits> are also supported.
 
-=head2 C<< confess(error) -> BOOM >>
+=head2 unimport
 
-L<Carp/confess> for your convenience.
+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<< blessed(value) -> ClassName | undef >>
+=head1 CAVEATS
 
-L<Scalar::Util/blessed> for your convenience.
+Role support has only a few caveats:
 
-=head1 MISC
+=over
 
-=head2 import
+=item *
 
-Importing Mouse::Role will give you sugar.
+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 unimport
+=item *
 
-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.
+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.
+
+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.
+
+=back
 
 =head1 SEE ALSO
 
+L<Mouse>
+
 L<Moose::Role>
 
+L<Moose::Manual::Roles>
+
+L<Moose::Spec::Role>
+
 =cut