PGObject

PGObject is a module intended to be a base for object class frameworks which map
PostgreSQL stored procedures to object methods in a relatively loosely coupled
way.  PGObject provides the bare-bones infrastructure required to make it 
happen.  This module is primarily of interest to individuals writing such 
frameworks, and very little in here is likely to be used directly outside of 
such frameworks.

The initial release, 1.0.0 is based on our six years of experience using 
essentially the same approach in LedgerSMB (starting with the beginnings of the
1.3 codebase in 2007).  This release is largely based on the code I wrote for
LedgerSMB but it cleans up and refactors such work based on the lessons learned.

INSTALLATION

To install this module, run the following commands:

	perl Makefile.PL
	make
	make test
	make install

SUPPORT AND DOCUMENTATION

After installing, you can find documentation for this module with the
perldoc command.

    perldoc PGObject

You can also look for information at:

    RT, CPAN's request tracker (report bugs here)
        http://rt.cpan.org/NoAuth/Bugs.html?Dist=PGObject

    AnnoCPAN, Annotated CPAN documentation
        http://annocpan.org/dist/PGObject

    CPAN Ratings
        http://cpanratings.perl.org/d/PGObject

    Search CPAN
        http://search.cpan.org/dist/PGObject/


WRITING PGOBJECT-AWARE PERL CLASSES

One of the powerful features of PGObject is the ability to declare methods in 
types which can be dynamically detected and used to serialize data for query 
purposes. Objects which contain a pgobject_to_db(), that method will be called
and the return value used in place of the object.  This can allow arbitrary 
types to serialize themselves in arbitrary ways.

For example a date object could be set up with such a method which would export 
a string in yyyy-mm-dd format.  An object could look up its own definition and
return something like :

   { cast => 'dbtypename', value => '("A","List","Of","Properties")'}

If a scalar is returned that is used as the serialized value.  If a hashref is 
returned, it must follow the type format:

  type  => variable binding type,
  cast  => db cast type
  value => literal representation of type, as intelligible by DBD::Pg


WRITING TOP-HALF OBJECT FRAMEWORKS FOR PGOBJECT

PGObject is intended to be the database-facing side of a framework for objects. 
The intended structure is for three tiers of logic:

 1.  Database facing, low-level API's
 2.  Object management modules 
 3.  Application handlers with things like database connection management.

By top half, we are referring to the second tier.  The third tier exists in the 
client application.

The PGObject module provides only low-level API's in that first tier.  The job
of this module is to provide database function information to the upper level 
modules.  

We do not supply type information, If your top-level module needs this, please
check out https://code.google.com/p/typeutils/ which could then be used via our
function mapping APIs here.

LICENSE AND COPYRIGHT

Copyright (C) 2013 Chris Travers

Redistribution and use in source and compiled forms with or without 
modification, are permitted provided that the following conditions are met:

*  Redistributions of source code (Perl) must retain the above
   copyright notice, this list of conditions and the following disclaimer as the
   first lines of this file unmodified.

*  Redistributions in compiled form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   source code, documentation, and/or other materials provided with the 
   distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.