Debian Codegraph @

README

raw
1 PGObject
2
3 PGObject is a module intended to be a base for object class frameworks which map
4 PostgreSQL stored procedures to object methods in a relatively loosely coupled
5 way. PGObject provides the bare-bones infrastructure required to make it
6 happen. This module is primarily of interest to individuals writing such
7 frameworks, and very little in here is likely to be used directly outside of
8 such frameworks.
9
10 The initial release, 1.0.0 is based on our six years of experience using
11 essentially the same approach in LedgerSMB (starting with the beginnings of the
12 1.3 codebase in 2007). This release is largely based on the code I wrote for
13 LedgerSMB but it cleans up and refactors such work based on the lessons learned.
14
15 INSTALLATION
16
17 To install this module, run the following commands:
18
19 perl Makefile.PL
20 make
21 make test
22 make install
23
24 SUPPORT AND DOCUMENTATION
25
26 After installing, you can find documentation for this module with the
27 perldoc command.
28
29 perldoc PGObject
30
31 You can also look for information at:
32
33 RT, CPAN's request tracker (report bugs here)
34 https://rt.cpan.org/NoAuth/Bugs.html?Dist=PGObject
35
36 MetaCPAN
37 https://metacpan.org/dist/PGObject
38
39
40 WRITING PGOBJECT-AWARE PERL CLASSES
41
42 One of the powerful features of PGObject is the ability to declare methods in
43 types which can be dynamically detected and used to serialize data for query
44 purposes. Objects which contain a pgobject_to_db(), that method will be called
45 and the return value used in place of the object. This can allow arbitrary
46 types to serialize themselves in arbitrary ways.
47
48 For example a date object could be set up with such a method which would export
49 a string in yyyy-mm-dd format. An object could look up its own definition and
50 return something like :
51
52 { cast => 'dbtypename', value => '("A","List","Of","Properties")'}
53
54 If a scalar is returned that is used as the serialized value. If a hashref is
55 returned, it must follow the type format:
56
57 type => variable binding type,
58 cast => db cast type
59 value => literal representation of type, as intelligible by DBD::Pg
60
61
62 WRITING TOP-HALF OBJECT FRAMEWORKS FOR PGOBJECT
63
64 PGObject is intended to be the database-facing side of a framework for objects.
65 The intended structure is for three tiers of logic:
66
67 1. Database facing, low-level API's
68 2. Object management modules
69 3. Application handlers with things like database connection management.
70
71 By top half, we are referring to the second tier. The third tier exists in the
72 client application.
73
74 The PGObject module provides only low-level API's in that first tier. The job
75 of this module is to provide database function information to the upper level
76 modules.
77
78 We do not supply type information, If your top-level module needs this, please
79 check out https://code.google.com/p/typeutils/ which could then be used via our
80 function mapping APIs here.
81
82 LICENSE AND COPYRIGHT
83
84 COPYRIGHT (C) 2013-2014 Chris Travers
85 COPYRIGHT (C) 2014-2021 The LedgerSMB Core Team
86
87 Redistribution and use in source and compiled forms with or without
88 modification, are permitted provided that the following conditions are met:
89
90 * Redistributions of source code (Perl) must retain the above
91 copyright notice, this list of conditions and the following disclaimer as the
92 first lines of this file unmodified.
93
94 * Redistributions in compiled form must reproduce the above copyright
95 notice, this list of conditions and the following disclaimer in the
96 source code, documentation, and/or other materials provided with the
97 distribution.
98
99 THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) "AS IS" AND
100 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
101 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
102 DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR
103 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
104 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
105 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
106 ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
107 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
108 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.