1Moose::Spec::Role(3) User Contributed Perl Documentation Moose::Spec::Role(3)
2
6 Moose::Spec::Role - Formal spec for Role behavior
7
9 NOTE: This document is currently incomplete.
10 Components of a Role
12 Excluded Roles
13 A role can have a list of excluded roles, these are basically roles
14 that they shouldn't be composed with. This is not just direct
15 composition either, but also "inherited" composition.
16 This feature was taken from the Fortress language and is really of
18 most use when building a large set of role "building blocks" some
19 of which should never be used together.
20 Attributes
22 A roles attributes are similar to those of a class, except that
23 they are not actually applied. This means that methods that are
24 generated by an attributes accessor will not be generated in the
25 role, but only created once the role is applied to a class.
26 Methods
28 These are the methods defined within the role. Simple as that.
29 Required Methods
31 A role can require a consuming class (or role) to provide a given
32 method. Failure to do so for classes is a fatal error, while for
33 roles it simply passes on the method requirement to the consuming
34 role.
35 Required Attributes
37 Just as a role can require methods, it can also require attributes.
38 The requirement fulfilling attribute must implement at least as
39 much as is required. That means, for instance, that if the role
40 requires that the attribute be read-only, then it must at least
41 have a reader and can also have a writer. It means that if the role
42 requires that the attribute be an ArrayRef, then it must either be
43 an ArrayRef or a subtype of an ArrayRef.
44 Overridden Methods
46 The "override" and "super" keywords are allowed in roles, but their
47 behavior is different from that of it's class counterparts. The
48 "super" in a class refers directly to that class's superclass,
49 while the "super" in a role is deferred and only has meaning once
50 the role is composed into a class. Once that composition occurs,
51 "super" then refers to that class's superclass.
52 It is key to remember that roles do not have hierarchy, so they can
54 never have a super role.
55 Method Modifiers
57 These are the "before", "around" and "after" modifiers provided in
58 Moose classes. The difference here is that the modifiers are not
59 actually applied until the role is composed into a class (this is
60 just like attributes and the "override" keyword).
61 Role Composition
63 Composing into a Class
64 Excluded Roles
66 Required Methods
67 Required Attributes
68 Attributes
69 Methods
70 Overridden methods
71 Method Modifiers (before, around, after)
72 Composing into a Instance
74 Composing into a Role
76 Excluded Roles
78 Required Methods
79 Required Attributes
80 Attributes
81 Methods
82 Overridden methods
83 Method Modifiers (before, around, after)
84 Role Summation
86 When multiple roles are added to another role (using the "with @roles"
88 keyword) the roles are composed symmetrically. The product of the
89 composition is a composite role (Moose::Meta::Role::Composite).
90 Excluded Roles
92 Required Methods
93 Required Attributes
94 Attributes
95 Attributes with the same name will conflict and are considered a
96 unrecoverable error. No other aspect of the attribute is examined,
97 it is enough that just the attribute names conflict.
98 The reason for such early and harsh conflicts with attributes is
100 because there is so much room for variance between two attributes
101 that the problem quickly explodes and rules get very complex. It is
102 my opinion that this complexity is not worth the trouble.
103 Methods
105 Methods with the same name will conflict, but no error is thrown,
106 instead the method name is added to the list of required methods
107 for the new composite role.
108 To look at this in terms of set theory, each role can be said to
110 have a set of methods. The symmetric difference of these two sets
111 is the new set of methods for the composite role, while the
112 intersection of these two sets are the conflicts. This can be
113 illustrated like so:
114 Role A has method set { a, b, c }
116 Role B has method set { c, d, e }
117 The composite role (A,B) has
119 method set { a, b, d, e }
120 conflict set { c }
121 Overridden methods
123 An overridden method can conflict in one of two ways.
124 The first way is with another overridden method of the same name,
126 and this is considered an unrecoverable error. This is an obvious
127 error since you cannot override a method twice in the same class.
128 The second way for conflict is for an overridden method and a
130 regular method to have the same name. This is also an unrecoverable
131 error since there is no way to combine these two, nor is it okay
132 for both items to be composed into a single class at some point.
133 The use of override in roles can be tricky, but if used carefully
135 they can be a very powerful tool.
136 Method Modifiers (before, around, after)
138 Method modifiers are the only place where the ordering of role
139 composition matters. This is due to the nature of method modifiers
140 themselves.
141 Since a method can have multiple method modifiers, these are just
143 collected in order to be later applied to the class in that same
144 order.
145 In general, great care should be taken in using method modifiers in
147 roles. The order sensitivity can possibly lead to subtle and
148 difficult to find bugs if they are overused. As with all good
149 things in life, moderation is the key.
150 Composition Edge Cases
152 This is a just a set of complex edge cases which can easily get
154 confused. This attempts to clarify those cases and provide an
155 explanation of what is going on in them.
156 Role Method Overriding
158 Many people want to "override" methods in roles they are consuming.
159 This works fine for classes, since the local class method is
160 favored over the role method. However in roles it is trickier, this
161 is because conflicts result in neither method being chosen and the
162 method being "required" instead.
163 Here is an example of this (incorrect) type of overriding.
165 package Role::Foo;
167 use Moose::Role;
168 sub foo { ... }
170 package Role::FooBar;
172 use Moose::Role;
173 with 'Role::Foo';
175 sub foo { ... }
177 sub bar { ... }
178 Here the "foo" methods conflict and the Role::FooBar now requires a
180 class or role consuming it to implement "foo". This is very often
181 not what the user wants.
182 Now here is an example of the (correct) type of overriding, only it
184 is not overriding at all, as is explained in the text below.
185 package Role::Foo;
187 use Moose::Role;
188 sub foo { ... }
190 package Role::Bar;
192 use Moose::Role;
193 sub foo { ... }
195 sub bar { ... }
196 package Role::FooBar;
198 use Moose::Role;
199 with 'Role::Foo', 'Role::Bar';
201 sub foo { ... }
203 This works because the combination of Role::Foo and Role::Bar
205 produce a conflict with the "foo" method. This conflict results in
206 the composite role (that was created by the combination of
207 Role::Foo and Role::Bar using the with keyword) having a method
208 requirement of "foo". The Role::FooBar then fulfills this
209 requirement.
210 It is important to note that Role::FooBar is simply fulfilling the
212 required "foo" method, and **NOT** overriding "foo". This is an
213 important distinction to make.
214 Now here is another example of a (correct) type of overriding, this
216 time using the excludes option.
217 package Role::Foo;
219 use Moose::Role;
220 sub foo { ... }
222 package Role::FooBar;
224 use Moose::Role;
225 with 'Role::Foo' => { excludes => 'foo' };
227 sub foo { ... }
229 sub bar { ... }
230 By specifically excluding the "foo" method during composition, we
232 allow Role::FooBar to define it's own version of "foo".
233
235 Traits
236 Roles are based on Traits, which originated in the Smalltalk
237 community.
238 <http://www.iam.unibe.ch/~scg/Research/Traits/>
240 This is the main site for the original Traits papers.
241 Class::Trait
243 I created this implementation of traits several years ago,
244 after reading the papers linked above. (This module is now
245 maintained by Ovid and I am no longer involved with it).
246 Roles
248 Since they are relatively new, and the Moose implementation is
249 probably the most mature out there, roles don't have much to link
250 to. However, here is some bits worth looking at (mostly related to
251 Perl 6)
252 <http://www.oreillynet.com/onlamp/blog/2006/08/roles_composable_units_of_obje.html>
254 This is chromatic's take on roles, which is worth reading since
255 he was/is one of the big proponents of them.
256 <http://svn.perl.org/perl6/doc/trunk/design/syn/S12.pod>
258 This is Synopsis 12, which is all about the Perl 6 Object
259 System. Which, of course, includes roles.
260
262 Stevan Little <stevan@iinteractive.com>
263
265 Copyright 2007-2009 by Infinity Interactive, Inc.
266 <http://www.iinteractive.com>
268 This library is free software; you can redistribute it and/or modify it
270 under the same terms as Perl itself.
271perl v5.12.2 2010-07-02 Moose::Spec::Role(3)