.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Class::GAPI 3"
.TH Class::GAPI 3 "2005-10-07" "perl v5.22.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Class::GAPI \- Generic API, Base class with autoloaded methods, stub objects, cloning etc.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        package Guppy ;
\&
\&        use Class::GAPI                 ; # All of its cool stuff 
\&        our @ISA = qw(Class::GAPI)      ; # is now in our namespace
\&
\&        our @Children = qw(Class::GAPI::Fin Class::List::Eyeballs CGI)  ; # Autoconstruct Subordinates
\&        our @Default_Properties = qw(scaly small sushi)                         ; # Call at constructor time
\&
\&        use strict ;
\& 
\&        sub _init { # Last stage of initialization
\&                  my $self = shift ; 
\&                  $self\->fillet(1) if defined $self\->{\*(Aqsushi\*(Aq}; # sushi exists but is undefined
\&                return 1;
\&        }
\&        1 ;
\&
\&        package Petstore ; 
\&        use Guppy        ; 
\&        my $pet = Guppy\->new(color => \*(Aqorange\*(Aq, price => \*(Aq.50\*(Aq, small => 1, \-sushi => 1) ; # envoke these functions
\&        $pet\->Eyeballs\->[0] = "left"    ; # Access a special list subclass
\&        $pet\->Eyeballs\->[1] = "right"   ; # 
\&        $pet\->Fin\->dorsal("polkadot")   ; # Access a subordinate Class::GAPI object
\&        $pet\->Fin\->tail("orange")       ; #
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a foundation class. It is intended to be inhertied and used as a framework for other 
objects. This module features autoloaded methods (set+get as one method), three styles of 
initialization, tools for handling stub objects, and cloning. It is particularly well suited 
to handling record list type structures, deeply nested trees and those on-the-fly data structures
that give Perl a reputation as being a language of line noise.  \s-1GAPI\s0 breaks a few rules and 
create a few others. Overall it just makes coding complex nested data structures a heck of a lot 
easier.
.SH "AUTOLOADED METHODS"
.IX Header "AUTOLOADED METHODS"
Probably the most used part of this module is the autoloaded methods. One can access them from 
a few places. First by constructing the widget with a hash
.PP
.Vb 1
\&        my $pet = Guppy\->new(foo => "bar") ;
.Ve
.PP
This is the same as saying:
.PP
.Vb 2
\&        my $pet = Guppy\->new() ;
\&        $pet\->foo("bar")       ;
.Ve
.PP
which is the same thing as saying:
.PP
.Vb 2
\&        my $pet = Guppy\->new() ;
\&        $pet\->{\*(Aqfoo\*(Aq} = \*(Aqbar\*(Aq  ;
.Ve
.PP
So all methods are autoloaded. A side effect is that typo'd function calls 
generally will not cause a crash, but rather quitely create an additional 
property. This can also be viewed as a feature, in that you can call nonexistant 
functions in \s-1GAPI\s0 objects, thereby allowing you to write you code a bit more top-down 
and it will be more tolerable of things you haven't added yet.
.PP
All autoloaded methods add properties, never deleting them. To undefine something 
call it as a hash.  (the variable \*(L"_init\*(R" is reserved and does not autoload, 
you'll see why later)
.PP
.Vb 2
\&        undef $pet\->{\*(Aqfoo\*(Aq}  ; # no foo for you 
\&        delete $pet\->{\*(Aqfoo\*(Aq} ; # de\-exist foo.
.Ve
.PP
Passing a hash or array to a function returns a reference to the respective type, as does just 
calling an empty function on a property that contains a hash or array.  And they may be constructed 
on the fly. So you can:
.PP
.Vb 1
\&        my $hashref = $pet\->magician(tophat => \*(Aqbunny\*(Aq) ;
.Ve
.PP
But don't do this. Forget I mentioned it. Instead use the \fIsprout()\fR function 
which is \s-1GAPI\s0 for creating \s-1GAPI\s0 based subclasses. \fIsprout()\fRed classes will 
then also support autoloaded methods and other \s-1GAPI\s0 functions.
.PP
.Vb 1
\&        $pet\->sprout(\*(Aqmagician\*(Aq, tophat => \*(Aqbunny\*(Aq)        ; # $pet\->{\*(Aqmagician\*(Aq} is now a Class::GAPI object
\&
\&        my $wascallywabit = $pet\->magician\->tophat()       ; # get the rabbit  
\&        $pet\->magician\->tophat(\*(Aqdove\*(Aq)                     ; # replace it with a dove
.Ve
.PP
Now, back to the constructor:
.PP
.Vb 1
\&        my $pet = Guppy\->new(foo => "bar") ;
.Ve
.PP
This does not just set \f(CW$pet\fR\->{'foo'} to \*(L"bar\*(R", it invoke the function 'foo' on \*(L"bar\*(R", and 
the autoloaded function is what does the set/get. So it is important to note that one can preempt 
this behavior simply by defining a function as follows:
.PP
.Vb 5
\&        sub foo { 
\&                my $self = shift ; 
\&                my $bar = shift  ; 
\&                print "a guppy walks into a $bar and says: Ouch.\en" ;
\&        }
.Ve
.SH "OBJECT INITIALIZATION"
.IX Header "OBJECT INITIALIZATION"
Class::GAPI has three stages of initialization at constructor time. The first which we just 
discussed is by calling passed arguments as functions. The second is by evaluating two class 
wide predefined arrays. They are:
.PP
.Vb 2
\&        our @Default_Properties = qw(scaly small sushi) ; # execute some functions during new()
\&        our @Children = qw(Class::GAPI::Fin Class::List::Eyeballs) ; # make some branches on our tree
.Ve
.PP
\&\f(CW@Default_Properties\fR is easy. Anything named here is called just as if it was passed as an 
option with an undefined value. So the example above is the same as:
.PP
.Vb 1
\&        my $pet = Guppy\->new(scaly => undef, small => undef, sushi => undef) ;
.Ve
.PP
\&\f(CW@Default_Properties\fR is not used that often, in that the other Initialization stages can 
do more than \f(CW@Default_Properties\fR. It is handy from time to time when you want to add 
something complicated to the objects initialization and don't need to pass any special 
arguments. (Like I said, rarely used) It is also trumped by any same-named passed option 
pair from stage 1. So you you can define this as a hail marry for any function that should 
be run at constructor time, even if the caller doesn't send an option pair.
.PP
\&\f(CW@Children\fR is a list of subordinate objects to call \->\fInew()\fR on at constructor time. This allows 
Class::GAPI based objects to include other classes in a sem-codeless fashion. Just \*(L"use\*(R" something 
and stick it in Children, and you will get one built. (No options will be passed, but it will 
built.) So for example you can do this:
.PP
.Vb 1
\&        package Guppy ; 
\&
\&        use CGI                    ;
\&        use Class::GAPI            ; 
\&        our @ISA = qw(Class::GAPI) ;  
\&        our @Children = qw(CGI)    ;
\&        1 ;
.Ve
.PP
Which will then allow you to do this:
.PP
.Vb 2
\&        my $pet = Guppy\->new()      ; 
\&        my $SwimTowardstheLight = $pet\->CGI\->param("fishhook") ; # Extract CGI parameter "fishhook"
.Ve
.PP
Class::GAPI will always use the right-most namespace fragment as the option in the option => value pair. (This may 
cause a namespace conflict from time to time, in those cases just use the third stage _init instead.) So for example:
.PP
.Vb 7
\&        package SpyGuppy           ; 
\&        use Crypt::CBC             ; # block handler
\&        use Crypt::DES             ; # Encryption Algorythm. 
\&        use Class::GAPI            ; 
\&        our @ISA = qw(Class::GAPI) ;  
\&        our @Children = qw(Crypt::CBC Crypt::DES) ;
\&        1 ;
.Ve
.PP
and then do:
.PP
.Vb 3
\&        my $pet = SpyGuppy\->new()       ; 
\&        $pet\->CBC\->something()          ;
\&        $pet\->DES\->somethingelse()      ;
.Ve
.PP
\&\f(CW@Children\fR also conveiniently has 2 special class names. Class::GAPI::Foo, and Class::List::Foo. In 
this case \*(L"Foo\*(R" can be anything you like, and will correspondingly be used to create a 
\&\fIsprout()\fRed object. Note that Class::GAPI::Foo is a a sprouted hash, while Class::List::Foo 
is a sprouted array. This is very convenient for making lists of objects. The technique below can be used 
to quickly create a variety of styles of record manager classes.
.PP
.Vb 4
\&        package Guppy::School   ; 
\&        use Guppy               ; 
\&        our @ISA = qw(Guppy)    ; # We are derived from a Guppy, which is derived from a GAPI  
\&        our @Children = qw(Class::List::School) ; # $self\->{\*(AqSchool\*(Aq} is now an array
\&
\&        sub doSpawn { # Add a new Guppy Object
\&                my $self = shift                         ;       
\&                my $fish = Guppy\->new()          ; 
\&                push @{$self\->School()}, $fish ; 
\&        }
\&
\&        sub fishNet { # Get a specific Guppy object 
\&                my $self = shift                 ; 
\&                my $n = shift                    ; 
\&                my $fish = $self\->School\->[$n] ;
\&                return($fish)                    ;   
\&        }
\&        1 ;
.Ve
.PP
The third stage of initialization is by defining a local &_init subroutine. This gets called after everything else. So if one desires to 
do something with passed variables after the class is blessed, this is where to do it. If you call an autoloaded function here, it takes place 
after autoloaded functions from \->\fInew()\fR, and Default_Properties. So you do have access to data passed or processed during invokation.
.PP
passed at invokation:
.PP
.Vb 4
\&        package Guppy           ; 
\&        use Class::GAPI         ; 
\&        our @ISA = (Class::GAPI);
\&        use strict              ; 
\& 
\&        sub _init {
\&                my $self = shift ; 
\&                $self\->chopchopchop() if $self\->sushi() && $self\->filet() ; 
\&        }
\&        1 ; 
\&
\&        package PetShop ; 
\&        use Guppy       ; 
\&
\&        my $pet = Guppy\->new(\-sushi => 0, \-filet => undef) ; 
\&        my $lunch = Guppy\->new(\-sushi => 1, \-filet => 1)   ;
.Ve
.PP
In this case the execution of method chopchopchop would occur 
in the case of lunch but not in the case of pet.
.SH "OTHER FUNCTIONS"
.IX Header "OTHER FUNCTIONS"
Cloning is supported for Class::GAPI objects and any subordinate objects based on Class::GAPI
or that Inherit Class::GAPI. This includes Class::List objects. This is function is \fIeval()\fRd, so it 
will not crash if you have other stuff in their, just don't expect that other stuff copy.
.PP
.Vb 1
\&        my $twin = $pet\->clone(); # Make the FDA nervous
.Ve
.PP
The \fIoverlay()\fR function allows one to execute a block of functions by passing hash.  This is equivilant 
to what happens when constructed with \fInew()\fR. This is typically usefull when you want to copy a hash 
into several objects as you might in a record table:
.PP
.Vb 4
\&        package Guppy::School   ; 
\&        use Guppy               ; 
\&        our @ISA = qw(Guppy)    ; # We are derived from a Guppy, which is derived from a GAPI  
\&        our @Children = qw(Class::List::School) ; # $self\->{\*(AqSchool\*(Aq} is now an array
\&
\&        sub doSpawn { # Add a new Guppy Object
\&                my $self = shift                ;
\&                my $fish = Guppy\->new(@_)       ; # Pass options pairs to the new fish 
\&                push @{$self\->School()}, $fish  ; 
\&        }
\&
\&        sub fishGrow { # Add a block of options like so: fishGrow(2, foo => \*(Aqbar\*(Aq) ;  
\&                my $self = shift                ; 
\&                my $n = shift                   ; 
\&                $self\->School\->[$n]\->overlay(@_); 
\&                return($fish)                   ;   
\&        }
\&        1 ;
.Ve
.PP
The \fIwarn_self()\fR function is pretty much what it sounds like. You can call it at any level with 
a tree of nested \s-1GAPI\s0 and it will produce a table of the object as a warning. Obviously this 
handy for debugging:
.PP
.Vb 2
\&        $self\->warn_self() ;
\&        $self\->Foo\->Bar\->warn_self() ;
.Ve
.SH "NOTES"
.IX Header "NOTES"
It is worth noting that \s-1GAPI\s0 uses a lot of \fIeval()\fR calls. So it is fairly slow. Also special 
care should be given to using this module in \s-1CGI\s0 because of that. You should probably 
read the code and understand how the constructor works before even considering using this 
thing in cgi code. Consider yourself warned.
.PP
This was written on an Win32 box running cygwin and Activestate, and it works on both with Perl 5.8. 
I expect it should work with anything later than 5.6.1, but It hasn't been tested.
.PP
Autoloaded methods tend to cause silent failure modes. Essentially typos that would have 
normally crashed perl will often just end up creating a dangling property somewhere. 
Use \f(CW$self\fR\->\fIwarn_self()\fR to take snapshots of objects if something is not getting properly 
populated. If you see two similarly named properties, you've found the culprit.
.PP
No animals were harmed in the development of this module.
.SH "AUTHOR"
.IX Header "AUTHOR"
Matthew Sibley 
matt@itoperators.com
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
Copyright (C) 2005 Crosswire Industries Inc.  (http://www.itoperators.com)
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.6 or,
at your option, any later version of Perl 5 you may have available.