NAME Spiffy - Spiffy Perl Interface Framework For You SYNOPSIS use Spiffy '-base'; DESCRIPTION "Spiffy" is a Perl module interface methodology and framework. It is a base class for implementing other Perl modules using my favorite tricks. Spiffy is different from other Perl object oriented base classes, in that it has the ability to export functions. If you create a subclass of Spiffy, all the functions that Spiffy exports will automatically be exported by your subclass, in addition to any functions that you want to export. And if someone creates a subclass of your subclass, all of those functions will be exported automatically, and so on. Spiffy has an interesting function that it exports called "spiffy_constructor()". This function will generate a function that will call the class's "new()" constructor. It is smart enough to know which class to use. All the arguments you pass to the generated function, get passed on to the constructor. In addition, all the arguments you passed in the use statement for that class, also get passed to the constructor. Spiffy has an interesting way of parsing arguments that you pass to "spiffy_constructor" generated functions, and also to "use" statements. You declare which arguments are boolean (singletons) and which ones are paired, with two special functions called "boolean_arguments" and "paired_arguments". Spiffy also exports a function called "attribute" that you can use to declare the attributes of your class. The "attribute" function will generate accessors for you. These attributes can be given defaults values as well. Perhaps this is all best described through an example. (These are meant to be three separate files): use Something qw(-cool); foo; bar; my $thing = thing(-name => 'Jimmy'); $thing->size(11); package Something; use Thing '-base'; attribute size => 0; @EXPORT = qw(foo); sub foo { ... } sub paired_arguments { my $self = shift; ('-name', $self->SUPER::paired_arguments) } 1; package Thing; use Spiffy '-base'; @EXPORT = qw(bar thing); sub bar { ... } spiffy_constructor 'thing'; sub boolean_arguments { my $self = shift; ('-cool', $self->SUPER::boolean_arguments) } 1; The top level program uses a module called "Something". "Something" exports 3 functions: "foo", "bar" and "thing". The "thing" function returns a new "Something" object. The "new()" method for the "Something" class is called with the arguments "<-name =" 'Jimmy'>>, and also with the arguments "<-cool =" 1>>. "Something" is a subclass of "Thing" and "Thing" is a subclass of "Spiffy". This is accomplished by importing the base classes with the special parameter "-base". This is similar to using the "base.pm" module except that it does all the extra Spiffy magic. That's Spiffy! Spiffy FUNCTIONS Spiffy defines a few functions that make it Spiffy. * attribute Defines accessor methods for an attribute of your class: package Example; use Spiffy '-base'; attribute 'foo'; attribute 'bar' => 42; The first parameter is the name of the attribute. The second optional argument is the default value. The "attribute" function is only exported if you use the '-base' option. * spiffy_constructor This function generates a function that calls the "new()" method for your class. It passes all its arguments on to "new", as well as any arguments passed to the "use" statement of your class. package Example; use Spiffy '-base'; @EXPORT = qw(foo); spiffy_constructor 'foo'; The "spiffy_constructor" function is only exported if you use the '- base' option. Spiffy METHODS The following subroutines are all methods rather than functions and should be called as such. For example: $self->parse_arguments(@arguments); * is_spiffy Returns true if an object is Spiffy. This method is UNIVERSAL so it can be called on all objects. * parse_arguments This method takes a list of arguments and groups them into pairs. It allows for boolean arguments which may or may not have a value (defaulting to 1). The method returns a hash reference of all the pairs as keys and values in the hash. Any arguments that cannot be paired, are returned as a list. Here is an example: sub boolean_arguments { qw(-has_spots -is_yummy) } sub paired_arguments { qw(-name -size) } my ($pairs, @others) = $self->parse_arguments( 'red', 'white', -name => 'Ingy', -has_spots => -size => 'large', 'black', -is_yummy => 0, ); After this call, $pairs will contain: { -name => 'Ingy', -has_spots => 1, -size => 'large', -is_yummy => 0, } and $others will contain 'red', 'white', and 'black'. * boolean_arguments Returns the list of arguments that are recognized as being boolean. Override this method to define your own list. * paired_arguments Returns the list of arguments that are recognized as being paired. Override this method to define your own list. * super This function is called without any arguments. It will call the same method that it is in, one level higher in the ISA tree, passing it all the same arguments. sub foo { my self = shift; super; # Same as $self->SUPER::foo(@_); $self->bar(42); } * XXX The "XXX" method will die with a YAML Dump of all the arguments passed to it. Used for debugging. Spiffy ARGUMENTS When you "use" the Spiffy module or a subclass of it, you can pass it a list of arguments. These arguments are parsed using the "parse_arguments" method described above. Any arguments that are pairs are passed on to calls to a spiffy_constructor generated function. The special argument "-base", is used to make the current package a subclass of the Spiffy module being used. Any non-paired parameters act like a normal import list; just like those used with the Exporter module. AUTHOR Brian Ingerson COPYRIGHT Copyright (c) 2004. Brian Ingerson. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See