Moose::Spec::Role - phpMan

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

VERSION
    version 2.2200

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

AUTHORS
    *   Stevan Little <stevan AT cpan.org>

    *   Dave Rolsky <autarch AT urth.org>

    *   Jesse Luehrs <doy AT cpan.org>

    *   Shawn M Moore <sartak AT cpan.org>

    *   יובל קוג'מן (Yuval Kogman) <nothingmuch AT woobling.org>

    *   Karen Etheridge <ether AT cpan.org>

    *   Florian Ragwitz <rafl AT debian.org>

    *   Hans Dieter Pearcey <hdp AT cpan.org>

    *   Chris Prather <chris AT prather.org>

    *   Matt S Trout <mstrout AT cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2006 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.