lib/Moose/Spec/Role.pod

   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
 165 Copyright 2007 by Infinity Interactive, Inc.
 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