=head1 DESCRIPTION
+B<NOTE:> This document is currently incomplete.
+
=head2 Components of a Role
=over 4
=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
-=item Overriden 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 fulfilling attribute must implement at least as much
+as is required. That means, for instance, that if the role requires
+that the attribute be read-only, 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 Overridden Methods
The C<override> and C<super> keywords are allowed in roles, but
-thier behavior is different from that of it's class counterparts.
+their behavior is different from that of it's class counterparts.
The C<super> in a class refers directly to that class's superclass,
while the C<super> in a role is deferred and only has meaning once
the role is composed into a class. Once that composition occurs,
=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 to Role Composition Rules
+=head2 Role Composition
-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 Class
=over 4
+=item Excluded Roles
+
+=item Required Methods
+
+=item Required Attributes
+
+=item Attributes
+
+=item Methods
+
+=item Overridden methods
+
+=item Method Modifiers (before, around, after)
+
+=back
+
+=head3 Composing into a Instance
+
+=head3 Composing into a Role
+
+=over 4
+
+=item Excluded Roles
+
+=item Required Methods
+
+=item Required Attributes
+
+=item Attributes
+
+=item Methods
+
+=item Overridden 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
-a un-recoverable error. No other aspect of the attribute is
-examained, it is enough that just the attribute names conflict.
+a unrecoverable error. No other aspect of the attribute is
+examined, it is enough that just the attribute names conflict.
The reason for such early and harsh conflicts with attributes
is because there is so much room for variance between two
method set { a, b, d, e }
conflict set { c }
-=item Overriden methods
+=item Overridden methods
-An overriden method can conflict in one of two ways.
+An overridden method can conflict in one of two ways.
-The first way is with another overriden method of the same
-name, and this is considered an un-recoverable error. This
+The first way is with another overridden method of the same
+name, and this is considered an unrecoverable error. This
is an obvious error since you cannot override a method twice
in the same class.
-The second way for conflict is for an overriden method and a
-regular method to have the same name. This is also an un-recoverable
+The second way for conflict is for an overridden method and a
+regular method to have the same name. This is also an unrecoverable
error since there is no way to combine these two, nor is it
okay for both items to be composed into a single class at some
point.
=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
+explanation 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 fulfills this requirement.
+
+It is important to note that Role::FooBar is simply fulfilling the
+required C<foo> method, and **NOT** overriding C<foo>. This is an
+important distinction to make.
+
+Now here is another example of a (correct) type of overriding, this
+time using the I<excludes> option.
+
+ package Role::Foo;
+ use Moose::Role;
+
+ sub foo { ... }
+
+ package Role::FooBar;
+ use Moose::Role;
+
+ with 'Role::Foo' => { excludes => 'foo' };
+
+ sub foo { ... }
+ sub bar { ... }
+
+By specifically excluding the C<foo> method during composition,
+we allow B<Role::FooBar> to define it's own version of C<foo>.
+
+=back
+
=head1 SEE ALSO
=over 4
I created this implementation of traits several years ago,
after reading the papers linked above. (This module is now
-maintatined by Ovid and I am no longer involved with it).
+maintained by Ovid and I am no longer involved with it).
=back
=head1 COPYRIGHT AND LICENSE
-Copyright 2007 by Infinity Interactive, Inc.
+Copyright 2007-2009 by Infinity Interactive, Inc.
L<http://www.iinteractive.com>
projects / gitmo/Moose.git / blobdiff