The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
EHUELS / PGObject-1.403.2 / README.md

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:

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.