=item Excluded Roles
+A role can have a list of excluded roles, these are basically
+roles that they shouldn't be composed with. This is not just
+direct composition either, but also "inherited" composition.
+
+This feature was taken from the Fortress language and is really
+of most use when building a large set of role "building blocks"
+some of which should never be used together.
+
=item Attributes
+A roles attributes are similar to those of a class, except that
+they are not actually applied. This means that methods that are
+generated by an attributes accessor will not be generated in the
+role, but only created once the role is applied to a class.
+
=item Methods
+These are the methods defined within the role. Simple as that.
+
=item Required Methods
+A role can require a consuming class (or role) to provide a
+given method. Failure to do so for classes is a fatal error,
+while for roles it simply passes on the method requirement to
+the consuming role.
+
+=item Required Attributes
+
+Just as a role can require methods, it can also require attributes.
+The requirement fufilling attribute must implement at least as much
+as is required. That means, for instance, that if the role requires
+that the attribute be readonly, then it must at least have a reader
+and can also have a writer. It means that if the role requires that
+the attribute be an ArrayRef, then it must either be an ArrayRef or
+a subtype of an ArrayRef.
+
=item Overriden Methods
The C<override> and C<super> keywords are allowed in roles, but
=item Method Modifiers
+These are the C<before>, C<around> and C<after> modifiers provided
+in Moose classes. The difference here is that the modifiers are not
+actually applied until the role is composed into a class (this is
+just like attributes and the C<override> keyword).
+
+=back
+
+=head2 Role Composition
+
+=head3 Composing into a Class
+
+=over 4
+
+=item Excluded Roles
+
+=item Required Methods
+
+=item Required Attributes
+
+=item Attributes
+
+=item Methods
+
+=item Overriden methods
+
+=item Method Modifiers (before, around, after)
+
=back
-=head2 Role to Role Composition Rules
+=head3 Composing into a Instance
-When a role is added to another role (using the C<with>
-keyword) the two roles are composed symmetrically. The
-product of the composition is a third composite role.
+=head3 Composing into a Role
=over 4
+=item Excluded Roles
+
+=item Required Methods
+
+=item Required Attributes
+
+=item Attributes
+
+=item Methods
+
+=item Overriden methods
+
+=item Method Modifiers (before, around, after)
+
+=back
+
+=head3 Role Summation
+
+When multiple roles are added to another role (using the
+C<with @roles> keyword) the roles are composed symmetrically.
+The product of the composition is a composite role
+(L<Moose::Meta::Role::Composite>).
+
+=over 4
+
+=item Excluded Roles
+
+=item Required Methods
+
+=item Required Attributes
+
=item Attributes
Attributes with the same name will conflict and are considered
=back
+=head3 Composition Edge Cases
+
+This is a just a set of complex edge cases which can easily get
+confused. This attempts to clarify those cases and provide an
+explination of what is going on in them.
+
+=over 4
+
+=item Role Method Overriding
+
+Many people want to "override" methods in roles they are consuming.
+This works fine for classes, since the local class method is favored
+over the role method. However in roles it is trickier, this is because
+conflicts result in neither method being chosen and the method being
+"required" instead.
+
+Here is an example of this (incorrect) type of overriding.
+
+ package Role::Foo;
+ use Moose::Role;
+
+ sub foo { ... }
+
+ package Role::FooBar;
+ use Moose::Role;
+
+ with 'Role::Foo';
+
+ sub foo { ... }
+ sub bar { ... }
+
+Here the C<foo> methods conflict and the Role::FooBar now requires a
+class or role consuming it to implement C<foo>. This is very often not
+what the user wants.
+
+Now here is an example of the (correct) type of overriding, only it is
+not overriding at all, as is explained in the text below.
+
+ package Role::Foo;
+ use Moose::Role;
+
+ sub foo { ... }
+
+ package Role::Bar;
+ use Moose::Role;
+
+ sub foo { ... }
+ sub bar { ... }
+
+ package Role::FooBar;
+ use Moose::Role;
+
+ with 'Role::Foo', 'Role::Bar';
+
+ sub foo { ... }
+
+This works because the combination of Role::Foo and Role::Bar produce
+a conflict with the C<foo> method. This conflict results in the
+composite role (that was created by the combination of Role::Foo
+and Role::Bar using the I<with> keyword) having a method requirement
+of C<foo>. The Role::FooBar then fufills this requirement.
+
+It is important to note that Role::FooBar is simply fufilling the
+required C<foo> method, and **NOT** overriding C<foo>. This is an
+important distinction to make.
+
+=back
+
=head1 SEE ALSO
=over 4
=head1 COPYRIGHT AND LICENSE
-Copyright 2007 by Infinity Interactive, Inc.
+Copyright 2007-2008 by Infinity Interactive, Inc.
L<http://www.iinteractive.com>
projects / gitmo/Moose.git / blobdiff