Debian Codegraph @

README

raw
1 NAME
2 Class::Spiffy - Spiffy Framework with No Source Filtering
3
4 SYNOPSIS
5 package Keen;
6 use strict;
7 use warnings;
8 use Class::Spiffy -base;
9 field 'mirth';
10 const mood => ':-)';
11
12 sub happy {
13 my $self = shift;
14 if ($self->mood eq ':-(') {
15 $self->mirth(-1);
16 print "Cheer up!";
17 }
18 super;
19 }
20
21 1;
22
23 DESCRIPTION
24 "Class::Spiffy" is a framework and methodology for doing object oriented
25 (OO) programming in Perl. Class::Spiffy combines the best parts of
26 Exporter.pm, base.pm, mixin.pm and SUPER.pm into one magic foundation
27 class. It attempts to fix all the nits and warts of traditional Perl OO,
28 in a clean, straightforward and (perhaps someday) standard way.
29
30 Class::Spiffy borrows ideas from other OO languages like Python, Ruby,
31 Java and Perl 6. It also adds a few tricks of its own.
32
33 If you take a look on CPAN, there are a ton of OO related modules. When
34 starting a new project, you need to pick the set of modules that makes
35 most sense, and then you need to use those modules in each of your
36 classes. Class::Spiffy, on the other hand, has everything you'll
37 probably need in one module, and you only need to use it once in one of
38 your classes. If you make Class::Spiffy the base class of the basest
39 class in your project, Class::Spiffy will automatically pass all of its
40 magic to all of your subclasses. You may eventually forget that you're
41 even using it!
42
43 The most striking difference between Class::Spiffy and other Perl object
44 oriented base classes, is that it has the ability to export things. If
45 you create a subclass of Class::Spiffy, all the things that
46 Class::Spiffy exports will automatically be exported by your subclass,
47 in addition to any more things that you want to export. And if someone
48 creates a subclass of your subclass, all of those things will be
49 exported automatically, and so on. Think of it as "Inherited
50 Exportation", and it uses the familiar Exporter.pm specification syntax.
51
52 To use Class::Spiffy or any subclass of Class::Spiffy as a base class of
53 your class, you specify the "-base" argument to the "use" command.
54
55 use MySpiffyBaseModule -base;
56
57 You can also use the traditional "use base 'MySpiffyBaseModule';" syntax
58 and everything will work exactly the same. The only caveat is that
59 Class::Spiffy must already be loaded. That's because Class::Spiffy
60 rewires base.pm on the fly to do all the Spiffy magics.
61
62 Class::Spiffy has support for Ruby-like mixins with Perl6-like roles.
63 Just like "base" you can use either of the following invocations:
64
65 use mixin 'MySpiffyBaseModule';
66 use MySpiffyBaseModule -mixin;
67
68 The second version will only work if the class being mixed in is a
69 subclass of Class::Spiffy. The first version will work in all cases, as
70 long as Class::Spiffy has already been loaded.
71
72 To limit the methods that get mixed in, use roles. (Hint: they work just
73 like an Exporter list):
74
75 use MySpiffyBaseModule -mixin => qw(:basics x y !foo);
76
77 A useful feature of Class::Spiffy is that it exports two functions:
78 "field" and "const" that can be used to declare the attributes of your
79 class, and automatically generate accessor methods for them. The only
80 difference between the two functions is that "const" attributes can not
81 be modified; thus the accessor is much faster.
82
83 One interesting aspect of OO programming is when a method calls the same
84 method from a parent class. This is generally known as calling a super
85 method. Perl's facility for doing this is butt ugly:
86
87 sub cleanup {
88 my $self = shift;
89 $self->scrub;
90 $self->SUPER::cleanup(@_);
91 }
92
93 Class::Spiffy makes it, er, super easy to call super methods. You just
94 use the "super" function. You don't need to pass it any arguments
95 because it automatically passes them on for you. Here's the same
96 function with Class::Spiffy:
97
98 sub cleanup {
99 my $self = shift;
100 $self->scrub;
101 super;
102 }
103
104 Class::Spiffy has a special method for parsing arguments called
105 "parse_arguments", that it also uses for parsing its own arguments. You
106 declare which arguments are boolean (singletons) and which ones are
107 paired, with two special methods called "boolean_arguments" and
108 "paired_arguments". Parse arguments pulls out the booleans and pairs and
109 returns them in an anonymous hash, followed by a list of the unmatched
110 arguments.
111
112 Finally, Class::Spiffy can export a few debugging functions "WWW",
113 "XXX", "YYY" and "ZZZ". Each of them produces a YAML dump of its
114 arguments. WWW warns the output, XXX dies with the output, YYY prints
115 the output, and ZZZ confesses the output. If YAML doesn't suit your
116 needs, you can switch all the dumps to Data::Dumper format with the "-
117 dumper" option.
118
119 That's Spiffy! Pretty Classy, eh?
120
121 A Spiffy NOTE
122 Class::Spiffy started off as the Spiffy.pm module. Class::Spiffy does
123 everything Spiffy does except clever source filtering. So you can be
124 sure that any module that uses Class::Spiffy, (like YAML.pm) doesn't use
125 source filtering. If you don't like source filtering, this may help you
126 sleep better at night.
127
128 Spiffy EXPORTING
129 Class::Spiffy implements a completely new idea in Perl. Modules that act
130 both as object oriented classes and that also export functions. But it
131 takes the concept of Exporter.pm one step further; it walks the entire
132 @ISA path of a class and honors the export specifications of each
133 module. Since Class::Spiffy calls on the Exporter module to do this, you
134 can use all the fancy interface features that Exporter has, including
135 tags and negation.
136
137 Class::Spiffy considers all the arguments that don't begin with a dash
138 to comprise the export specification.
139
140 package Vehicle;
141 use Spiffy -base;
142 our $SERIAL_NUMBER = 0;
143 our @EXPORT = qw($SERIAL_NUMBER);
144 our @EXPORT_BASE = qw(tire horn);
145
146 package Bicycle;
147 use Vehicle -base, '!field';
148
149 In this case, "Bicycle-"isa('Vehicle')> and also all the things that
150 "Vehicle" and "Class::Spiffy" export, will go into "Bicycle", except
151 "field".
152
153 Exporting can be very helpful when you've designed a system with
154 hundreds of classes, and you want them all to have access to some
155 functions or constants or variables. Just export them in your main base
156 class and every subclass will get the functions they need.
157
158 You can do almost everything that Exporter does because Class::Spiffy
159 delegates the job to Exporter (after adding some Spiffy magic).
160 Class::Spiffy offers a @EXPORT_BASE variable which is like @EXPORT, but
161 only for usages that use "-base".
162
163 Spiffy MIXINs & ROLEs
164 If you've done much OO programming in Perl you've probably used Multiple
165 Inheritance (MI), and if you've done much MI you've probably run into
166 weird problems and headaches. Some languages like Ruby, attempt to
167 resolve MI issues using a technique called mixins. Basically, all Ruby
168 classes use only Single Inheritance (SI), and then *mixin* functionality
169 from other modules if they need to.
170
171 Mixins can be thought of at a simplistic level as *importing* the
172 methods of another class into your subclass. But from an implementation
173 standpoint that's not the best way to do it. Class::Spiffy does what
174 Ruby does. It creates an empty anonymous class, imports everything into
175 that class, and then chains the new class into your SI ISA path. In
176 other words, if you say:
177
178 package A;
179 use B -base;
180 use C -mixin;
181 use D -mixin;
182
183 You end up with a single inheritance chain of classes like this:
184
185 A << A-D << A-C << B;
186
187 "A-D" and "A-C" are the actual package names of the generated classes.
188 The nice thing about this style is that mixing in C doesn't clobber any
189 methods in A, and D doesn't conflict with A or C either. If you mixed in
190 a method in C that was also in A, you can still get to it by using
191 "super".
192
193 When Class::Spiffy mixes in C, it pulls in all the methods in C that do
194 not begin with an underscore. Actually it goes farther than that. If C
195 is a subclass it will pull in every method that C "can" do through
196 inheritance. This is very powerful, maybe too powerful.
197
198 To limit what you mixin, Class::Spiffy borrows the concept of Roles from
199 Perl6. The term role is used more loosely in Class::Spiffy though. It's
200 much like an import list that the Exporter module uses, and you can use
201 groups (tags) and negation. If the first element of your list uses
202 negation, Class::Spiffy will start with all the methods that your mixin
203 class can do.
204
205 use E -mixin => qw(:tools walk !run !:sharp_tools);
206
207 In this example, "walk" and "run" are methods that E can do, and "tools"
208 and "sharp_tools" are roles of class E. How does class E define these
209 roles? It very simply defines methods called "_role_tools" and
210 "_role_sharp_tools" which return lists of more methods. (And possibly
211 other roles!) The neat thing here is that since roles are just methods,
212 they too can be inherited. Take that Perl6!
213
214 Spiffy DEBUGGING
215 The XXX function is very handy for debugging because you can insert it
216 almost anywhere, and it will dump your data in nice clean YAML. Take the
217 following statement:
218
219 my @stuff = grep { /keen/ } $self->find($a, $b);
220
221 If you have a problem with this statement, you can debug it in any of
222 the following ways:
223
224 XXX my @stuff = grep { /keen/ } $self->find($a, $b);
225 my @stuff = XXX grep { /keen/ } $self->find($a, $b);
226 my @stuff = grep { /keen/ } XXX $self->find($a, $b);
227 my @stuff = grep { /keen/ } $self->find(XXX $a, $b);
228
229 XXX is easy to insert and remove. It is also a tradition to mark
230 uncertain areas of code with XXX. This will make the debugging dumpers
231 easy to spot if you forget to take them out.
232
233 WWW and YYY are nice because they dump their arguments and then return
234 the arguments. This way you can insert them into many places and still
235 have the code run as before. Use ZZZ when you need to die with both a
236 YAML dump and a full stack trace.
237
238 The debugging functions are exported by default if you use the "-base"
239 option, but only if you have previously used the "-XXX" option. To
240 export all 4 functions use the export tag:
241
242 use SomeSpiffyModule ':XXX';
243
244 To force the debugging functions to use Data::Dumper instead of YAML:
245
246 use SomeSpiffyModule -dumper;
247
248 Spiffy FUNCTIONS
249 This section describes the functions the Class::Spiffy exports. The
250 "field", "const", "stub" and "super" functions are only exported when
251 you use the "-base" option.
252
253 * field
254 Defines accessor methods for a field of your class:
255
256 package Example;
257 use Classs::Spiffy -base;
258
259 field 'foo';
260 field bar => [];
261
262 sub lalala {
263 my $self == shift;
264 $self->foo(42);
265 push @{$self->{bar}}, $self->foo;
266 }
267
268 The first parameter passed to "field" is the name of the attribute
269 being defined. Accessors can be given an optional default value.
270 This value will be returned if no value for the field has been set
271 in the object.
272
273 * const
274 const bar => 42;
275
276 The "const" function is similar to <field> except that it is
277 immutable. It also does not store data in the object. You probably
278 always want to give a "const" a default value, otherwise the
279 generated method will be somewhat useless.
280
281 * stub
282 stub 'cigar';
283
284 The "stub" function generates a method that will die with an
285 appropriate message. The idea is that subclasses must implement
286 these methods so that the stub methods don't get called.
287
288 * super
289 If this function is called without any arguments, it will call the
290 same method that it is in, higher up in the ISA tree, passing it all
291 the same arguments. If it is called with arguments, it will use
292 those arguments with $self in the front. In other words, it just
293 works like you'd expect.
294
295 sub foo {
296 my $self = shift;
297 super; # Same as $self->SUPER::foo(@_);
298 super('hello'); # Same as $self->SUPER::foo('hello');
299 $self->bar(42);
300 }
301
302 sub new {
303 my $self = super;
304 $self->init;
305 return $self;
306 }
307
308 "super" will simply do nothing if there is no super method. Finally,
309 "super" does the right thing in AUTOLOAD subroutines.
310
311 Spiffy METHODS
312 This section lists all of the methods that any subclass of Class::Spiffy
313 automatically inherits.
314
315 * mixin
316 A method to mixin a class at runtime. Takes the same arguments as
317 "use mixin ...". Makes the target class a mixin of the caller.
318
319 $self->mixin('SomeClass');
320 $object->mixin('SomeOtherClass' => 'some_method');
321
322 * parse_arguments
323 This method takes a list of arguments and groups them into pairs. It
324 allows for boolean arguments which may or may not have a value
325 (defaulting to 1). The method returns a hash reference of all the
326 pairs as keys and values in the hash. Any arguments that cannot be
327 paired, are returned as a list. Here is an example:
328
329 sub boolean_arguments { qw(-has_spots -is_yummy) }
330 sub paired_arguments { qw(-name -size) }
331 my ($pairs, @others) = $self->parse_arguments(
332 'red', 'white',
333 -name => 'Ingy',
334 -has_spots =>
335 -size => 'large',
336 'black',
337 -is_yummy => 0,
338 );
339
340 After this call, $pairs will contain:
341
342 {
343 -name => 'Ingy',
344 -has_spots => 1,
345 -size => 'large',
346 -is_yummy => 0,
347 }
348
349 and @others will contain 'red', 'white', and 'black'.
350
351 * boolean_arguments
352 Returns the list of arguments that are recognized as being boolean.
353 Override this method to define your own list.
354
355 * paired_arguments
356 Returns the list of arguments that are recognized as being paired.
357 Override this method to define your own list.
358
359 Spiffy ARGUMENTS
360 When you "use" the Class::Spiffy module or a subclass of it, you can
361 pass it a list of arguments. These arguments are parsed using the
362 "parse_arguments" method described above. The special argument "- base",
363 is used to make the current package a subclass of the Class::Spiffy
364 module being used.
365
366 Any non-paired parameters act like a normal import list; just like those
367 used with the Exporter module.
368
369 USING Class::Spiffy WITH base.pm
370 The proper way to use a Class::Spiffy module as a base class is with the
371 "-base" parameter to the "use" statement. This differs from typical
372 modules where you would want to "use base".
373
374 package Something;
375 use Spiffy::Module -base;
376 use base 'NonSpiffy::Module';
377
378 Now it may be hard to keep track of what's Spiffy and what is not.
379 Therefore Class::Spiffy has actually been made to work with base.pm. You
380 can say:
381
382 package Something;
383 use base 'Spiffy::Module';
384 use base 'NonSpiffy::Module';
385
386 "use base" is also very useful when your class is not an actual module
387 (a separate file) but just a package in some file that has already been
388 loaded. "base" will work whether the class is a module or not, while the
389 "-base" syntax cannot work that way, since "use" always tries to load a
390 module.
391
392 base.pm Caveats
393 To make Class::Spiffy work with base.pm, a dirty trick was played.
394 Class::Spiffy swaps "base::import" with its own version. If the base
395 modules are not Spiffy, Class::Spiffy calls the original base::import.
396 If the base modules are Spiffy, then Class::Spiffy does its own thing.
397
398 There are two caveats.
399
400 * Class::Spiffy must be loaded first.
401 If Class::Spiffy is not loaded and "use base" is invoked on a
402 Class::Spiffy module, Class::Spiffy will die with a useful message
403 telling the author to read this documentation. That's because
404 Class::Spiffy needed to do the import swap beforehand.
405
406 If you get this error, simply put a statement like this up front in
407 your code:
408
409 use Class::Spiffy ();
410
411 * No Mixing
412 "base.pm" can take multiple arguments. And this works with
413 Class::Spiffy as long as all the base classes are Spiffy, or they
414 are all non-Spiffy. If they are mixed, Class::Spiffy will die. In
415 this case just use separate "use base" statements.
416
417 AUTHOR
418 Ingy döt Net <[email protected]>
419
420 COPYRIGHT
421 Copyright (c) 2006. Ingy döt Net. All rights reserved.
422
423 This program is free software; you can redistribute it and/or modify it
424 under the same terms as Perl itself.
425
426 See <http://www.perl.com/perl/misc/Artistic.html>
427