Provided by: libmoose-perl_2.1005-1_amd64 bug

NAME

       Moose::Spec::Role - Formal spec for Role behavior

VERSION

       version 2.1005

DESCRIPTION

       NOTE: This document is currently incomplete.

   Components of a Role
       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.

       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.

       Methods
           These are the methods defined within the role. Simple as that.

       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.

       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.

       Overridden Methods
           The "override" and "super" keywords are allowed in roles, but their behavior is
           different from that of its class counterparts.  The "super" in a class refers directly
           to that class's superclass, while the "super" in a role is deferred and only has
           meaning once the role is composed into a class. Once that composition occurs, "super"
           then refers to that class's superclass.

           It is key to remember that roles do not have hierarchy, so they can never have a super
           role.

       Method Modifiers
           These are the "before", "around" and "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 "override" keyword).

   Role Composition
       Composing into a Class

       Excluded Roles
       Required Methods
       Required Attributes
       Attributes
       Methods
       Overridden methods
       Method Modifiers (before, around, after)

       Composing into a Instance

       Composing into a Role

       Excluded Roles
       Required Methods
       Required Attributes
       Attributes
       Methods
       Overridden methods
       Method Modifiers (before, around, after)

       Role Summation

       When multiple roles are added to another role (using the "with @roles" keyword) the roles
       are composed symmetrically.  The product of the composition is a composite role
       (Moose::Meta::Role::Composite).

       Excluded Roles
       Required Methods
       Required Attributes
       Attributes
           Attributes with the same name will conflict and are considered 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 attributes that the problem quickly explodes and
           rules get very complex. It is my opinion that this complexity is not worth the
           trouble.

       Methods
           Methods with the same name will conflict, but no error is thrown, instead the method
           name is added to the list of required methods for the new composite role.

           To look at this in terms of set theory, each role can be said to have a set of
           methods. The symmetric difference of these two sets is the new set of methods for the
           composite role, while the intersection of these two sets are the conflicts. This can
           be illustrated like so:

              Role A has method set { a, b, c }
              Role B has method set { c, d, e }

              The composite role (A,B) has
                  method   set { a, b, d, e }
                  conflict set { c }

       Overridden methods
           An overridden method can conflict in one of two ways.

           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 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.

           The use of override in roles can be tricky, but if used carefully they can be a very
           powerful tool.

       Method Modifiers (before, around, after)
           Method modifiers are the only place where the ordering of role composition matters.
           This is due to the nature of method modifiers themselves.

           Since a method can have multiple method modifiers, these are just collected in order
           to be later applied to the class in that same order.

           In general, great care should be taken in using method modifiers in roles. The order
           sensitivity can possibly lead to subtle and difficult to find bugs if they are
           overused. As with all good things in life, moderation is the key.

       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.

       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 "foo" methods conflict and the Role::FooBar now requires a class or role
           consuming it to implement "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 "foo" method. This conflict results in the composite role (that was created by the
           combination of Role::Foo and Role::Bar using the with keyword) having a method
           requirement of "foo". The Role::FooBar then fulfills this requirement.

           It is important to note that Role::FooBar is simply fulfilling the required "foo"
           method, and **NOT** overriding "foo". This is an important distinction to make.

           Now here is another example of a (correct) type of overriding, this time using the
           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 "foo" method during composition, we allow Role::FooBar
           to define its own version of "foo".

SEE ALSO

       Traits
           Roles are based on Traits, which originated in the Smalltalk community.

           <http://www.iam.unibe.ch/~scg/Research/Traits/>
               This is the main site for the original Traits papers.

           Class::Trait
               I created this implementation of traits several years ago, after reading the
               papers linked above. (This module is now maintained by Ovid and I am no longer
               involved with it).

       Roles
           Since they are relatively new, and the Moose implementation is probably the most
           mature out there, roles don't have much to link to. However, here is some bits worth
           looking at (mostly related to Perl 6)

           <http://www.oreillynet.com/onlamp/blog/2006/08/roles_composable_units_of_obje.html>
               This is chromatic's take on roles, which is worth reading since he was/is one of
               the big proponents of them.

           <http://svn.perl.org/perl6/doc/trunk/design/syn/S12.pod>
               This is Synopsis 12, which is all about the Perl 6 Object System.  Which, of
               course, includes roles.

AUTHOR

       Moose is maintained by the Moose Cabal, along with the help of many contributors. See
       "CABAL" in Moose and "CONTRIBUTORS" in Moose for details.

COPYRIGHT AND LICENSE

       This software is copyright (c) 2013 by Infinity Interactive, Inc..

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.