1Moose::Spec::Role(3)  User Contributed Perl Documentation Moose::Spec::Role(3)
2
3
4

NAME

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

VERSION

9       version 2.2203
10

DESCRIPTION

12       NOTE: This document is currently incomplete.
13
14   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
20           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
24       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
30       Methods
31           These are the methods defined within the role. Simple as that.
32
33       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
39       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
48       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
56           It is key to remember that roles do not have hierarchy, so they can
57           never have a super role.
58
59       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
65   Role Composition
66       Composing into a Class
67
68       Excluded Roles
69       Required Methods
70       Required Attributes
71       Attributes
72       Methods
73       Overridden methods
74       Method Modifiers (before, around, after)
75
76       Composing into a Instance
77
78       Composing into a Role
79
80       Excluded Roles
81       Required Methods
82       Required Attributes
83       Attributes
84       Methods
85       Overridden methods
86       Method Modifiers (before, around, after)
87
88       Role Summation
89
90       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
94       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
102           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
107       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
112           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
118              Role A has method set { a, b, c }
119              Role B has method set { c, d, e }
120
121              The composite role (A,B) has
122                  method   set { a, b, d, e }
123                  conflict set { c }
124
125       Overridden methods
126           An overridden method can conflict in one of two ways.
127
128           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
132           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
137           The use of override in roles can be tricky, but if used carefully
138           they can be a very powerful tool.
139
140       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
145           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
149           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
154       Composition Edge Cases
155
156       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
160       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
167           Here is an example of this (incorrect) type of overriding.
168
169               package Role::Foo;
170               use Moose::Role;
171
172               sub foo { ... }
173
174               package Role::FooBar;
175               use Moose::Role;
176
177               with 'Role::Foo';
178
179               sub foo { ... }
180               sub bar { ... }
181
182           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
186           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
189               package Role::Foo;
190               use Moose::Role;
191
192               sub foo { ... }
193
194               package Role::Bar;
195               use Moose::Role;
196
197               sub foo { ... }
198               sub bar { ... }
199
200               package Role::FooBar;
201               use Moose::Role;
202
203               with 'Role::Foo', 'Role::Bar';
204
205               sub foo { ... }
206
207           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
214           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
218           Now here is another example of a (correct) type of overriding, this
219           time using the excludes option.
220
221               package Role::Foo;
222               use Moose::Role;
223
224               sub foo { ... }
225
226               package Role::FooBar;
227               use Moose::Role;
228
229               with 'Role::Foo' => { -excludes => 'foo' };
230
231               sub foo { ... }
232               sub bar { ... }
233
234           By specifically excluding the "foo" method during composition, we
235           allow Role::FooBar to define its own version of "foo".
236

SEE ALSO

238       Traits
239           Roles are based on Traits, which originated in the Smalltalk
240           community.
241
242           <http://www.iam.unibe.ch/~scg/Research/Traits/>
243               This is the main site for the original Traits papers.
244
245           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
250       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
256           <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
260           <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

AUTHORS

265       •   Stevan Little <stevan@cpan.org>
266
267       •   Dave Rolsky <autarch@urth.org>
268
269       •   Jesse Luehrs <doy@cpan.org>
270
271       •   Shawn M Moore <sartak@cpan.org>
272
273       •   יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
274
275       •   Karen Etheridge <ether@cpan.org>
276
277       •   Florian Ragwitz <rafl@debian.org>
278
279       •   Hans Dieter Pearcey <hdp@cpan.org>
280
281       •   Chris Prather <chris@prather.org>
282
283       •   Matt S Trout <mstrout@cpan.org>
284
286       This software is copyright (c) 2006 by Infinity Interactive, Inc.
287
288       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.
290
291
292
293perl v5.36.0                      2023-02-06              Moose::Spec::Role(3)
Impressum