[gitmo/Moose.git] / lib / Moose / Spec / Role.pod


=pod

=head1 NAME

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

=head1 DESCRIPTION

=head2 Components of a Role

=over 4

=item Excluded Roles

=item Attributes

=item Methods

=item Required Methods

=item Overriden Methods

The C<override> and C<super> keywords are allowed in roles, but 
thier 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, 
C<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 I<super> role.

=item Method Modifiers

=back

=head2 Role to Role Composition Rules

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.

=over 4

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

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.

=item Methods

Methods with the same name will conflict, but no error is 
thrown, instead the method name is added to the list of 
I<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 }

=item Overriden methods

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

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

=back

=head1 SEE ALSO

=over 4

=item Traits

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

=over 4 

=item L<http://www.iam.unibe.ch/~scg/Research/Traits/>

This is the main site for the original Traits papers.

=item L<Class::Trait>

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

=back

=item 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)

=over 4

=item L<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.

=item L<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.

=back

=back

=head1 AUTHOR

Stevan Little E<lt>stevan@iinteractive.comE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright 2007-2008 by Infinity Interactive, Inc.

L<http://www.iinteractive.com>

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

=cut
Commit	Line	Data
24a8fe99	1
	2	=pod
	3
	4	=head1 NAME
	5
	6	Moose::Spec::Role - Formal spec for Role behavior
	7
	8	=head1 DESCRIPTION
	9
	10	=head2 Components of a Role
	11
	12	=over 4
	13
	14	=item Excluded Roles
	15
	16	=item Attributes
	17
	18	=item Methods
	19
	20	=item Required Methods
	21
	22	=item Overriden Methods
	23
	24	The C<override> and C<super> keywords are allowed in roles, but
	25	thier behavior is different from that of it's class counterparts.
	26	The C<super> in a class refers directly to that class's superclass,
	27	while the C<super> in a role is deferred and only has meaning once
	28	the role is composed into a class. Once that composition occurs,
	29	C<super> then refers to that class's superclass.
	30
	31	It is key to remember that roles do not have hierarchy, so they
	32	can never have a I<super> role.
	33
	34	=item Method Modifiers
	35
	36	=back
	37
	38	=head2 Role to Role Composition Rules
	39
	40	When a role is added to another role (using the C<with>
	41	keyword) the two roles are composed symmetrically. The
	42	product of the composition is a third composite role.
	43
	44	=over 4
	45
	46	=item Attributes
	47
	48	Attributes with the same name will conflict and are considered
	49	a un-recoverable error. No other aspect of the attribute is
	50	examained, it is enough that just the attribute names conflict.
	51
	52	The reason for such early and harsh conflicts with attributes
	53	is because there is so much room for variance between two
	54	attributes that the problem quickly explodes and rules get
	55	very complex. It is my opinion that this complexity is not
	56	worth the trouble.
	57
	58	=item Methods
	59
	60	Methods with the same name will conflict, but no error is
	61	thrown, instead the method name is added to the list of
	62	I<required> methods for the new composite role.
	63
	64	To look at this in terms of set theory, each role can be
65	said to have a set of methods. The symmetric difference of
66	these two sets is the new set of methods for the composite
67	role, while the intersection of these two sets are the
68	conflicts. This can be illustrated like so:
69
70	Role A has method set { a, b, c }
71	Role B has method set { c, d, e }
72
73	The composite role (A,B) has
74	method set { a, b, d, e }
75	conflict set { c }
76
77	=item Overriden methods
78
79	An overriden method can conflict in one of two ways.
80
81	The first way is with another overriden method of the same
82	name, and this is considered an un-recoverable error. This
83	is an obvious error since you cannot override a method twice
84	in the same class.
85
86	The second way for conflict is for an overriden method and a
87	regular method to have the same name. This is also an un-recoverable
88	error since there is no way to combine these two, nor is it
89	okay for both items to be composed into a single class at some
90	point.
91
92	The use of override in roles can be tricky, but if used
93	carefully they can be a very powerful tool.
94
95	=item Method Modifiers (before, around, after)
96
97	Method modifiers are the only place where the ordering of
98	role composition matters. This is due to the nature of
99	method modifiers themselves.
100
101	Since a method can have multiple method modifiers, these
102	are just collected in order to be later applied to the
103	class in that same order.
104
105	In general, great care should be taken in using method
106	modifiers in roles. The order sensitivity can possibly
107	lead to subtle and difficult to find bugs if they are
108	overused. As with all good things in life, moderation
109	is the key.
110
111	=back
112
113	=head1 SEE ALSO
114
115	=over 4
116
117	=item Traits
118
119	Roles are based on Traits, which originated in the Smalltalk
120	community.
121
122	=over 4
123
124	=item L<http://www.iam.unibe.ch/~scg/Research/Traits/>
125
126	This is the main site for the original Traits papers.
127
128	=item L<Class::Trait>
129
130	I created this implementation of traits several years ago,
131	after reading the papers linked above. (This module is now
132	maintatined by Ovid and I am no longer involved with it).
133
134	=back
135
136	=item Roles
137
138	Since they are relatively new, and the Moose implementation
139	is probably the most mature out there, roles don't have much
140	to link to. However, here is some bits worth looking at (mostly
141	related to Perl 6)
142
143	=over 4
144
145	=item L<http://www.oreillynet.com/onlamp/blog/2006/08/roles_composable_units_of_obje.html>
146
147	This is chromatic's take on roles, which is worth reading since
148	he was/is one of the big proponents of them.
149
150	=item L<http://svn.perl.org/perl6/doc/trunk/design/syn/S12.pod>
151
152	This is Synopsis 12, which is all about the Perl 6 Object System.
153	Which, of course, includes roles.
154
155	=back
156
157	=back
158
159	=head1 AUTHOR
160
161	Stevan Little E<lt>stevan@iinteractive.comE<gt>
162
163	=head1 COPYRIGHT AND LICENSE
164
778db3ac	165	Copyright 2007-2008 by Infinity Interactive, Inc.
24a8fe99	166
	167	L<http://www.iinteractive.com>
	168
	169	This library is free software; you can redistribute it and/or modify
	170	it under the same terms as Perl itself.
	171
	172	=cut
	173