1Role-Basic
2
3INSTALLATION
4
5To install this module, run the following commands:
6
7 perl Build.PL
8 ./Build
9 ./Build test
10 ./Build install
11
12If you prefer a Makefile.PL:
13
14 perl Makefile.PL
15 make
16 make test
17 make install
18
19SUPPORT AND DOCUMENTATION
20
21After installing, you can find documentation for this module with the
22perldoc command.
23
24 perldoc Role::Basic
25
26NAME
27 Role::Basic - Just roles. Nothing else.
28
29VERSION
30 Version 0.01
31
32SYNOPSIS
33 In a role:
34
35 package Does::Serialize::AsYAML;
36 use Role::Basic;
37 use YAML::Syck;
38 requires 'as_hash';
39
40 sub serialize {
41 my $self = shift;
42 return Dump( $self->as_hash );
43 }
44
45 1;
46
47 In your class:
48
49 package My::Class;
50 use Role::Basic 'with';
51
52 with qw(
53 Does::Serialize::AsYAML
54 );
55
56 sub as_hash { ... } # because the role requires it
57
58DESCRIPTION
59 Sometimes you want roles. You're not sure about Moose, Mouse, Moo and
60 what *was* that damned Squirrel thing anyway? Then there's Class::Trait,
61 but it has a funky syntax and the maintainer's deprecated it in favor of
62 Moose::Role and you really don't care that it handles overloading,
63 instance application or has a workaround for the SUPER:: bug. You think
64 a meta-object protocol sounds nifty, but you don't understand it. Maybe
65 you're not sure you want the syntactic sugar for object declaration.
66 Maybe you've convinced your colleagues that roles are a good idea but
67 they're leery of dragging in Moose (your author has had this happen more
68 than once and heard of others making the same complaint). Sometimes you
69 just want good old-fashioned roles which let you separate class
70 responsibility from code reuse.
71
72 Whatever your reasons, this is the module you're looking for. It only
73 provides roles and its major design goals are safety and simplicity. It
74 also aims to be a *subset* of Moose::Role behavior so that when/if
75 you're ready to upgrade, there will be minimal pain.
76
77DECLARING A ROLE
78 To declare the current package as a role, simply add the following line
79 to the package:
80
81 use Role::Basic;
82
83 You can then use "with" to consume other roles and "requires" to list
84 the methods this role requires. Note that the *only* methods the role
85 will provide are methods declared directly in the role or consumed from
86 other roles. Thus:
87
88 package My::Role;
89 use Role::Basic;
90 use List::Util 'sum'; # this will not be provided by the role
91 with 'Some::Other::Role'; # any methods from this role will be provided
92
93 sub some_method {...} # this will be provided by the role
94
95CONSUMING ROLES
96 To declare the current package as a class that will use roles, simply
97 add the following line to the package:
98
99 use Role::Basic 'with';
100
101 Just as with Moose, you can have "-aliases" and list "-excludes".
102
103EXPORT
104 Both roles and classes will receive the following methods:
105
106 * "with"
107 "with" accepts a list and may only be called once per role or class.
108 This is because calling it multiple times removes composition
109 safety. Just as with Moose::Role, any class may also have "-aliases"
110 or "-excludes".
111
112 package My::Class;
113 use Role::Basic 'with';
114
115 with 'Does::Serialize::AsYAML' => { -aliases => { serialize => 'as_yaml' } };
116
117 And later:
118
119 print $object->as_yaml;
120
121 * "DOES"
122 Returns true if the class or role consumes a role of the given name:
123
124 if ( $class->DOES('Does::Serialize::AsYAML') ) {
125 ...
126 }
127
128 Further, if you're a role, you can also specify methods you require:
129
130 * "requires"
131 package Some::Role;
132 use Role::Basic;
133
134 # roles can consume other roles
135 with 'Another::Role';
136
137 requires qw(
138 first_method
139 second_method
140 another_method
141 );
142
143 In the example above, if "Another::Role" has methods it requires,
144 they will be added to the requirements of "Some::Role".
145
146DESIGN GOALS AND LIMITATIONS
147 There are two overriding design goals for "Role::Basic": simplicity and
148 safety. We make it a bit harder to shoot yourself in the foot and we aim
149 to keep the code as simple as possible. Feature requests are welcomed,
150 but will not be acted upon if they violate either of these two design
151 goals.
152
153 Thus, if you need something which "Role::Basic" does not support, you're
154 strongly encouraged to consider Moose or Mouse.
155
156 The following list details the outcomes of this module's goals.
157
158 * Basic role support
159 This includes composing into your class, composing roles from other
160 roles, roles declaring requirements and conflict resolution.
161
162 * Moose-like syntax
163 To ease migration difficulties, we use a Moose-like syntax. If you
164 wish to upgrade to Moose later, or you find that others on your
165 project are already familiar with Moose, this should make
166 "Role::Basic" easier to learn.
167
168 * No handling of SUPER:: bug
169 A well-known bug in OO Perl is that a SUPER:: method is invoked
170 against the class its declared in, not against the class of the
171 invocant. Handling this properly generally involves eval'ing a
172 method directly into the correct package:
173
174 eval <<"END_METHOD";
175 package $some_package;
176
177 sub some_method { ... }
178 END_METHOD
179
180 Or using a different method resolution order (MRO) such as with
181 Class::C3 or friends. We alert you to this limitation but make no
182 attempt to address it. We consider this a feature because roles
183 should not know or care how they are composed and probably should
184 not know if a superclass exists. This helps to keep this module
185 simple, a primary design goal.
186
187 * Composition Safety
188 In addition to the normal conflict resolution, only one "with"
189 statement is allowed:
190
191 package Foo;
192 use Role::Basic;
193 with 'Some::Role';
194 with 'Another::Role'; # boom!
195
196 This is because when you have more than one "with" statement, the
197 latter will ignore conflicts with the first. We could work around
198 this, but this would be significantly different from the behavior of
199 Moose.
200
201 * Override Safety
202 By default, we aim to behave like Moose::Role. This means that if a
203 class consuming a role has a method with the same name the role
204 provides, the class *silently* wins. This has been a somewhat
205 contentious issue in the "Moose" community and the "silent"
206 behaviour has won. However, there are those who prefer that they
207 don't have their methods silently ignored. We provide two optional
208 environment variables to handle this:
209
210 $ENV{PERL_ROLE_OVERRIDE_WARN}
211 $ENV{PERL_ROLE_OVERRIDE_DIE}
212
213 If you prefer, you can set one of those to true and a class
214 overridding a role's method will "warn" or "die", as appropriate. As
215 you might expect, you can handle this with normal role behaviour or
216 exclusion or aliasing.
217
218 package My::Class;
219 use Role::Basic 'with';
220 with 'My::Role' => { -excludes => 'conflicting_method' };
221
222 From your author's email exchanges with the authors of the original
223 traits paper (referenced here with permission), the "class silently
224 wins" behaviour was not intended. About this, Dr. Andrew P. Black
225 wrote the following:
226
227 Yes, it is really important that a programmer can see clearly when a trait
228 method is being overridden -- just as it is important that it is clear
229 when an inherited method is being overridden.
230
231 In Smalltalk, where a program is viewed as a graph of objects, the obvious
232 solution to this problem is to provide an adequate tool to show the
233 programmer interesting properties of the program. The original traits
234 browser did this for Smalltalk; the reason that we implemented it is that
235 traits were really NOT a good idea (that is,they were not very usable or
236 maintainable) without it. Since then, the same sort of "virtual
237 protocols" have been built into the browser for other properties, like
238 "overridden methods".
239
240 Note that those are provided as environment variables and not as
241 syntax in the code itself to help keep the code closer to the Moose
242 syntax.
243
244 * No instance application
245 "Role::Basic" does not support applying roles to object instances.
246 This may change in the future.
247
248 * No method modifiers
249 These have been especially problematic. Consider a "before" modifier
250 which multiplies a value by 2 and another before modifier which
251 divides a value by 3. The order in which those modifiers are applied
252 becomes extremely important. and role-consumption is no longer
253 entirely declarative, but becomes partially procedural. This causes
254 enough problems that on Sep 14, 2010 on the Moose mailing list,
255 Stevan Little wrote:
256
257 I totally agree [with the described application order problems], and if I
258 had to do it over again, I would not have allowed method modifiers in
259 roles. They ruin the unordered-ness of roles and bring about edge cases
260 like this that are not so easily solved.
261
262 Thus, "Role::Basic" does not and *will not* support method
263 modifiers. If you need them, consider Moose.
264
265AUTHOR
266 Curtis 'Ovid' Poe, "<ovid at cpan.org>"
267
268BUGS
269 Please report any bugs or feature requests to "bug-role-basic at
270 rt.cpan.org", or through the web interface at
271 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Role-Basic>. I will be
272 notified, and then you'll automatically be notified of progress on your
273 bug as I make changes.
274
275SUPPORT
276 You can find documentation for this module with the perldoc command.
277
278 perldoc Role::Basic
279
280 You can also look for information at:
281
282 * RT: CPAN's request tracker
283 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Role-Basic>
284
285 * AnnoCPAN: Annotated CPAN documentation
286 <http://annocpan.org/dist/Role-Basic>
287
288 * CPAN Ratings
289 <http://cpanratings.perl.org/d/Role-Basic>
290
291 * Search CPAN
292 <http://search.cpan.org/dist/Role-Basic/>
293
294ACKNOWLEDGEMENTS
295LICENSE AND COPYRIGHT
296 Copyright 2010 Curtis 'Ovid' Poe.
297
298 This program is free software; you can redistribute it and/or modify it
299 under the terms of either: the GNU General Public License as published
300 by the Free Software Foundation; or the Artistic License.
301
302 See http://dev.perl.org/licenses/ for more information.
303
304