Moose::Spec::Role(3pm)

NAME

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

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 it's 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 it's own version of "foo".

AUTHOR

Stevan Little <stevan@iinteractive.com>

COPYRIGHT AND LICENSE

<http://www.iinteractive.com>

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

docs.sk

comprehensive documentation repository

Most Viewed

Moose::Spec::Role(3pm)

NAME

DESCRIPTION

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE