1Spiffy(3)             User Contributed Perl Documentation            Spiffy(3)
2
3
4

NAME

6       Spiffy - Spiffy Perl Interface Framework For You
7

SYNOPSIS

9           package Keen;
10           use Spiffy -Base;
11           field 'mirth';
12           const mood => ':-)';
13
14           sub happy {
15               if ($self->mood eq ':-(') {
16                   $self->mirth(-1);
17                   print "Cheer up!";
18               }
19               super;
20           }
21

DESCRIPTION

23       "Spiffy" is a framework and methodology for doing object oriented (OO)
24       programming in Perl. Spiffy combines the best parts of Exporter.pm,
25       base.pm, mixin.pm and SUPER.pm into one magic foundation class. It
26       attempts to fix all the nits and warts of traditional Perl OO, in a
27       clean, straightforward and (perhaps someday) standard way.
28
29       Spiffy borrows ideas from other OO languages like Python, Ruby, Java
30       and Perl 6. It also adds a few tricks of its own.
31
32       If you take a look on CPAN, there are a ton of OO related modules. When
33       starting a new project, you need to pick the set of modules that makes
34       most sense, and then you need to use those modules in each of your
35       classes. Spiffy, on the other hand, has everything you'll probably need
36       in one module, and you only need to use it once in one of your classes.
37       If you make Spiffy.pm the base class of the basest class in your
38       project, Spiffy will automatically pass all of its magic to all of your
39       subclasses. You may eventually forget that you're even using it!
40
41       The most striking difference between Spiffy and other Perl object
42       oriented base classes, is that it has the ability to export things. If
43       you create a subclass of Spiffy, all the things that Spiffy exports
44       will automatically be exported by your subclass, in addition to any
45       more things that you want to export. And if someone creates a subclass
46       of your subclass, all of those things will be exported automatically,
47       and so on. Think of it as "Inherited Exportation", and it uses the
48       familiar Exporter.pm specification syntax.
49
50       To use Spiffy or any subclass of Spiffy as a base class of your class,
51       you specify the "-base" argument to the "use" command.
52
53           use MySpiffyBaseModule -base;
54
55       You can also use the traditional "use base 'MySpiffyBaseModule';"
56       syntax and everything will work exactly the same. The only caveat is
57       that Spiffy.pm must already be loaded. That's because Spiffy rewires
58       base.pm on the fly to do all the Spiffy magics.
59
60       Spiffy has support for Ruby-like mixins with Perl6-like roles. Just
61       like "base" you can use either of the following invocations:
62
63           use mixin 'MySpiffyBaseModule';
64           use MySpiffyBaseModule -mixin;
65
66       The second version will only work if the class being mixed in is a
67       subclass of Spiffy. The first version will work in all cases, as long
68       as Spiffy has already been loaded.
69
70       To limit the methods that get mixed in, use roles. (Hint: they work
71       just like an Exporter list):
72
73           use MySpiffyBaseModule -mixin => qw(:basics x y !foo);
74
75       In object oriented Perl almost every subroutine is a method. Each
76       method gets the object passed to it as its first argument. That means
77       practically every subroutine starts with the line:
78
79           my $self = shift;
80
81       Spiffy provides a simple, optional filter mechanism to insert that line
82       for you, resulting in cleaner code. If you figure an average method has
83       10 lines of code, that's 10% of your code! To turn this option on, you
84       just use the "- Base" option instead of the "-base" option, or add the
85       "-selfless" option.  If source filtering makes you queazy, don't use
86       the feature. I personally find it addictive in my quest for writing
87       squeaky clean, maintainable code.
88
89       A useful feature of Spiffy is that it exports two functions: "field"
90       and "const" that can be used to declare the attributes of your class,
91       and automatically generate accessor methods for them. The only
92       difference between the two functions is that "const" attributes can not
93       be modified; thus the accessor is much faster.
94
95       One interesting aspect of OO programming is when a method calls the
96       same method from a parent class. This is generally known as calling a
97       super method.  Perl's facility for doing this is butt ugly:
98
99           sub cleanup {
100               my $self = shift;
101               $self->scrub;
102               $self->SUPER::cleanup(@_);
103           }
104
105       Spiffy makes it, er, super easy to call super methods. You just use the
106       "super" function. You don't need to pass it any arguments because it
107       automatically passes them on for you. Here's the same function with
108       Spiffy:
109
110           sub cleanup {
111               $self->scrub;
112               super;
113           }
114
115       Spiffy has a special method for parsing arguments called
116       "parse_arguments", that it also uses for parsing its own arguments. You
117       declare which arguments are boolean (singletons) and which ones are
118       paired, with two special methods called "boolean_arguments" and
119       "paired_arguments". Parse arguments pulls out the booleans and pairs
120       and returns them in an anonymous hash, followed by a list of the
121       unmatched arguments.
122
123       Finally, Spiffy can export a few debugging functions "WWW", "XXX",
124       "YYY" and "ZZZ". Each of them produces a YAML dump of its arguments.
125       WWW warns the output, XXX dies with the output, YYY prints the output,
126       and ZZZ confesses the output. If YAML doesn't suit your needs, you can
127       switch all the dumps to Data::Dumper format with the "-dumper" option.
128
129       That's Spiffy!
130

EXPORTING

132       Spiffy implements a completely new idea in Perl. Modules that act both
133       as object oriented classes and that also export functions. But it takes
134       the concept of Exporter.pm one step further; it walks the entire @ISA
135       path of a class and honors the export specifications of each module.
136       Since Spiffy calls on the Exporter module to do this, you can use all
137       the fancy interface features that Exporter has, including tags and
138       negation.
139
140       Spiffy considers all the arguments that don't begin with a dash to
141       comprise the export specification.
142
143           package Vehicle;
144           use Spiffy -base;
145           our $SERIAL_NUMBER = 0;
146           our @EXPORT = qw($SERIAL_NUMBER);
147           our @EXPORT_BASE = qw(tire horn);
148
149           package Bicycle;
150           use Vehicle -base, '!field';
151           $self->inflate(tire);
152
153       In this case, "Bicycle->isa('Vehicle')" and also all the things that
154       "Vehicle" and "Spiffy" export, will go into "Bicycle", except "field".
155
156       Exporting can be very helpful when you've designed a system with
157       hundreds of classes, and you want them all to have access to some
158       functions or constants
159
160             or variables. Just export them in your main base class and every subclass
161
162       will get the functions they need.
163
164       You can do almost everything that Exporter does because Spiffy
165       delegates the job to Exporter (after adding some Spiffy magic). Spiffy
166       offers a @EXPORT_BASE variable which is like @EXPORT, but only for
167       usages that use "-base".
168

MIXINS & ROLES

170       If you've done much OO programming in Perl you've probably used
171       Multiple Inheritance (MI), and if you've done much MI you've probably
172       run into weird problems and headaches. Some languages like Ruby,
173       attempt to resolve MI issues using a technique called mixins.
174       Basically, all Ruby classes use only Single Inheritance (SI), and then
175       mixin functionality from other modules if they need to.
176
177       Mixins can be thought of at a simplistic level as importing the methods
178       of another class into your subclass. But from an implementation
179       standpoint that's not the best way to do it. Spiffy does what Ruby
180       does. It creates an empty anonymous class, imports everything into that
181       class, and then chains the new class into your SI ISA path. In other
182       words, if you say:
183
184           package AAA;
185           use BBB -base;
186           use CCC -mixin;
187           use DDD -mixin;
188
189       You end up with a single inheritance chain of classes like this:
190
191           AAA << AAA-DDD << AAA-CCC << BBB;
192
193       "AAA-DDD" and "AAA-CCC" are the actual package names of the generated
194       classes. The nice thing about this style is that mixing in CCC doesn't
195       clobber any methods in AAA, and DDD doesn't conflict with AAA or CCC
196       either. If you mixed in a method in CCC that was also in AAA, you can
197       still get to it by using "super".
198
199       When Spiffy mixes in CCC, it pulls in all the methods in CCC that do
200       not begin with an underscore. Actually it goes farther than that. If
201       CCC is a subclass it will pull in every method that CCC "can" do
202       through inheritance. This is very powerful, maybe too powerful.
203
204       To limit what you mixin, Spiffy borrows the concept of Roles from
205       Perl6. The term role is used more loosely in Spiffy though. It's much
206       like an import list that the Exporter module uses, and you can use
207       groups (tags) and negation. If the first element of your list uses
208       negation, Spiffy will start with all the methods that your mixin class
209       can do.
210
211           use EEE -mixin => qw(:tools walk !run !:sharp_tools);
212
213       In this example, "walk" and "run" are methods that EEE can do, and
214       "tools" and "sharp_tools" are roles of class EEE. How does class EEE
215       define these roles? It very simply defines methods called "_role_tools"
216       and "_role_sharp_tools" which return lists of more methods. (And
217       possibly other roles!) The neat thing here is that since roles are just
218       methods, they too can be inherited. Take that Perl6!
219

FILTERING

221       By using the "-Base" flag instead of "-base" you never need to write
222       the line:
223
224           my $self = shift;
225
226       This statement is added to every subroutine in your class by using a
227       source filter. The magic is simple and fast, so there is litte
228       performance penalty for creating clean code on par with Ruby and
229       Python.
230
231           package Example;
232           use Spiffy -Base;
233
234           sub crazy {
235               $self->nuts;
236           }
237           sub wacky { }
238           sub new() {
239               bless [], shift;
240           }
241
242       is exactly the same as:
243
244           package Example;
245           use Spiffy -base;
246           use strict;use warnings;
247           sub crazy {my $self = shift;
248               $self->nuts;
249           }
250           sub wacky {my $self = shift; }
251           sub new {
252               bless [], shift;
253           }
254           ;1;
255
256       Note that the empty parens after the subroutine "new" keep it from
257       having a $self added. Also note that the extra code is added to
258       existing lines to ensure that line numbers are not altered.
259
260       "-Base" also turns on the strict and warnings pragmas, and adds that
261       annoying '1;' line to your module.
262

PRIVATE METHODS

264       Spiffy now has support for private methods when you use the '-Base'
265       filter mechanism. You just declare the subs with the "my" keyword, and
266       call them with a '$' in front. Like this:
267
268           package Keen;
269           use SomethingSpiffy -Base;
270
271           # normal public method
272           sub swell {
273               $self->$stinky;
274           }
275
276           # private lexical method. uncallable from outside this file.
277           my sub stinky {
278               ...
279           }
280

SPIFFY DEBUGGING

282       The XXX function is very handy for debugging because you can insert it
283       almost anywhere, and it will dump your data in nice clean YAML. Take
284       the following statement:
285
286           my @stuff = grep { /keen/ } $self->find($a, $b);
287
288       If you have a problem with this statement, you can debug it in any of
289       the following ways:
290
291           XXX my @stuff = grep { /keen/ } $self->find($a, $b);
292           my @stuff = XXX grep { /keen/ } $self->find($a, $b);
293           my @stuff = grep { /keen/ } XXX $self->find($a, $b);
294           my @stuff = grep { /keen/ } $self->find(XXX $a, $b);
295
296       XXX is easy to insert and remove. It is also a tradition to mark
297       uncertain areas of code with XXX. This will make the debugging dumpers
298       easy to spot if you forget to take them out.
299
300       WWW and YYY are nice because they dump their arguments and then return
301       the arguments. This way you can insert them into many places and still
302       have the code run as before. Use ZZZ when you need to die with both a
303       YAML dump and a full stack trace.
304
305       The debugging functions are exported by default if you use the "-base"
306       option, but only if you have previously used the "-XXX" option. To
307       export all 4 functions use the export tag:
308
309           use SomeSpiffyModule ':XXX';
310
311       To force the debugging functions to use Data::Dumper instead of YAML:
312
313           use SomeSpiffyModule -dumper;
314

SPIFFY FUNCTIONS

316       This section describes the functions the Spiffy exports. The "field",
317       "const", "stub" and "super" functions are only exported when you use
318       the "-base" or "-Base" options.
319
320       field
321           Defines accessor methods for a field of your class:
322
323               package Example;
324               use Spiffy -Base;
325
326               field 'foo';
327               field bar => [];
328
329               sub lalala {
330                   $self->foo(42);
331                   push @{$self->{bar}}, $self->foo;
332               }
333
334           The first parameter passed to "field" is the name of the attribute
335           being defined. Accessors can be given an optional default value.
336           This value will be returned if no value for the field has been set
337           in the object.
338
339       const
340               const bar => 42;
341
342           The "const" function is similar to <field> except that it is
343           immutable.  It also does not store data in the object. You probably
344           always want to give a "const" a default value, otherwise the
345           generated method will be somewhat useless.
346
347       stub
348               stub 'cigar';
349
350           The "stub" function generates a method that will die with an
351           appropriate message. The idea is that subclasses must implement
352           these methods so that the stub methods don't get called.
353
354       super
355           If this function is called without any arguments, it will call the
356           same method that it is in, higher up in the ISA tree, passing it
357           all the same arguments.  If it is called with arguments, it will
358           use those arguments with $self in the front. In other words, it
359           just works like you'd expect.
360
361               sub foo {
362                   super;             # Same as $self->SUPER::foo(@_);
363                   super('hello');    # Same as $self->SUPER::foo('hello');
364                   $self->bar(42);
365               }
366
367               sub new() {
368                   my $self = super;
369                   $self->init;
370                   return $self;
371               }
372
373           "super" will simply do nothing if there is no super method.
374           Finally, "super" does the right thing in AUTOLOAD subroutines.
375

METHODS

377       This section lists all of the methods that any subclass of Spiffy
378       automatically inherits.
379
380       mixin
381           A method to mixin a class at runtime. Takes the same arguments as
382           "use mixin ...". Makes the target class a mixin of the caller.
383
384               $self->mixin('SomeClass');
385               $object->mixin('SomeOtherClass' => 'some_method');
386
387       parse_arguments
388           This method takes a list of arguments and groups them into pairs.
389           It allows for boolean arguments which may or may not have a value
390           (defaulting to 1).  The method returns a hash reference of all the
391           pairs as keys and values in the hash. Any arguments that cannot be
392           paired, are returned as a list. Here is an example:
393
394               sub boolean_arguments { qw(-has_spots -is_yummy) }
395               sub paired_arguments { qw(-name -size) }
396               my ($pairs, @others) = $self->parse_arguments(
397                   'red', 'white',
398                   -name => 'Ingy',
399                   -has_spots =>
400                   -size => 'large',
401                   'black',
402                   -is_yummy => 0,
403               );
404
405           After this call, $pairs will contain:
406
407               {
408                   -name => 'Ingy',
409                   -has_spots => 1,
410                   -size => 'large',
411                   -is_yummy => 0,
412               }
413
414           and @others will contain 'red', 'white', and 'black'.
415
416       boolean_arguments
417           Returns the list of arguments that are recognized as being boolean.
418           Override this method to define your own list.
419
420       paired_arguments
421           Returns the list of arguments that are recognized as being paired.
422           Override this method to define your own list.
423

ARGUMENTS

425       When you "use" the Spiffy module or a subclass of it, you can pass it a
426       list of arguments. These arguments are parsed using the
427       "parse_arguments" method described above. The special argument "-base",
428       is used to make the current package a subclass of the Spiffy module
429       being used.
430
431       Any non-paired parameters act like a normal import list; just like
432       those used with the Exporter module.
433

USING SPIFFY WITH BASE.PM

435       The proper way to use a Spiffy module as a base class is with the
436       "-base" parameter to the "use" statement. This differs from typical
437       modules where you would want to "use base".
438
439           package Something;
440           use Spiffy::Module -base;
441           use base 'NonSpiffy::Module';
442
443       Now it may be hard to keep track of what's Spiffy and what is not.
444       Therefore Spiffy has actually been made to work with base.pm. You can
445       say:
446
447           package Something;
448           use base 'Spiffy::Module';
449           use base 'NonSpiffy::Module';
450
451       "use base" is also very useful when your class is not an actual module
452       (a separate file) but just a package in some file that has already been
453       loaded.  "base" will work whether the class is a module or not, while
454       the "-base" syntax cannot work that way, since "use" always tries to
455       load a module.
456
457   base.pm Caveats
458       To make Spiffy work with base.pm, a dirty trick was played. Spiffy
459       swaps "base::import" with its own version. If the base modules are not
460       Spiffy, Spiffy calls the original base::import. If the base modules are
461       Spiffy, then Spiffy does its own thing.
462
463       There are two caveats.
464
465       Spiffy must be loaded first.
466           If Spiffy is not loaded and "use base" is invoked on a Spiffy
467           module, Spiffy will die with a useful message telling the author to
468           read this documentation.  That's because Spiffy needed to do the
469           import swap beforehand.
470
471           If you get this error, simply put a statement like this up front in
472           your code:
473
474               use Spiffy ();
475
476       No Mixing
477           "base.pm" can take multiple arguments. And this works with Spiffy
478           as long as all the base classes are Spiffy, or they are all non-
479           Spiffy. If they are mixed, Spiffy will die. In this case just use
480           separate "use base" statements.
481

SPIFFY TODO LIST

483       Spiffy is a wonderful way to do OO programming in Perl, but it is still
484       a work in progress. New things will be added, and things that don't
485       work well, might be removed.
486

AUTHOR

488       Ingy döt Net <ingy@cpan.org>
489
491       Copyright 2004-2014. Ingy döt Net.
492
493       This program is free software; you can redistribute it and/or modify it
494       under the same terms as Perl itself.
495
496       See <http://www.perl.com/perl/misc/Artistic.html>
497
498
499
500perl v5.36.0                      2023-01-20                         Spiffy(3)
Impressum