=head1 NAME
-Moose::Manual::Roles - Roles, an Alternative to Deep Hierarchies and Base Classes
+Moose::Manual::Roles - Roles, an alternative to deep hierarchies and base classes
=head1 WHAT IS A ROLE?
A role is something that classes do. Usually, a role encapsulates some
piece of behavior or state that can be shared between classes. It is
-important to understand that I<roles are not classes>. Roles do not
-participate in inheritance, and a role cannot be instantiated.
+important to understand that I<roles are not classes>. You cannot
+inherit from a role, and a role cannot be instantiated. We sometimes
+say that roles are I<consumed>, either by classes or other roles.
Instead, a role is I<composed> into a class. In practical terms, this
means that all of the methods and attributes defined in a role are
-added directly to (we sometimes say ("flattened into") the class that
-consumes the role. These attributes and methods then show up in the
-class as if they were defined directly in the class.
+added directly to (we sometimes say "flattened into") the class that
+consumes the role. These attributes and methods then appear as if they
+were defined in the class itself. A subclass of the consuming class
+will inherit all of these methods and attributes.
Moose roles are similar to mixins or interfaces in other languages.
$self->is_broken(1);
}
-Except for our use of C<Moose::Role>, this looks just like a class
+Except for our use of L<Moose::Role>, this looks just like a class
definition with Moose. However, this is not a class, and it cannot be
instantiated.
If we try to consume this role in a class that does not have a
C<break> method, we will get an exception.
-Note that attribute-generated accessors do not satisfy the requirement
-that the named method exists. Similarly, a method modifier does not
-satisfy this requirement either. This may change in the future.
-
-You can also see that we added a method modifier on
-C<break>. Basically, we want consuming classes to implement their own
-logic for breaking, but we make sure that the C<is_broken> attribute
-is always set to true when C<break> is called.
+You can see that we added a method modifier on C<break>. We want
+classes that consume this role to implement their own logic for
+breaking, but we make sure that the C<is_broken> attribute is always
+set to true when C<break> is called.
package Car
- use Moose;
+ use Moose;
with 'Breakable';
}
}
+=head2 Roles Versus Abstract Base Classes
+
+If you are familiar with the concept of abstract base classes in other
+languages, you may be tempted to use roles in the same way.
+
+You I<can> define an "interface-only" role, one that contains I<just>
+a list of required methods.
+
+However, any class which consumes this role must implement all of the
+required methods, either directly or through inheritance from a
+parent. You cannot delay the method requirement check so that they can
+be implemented by future subclasses.
+
+Because the role defines the required methods directly, adding a base
+class to the mix would not achieve anything. We recommend that you
+simply consume the interface role in each class which implements that
+interface.
+
=head1 USING METHOD MODIFIERS
Method modifiers and roles are a very powerful combination. Often, a
the same name, we will have a conflict. In that case, the composing
class is required to provide its I<own> method of the same name.
- package Breakdances;
+ package Breakdancer;
use Moose::Role
method. If some API expects an object that does one of those roles, it
probably expects it to implement that method.
+In some use cases we might alias and exclude methods from roles, but
+then provide a method of the same name in the class itself.
+
+=head1 ROLE EXCLUSION
+
+A role can say that it cannot be combined with some other role. This
+should be used with great caution, since it limits the re-usability of
+the role.
+
+ package Breakable;
+
+ use Moose::Role;
+
+ excludes 'BreakDancer';
+
=head1 AUTHOR
Dave Rolsky E<lt>autarch@urth.orgE<gt>
projects / gitmo/Moose.git / blobdiff