1Moose::Spec::Role(3) User Contributed Perl Documentation Moose::Spec::Role(3)
2
6 Moose::Spec::Role - Formal spec for Role behavior
7
9 version 2.2011
10
12 NOTE: This document is currently incomplete.
13 Components of a Role
15 Excluded Roles
16 A role can have a list of excluded roles, these are basically roles
17 that they shouldn't be composed with. This is not just direct
18 composition either, but also "inherited" composition.
19 This feature was taken from the Fortress language and is really of
21 most use when building a large set of role "building blocks" some
22 of which should never be used together.
23 Attributes
25 A roles attributes are similar to those of a class, except that
26 they are not actually applied. This means that methods that are
27 generated by an attributes accessor will not be generated in the
28 role, but only created once the role is applied to a class.
29 Methods
31 These are the methods defined within the role. Simple as that.
32 Required Methods
34 A role can require a consuming class (or role) to provide a given
35 method. Failure to do so for classes is a fatal error, while for
36 roles it simply passes on the method requirement to the consuming
37 role.
38 Required Attributes
40 Just as a role can require methods, it can also require attributes.
41 The requirement fulfilling attribute must implement at least as
42 much as is required. That means, for instance, that if the role
43 requires that the attribute be read-only, then it must at least
44 have a reader and can also have a writer. It means that if the role
45 requires that the attribute be an ArrayRef, then it must either be
46 an ArrayRef or a subtype of an ArrayRef.
47 Overridden Methods
49 The "override" and "super" keywords are allowed in roles, but their
50 behavior is different from that of its class counterparts. The
51 "super" in a class refers directly to that class's superclass,
52 while the "super" in a role is deferred and only has meaning once
53 the role is composed into a class. Once that composition occurs,
54 "super" then refers to that class's superclass.
55 It is key to remember that roles do not have hierarchy, so they can
57 never have a super role.
58 Method Modifiers
60 These are the "before", "around" and "after" modifiers provided in
61 Moose classes. The difference here is that the modifiers are not
62 actually applied until the role is composed into a class (this is
63 just like attributes and the "override" keyword).
64 Role Composition
66 Composing into a Class
67 Excluded Roles
69 Required Methods
70 Required Attributes
71 Attributes
72 Methods
73 Overridden methods
74 Method Modifiers (before, around, after)
75 Composing into a Instance
77 Composing into a Role
79 Excluded Roles
81 Required Methods
82 Required Attributes
83 Attributes
84 Methods
85 Overridden methods
86 Method Modifiers (before, around, after)
87 Role Summation
89 When multiple roles are added to another role (using the "with @roles"
91 keyword) the roles are composed symmetrically. The product of the
92 composition is a composite role (Moose::Meta::Role::Composite).
93 Excluded Roles
95 Required Methods
96 Required Attributes
97 Attributes
98 Attributes with the same name will conflict and are considered a
99 unrecoverable error. No other aspect of the attribute is examined,
100 it is enough that just the attribute names conflict.
101 The reason for such early and harsh conflicts with attributes is
103 because there is so much room for variance between two attributes
104 that the problem quickly explodes and rules get very complex. It is
105 my opinion that this complexity is not worth the trouble.
106 Methods
108 Methods with the same name will conflict, but no error is thrown,
109 instead the method name is added to the list of required methods
110 for the new composite role.
111 To look at this in terms of set theory, each role can be said to
113 have a set of methods. The symmetric difference of these two sets
114 is the new set of methods for the composite role, while the
115 intersection of these two sets are the conflicts. This can be
116 illustrated like so:
117 Role A has method set { a, b, c }
119 Role B has method set { c, d, e }
120 The composite role (A,B) has
122 method set { a, b, d, e }
123 conflict set { c }
124 Overridden methods
126 An overridden method can conflict in one of two ways.
127 The first way is with another overridden method of the same name,
129 and this is considered an unrecoverable error. This is an obvious
130 error since you cannot override a method twice in the same class.
131 The second way for conflict is for an overridden method and a
133 regular method to have the same name. This is also an unrecoverable
134 error since there is no way to combine these two, nor is it okay
135 for both items to be composed into a single class at some point.
136 The use of override in roles can be tricky, but if used carefully
138 they can be a very powerful tool.
139 Method Modifiers (before, around, after)
141 Method modifiers are the only place where the ordering of role
142 composition matters. This is due to the nature of method modifiers
143 themselves.
144 Since a method can have multiple method modifiers, these are just
146 collected in order to be later applied to the class in that same
147 order.
148 In general, great care should be taken in using method modifiers in
150 roles. The order sensitivity can possibly lead to subtle and
151 difficult to find bugs if they are overused. As with all good
152 things in life, moderation is the key.
153 Composition Edge Cases
155 This is a just a set of complex edge cases which can easily get
157 confused. This attempts to clarify those cases and provide an
158 explanation of what is going on in them.
159 Role Method Overriding
161 Many people want to "override" methods in roles they are consuming.
162 This works fine for classes, since the local class method is
163 favored over the role method. However in roles it is trickier, this
164 is because conflicts result in neither method being chosen and the
165 method being "required" instead.
166 Here is an example of this (incorrect) type of overriding.
168 package Role::Foo;
170 use Moose::Role;
171 sub foo { ... }
173 package Role::FooBar;
175 use Moose::Role;
176 with 'Role::Foo';
178 sub foo { ... }
180 sub bar { ... }
181 Here the "foo" methods conflict and the Role::FooBar now requires a
183 class or role consuming it to implement "foo". This is very often
184 not what the user wants.
185 Now here is an example of the (correct) type of overriding, only it
187 is not overriding at all, as is explained in the text below.
188 package Role::Foo;
190 use Moose::Role;
191 sub foo { ... }
193 package Role::Bar;
195 use Moose::Role;
196 sub foo { ... }
198 sub bar { ... }
199 package Role::FooBar;
201 use Moose::Role;
202 with 'Role::Foo', 'Role::Bar';
204 sub foo { ... }
206 This works because the combination of Role::Foo and Role::Bar
208 produce a conflict with the "foo" method. This conflict results in
209 the composite role (that was created by the combination of
210 Role::Foo and Role::Bar using the with keyword) having a method
211 requirement of "foo". The Role::FooBar then fulfills this
212 requirement.
213 It is important to note that Role::FooBar is simply fulfilling the
215 required "foo" method, and **NOT** overriding "foo". This is an
216 important distinction to make.
217 Now here is another example of a (correct) type of overriding, this
219 time using the excludes option.
220 package Role::Foo;
222 use Moose::Role;
223 sub foo { ... }
225 package Role::FooBar;
227 use Moose::Role;
228 with 'Role::Foo' => { -excludes => 'foo' };
230 sub foo { ... }
232 sub bar { ... }
233 By specifically excluding the "foo" method during composition, we
235 allow Role::FooBar to define its own version of "foo".
236
238 Traits
239 Roles are based on Traits, which originated in the Smalltalk
240 community.
241 <http://www.iam.unibe.ch/~scg/Research/Traits/>
243 This is the main site for the original Traits papers.
244 Class::Trait
246 I created this implementation of traits several years ago,
247 after reading the papers linked above. (This module is now
248 maintained by Ovid and I am no longer involved with it).
249 Roles
251 Since they are relatively new, and the Moose implementation is
252 probably the most mature out there, roles don't have much to link
253 to. However, here is some bits worth looking at (mostly related to
254 Perl 6)
255 <http://www.oreillynet.com/onlamp/blog/2006/08/roles_composable_units_of_obje.html>
257 This is chromatic's take on roles, which is worth reading since
258 he was/is one of the big proponents of them.
259 <http://svn.perl.org/perl6/doc/trunk/design/syn/S12.pod>
261 This is Synopsis 12, which is all about the Perl 6 Object
262 System. Which, of course, includes roles.
263
265 · Stevan Little <stevan.little@iinteractive.com>
266 · Dave Rolsky <autarch@urth.org>
268 · Jesse Luehrs <doy@tozt.net>
270 · Shawn M Moore <code@sartak.org>
272 · יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
274 · Karen Etheridge <ether@cpan.org>
276 · Florian Ragwitz <rafl@debian.org>
278 · Hans Dieter Pearcey <hdp@weftsoar.net>
280 · Chris Prather <chris@prather.org>
282 · Matt S Trout <mst@shadowcat.co.uk>
284
286 This software is copyright (c) 2006 by Infinity Interactive, Inc.
287 This is free software; you can redistribute it and/or modify it under
289 the same terms as the Perl 5 programming language system itself.
290perl v5.28.0 2018-05-16 Moose::Spec::Role(3)