README 4.16 KB
Newer Older
ryszard.szopa's avatar
README  
ryszard.szopa committed
1
2

Submarine is a Common Lisp library that's somewhere between a
ryszard.szopa's avatar
README    
ryszard.szopa committed
3
4
5
6
7
8
PostgreSQL library an an object persistency system.  It uses
Postmodern to communicate with the database. The basic idea is that
you create your classes in the metaclass DB-CLASS and submarine cares
about creating SQL tables or, if the tables already exist, checking if
they conform to the provided specification.  Moreover, Submarine
supports an intuitive way of expressing both one-to-many and
ryszard.szopa's avatar
README  
ryszard.szopa committed
9
10
11
12
many-to-many relations.

Getting submarine
=================
13

ryszard.szopa's avatar
README  
ryszard.szopa committed
14
15
16
17
At the moment there's only a darcs repository available:
   
    darcs pull http://bender.streamtech.nl/darcs/submarine/

ryszard.szopa's avatar
ryszard.szopa committed
18
19
You will also need my mop-utilities, which may be incorporated into
submarine in the close future:
ryszard.szopa's avatar
README  
ryszard.szopa committed
20
21
22
23

    darcs get http://bender.streamtech.nl/darcs/mop-utils

Dependencies
24
25
26
27
28
29
============ 

Submarine depends on Postmodern and Iterate.
It uses also my library of MOP utilities, MOP-UTILS, which may become
a separate library in the future.  On platforms other than SBCL,
mop-utils needs Closer-mop.
ryszard.szopa's avatar
README  
ryszard.szopa committed
30
31
32

License
=======
33

ryszard.szopa's avatar
README  
ryszard.szopa committed
34
35
36
37
38
39
Submarine is released under a BSD-like license. Which approximately
means you can use the code in whatever way you like, except for
passing it off as your own or releasing a modified version without
indication that it is not the original.

Relation to Postmodern
ryszard.szopa's avatar
README    
ryszard.szopa committed
40
======================
ryszard.szopa's avatar
README  
ryszard.szopa committed
41
42
43
44
45

Submarine started as a patch that added, among others, foreign keys
support to Postmodern.  This meant hacking the DEFTABLE macro and
TABLE and TABLEFIELD classes.  After some time I realized that my
modified Postmodern macros had become far too large and heavy to be
ryszard.szopa's avatar
README    
ryszard.szopa committed
46
47
easy maintainable. So, I decided to leave Postmodern's code as it was
and write a separate library.
ryszard.szopa's avatar
README  
ryszard.szopa committed
48

ryszard.szopa's avatar
README    
ryszard.szopa committed
49
50
Introduction for Postmodern users
=================================
ryszard.szopa's avatar
README  
ryszard.szopa committed
51
52
53
54
55
56
57
58

Submarine tries to keep as much as possible of Postmodern's original
API. I use the same terminology, and functions with similar names will
probably do very similar things. My purpose was twofold. First of all,
I wanted to make porting programs using Postmodern to Submarine
easy. Secondly, this would allow me to use some of Marijn Haverbeke's
superb documentation nearly without any changes.

ryszard.szopa's avatar
ryszard.szopa committed
59
Main differences between Postmodern and Submarine:
ryszard.szopa's avatar
README  
ryszard.szopa committed
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

 * You don't have to create DAO (database access object) classes and SQL
tables separately. You just create classes belonging to a certain
metaclass, and the library cares of the rest.

 * If the table with an appropriate name exists in the database,
Submarine will test if it has columns with the right names and
types. If a column does not exist or has a wrong type, Submarine will
offer the user a possibility to fix it. Submarine will warn, but do
nothing about any additional columns in the table.

 * Each DB-CLASS class has its own connection specification. This means
that you can just access your objects, without wrapping them in a
WITH-CONNECTION macro, and they will care about setting the right
connection.

 * DAO is a basis class for DB-CLASS classes, and methods that are
supposed to work on an object of any DB-CLASS class use DAO as a
dispatch type. Of course, you don't have to use DAO as a base class,
but it makes a lot of things easier.

 * Submarine supports foreign keys. If you define a DB-CLASS class
with a slot whose type is another DB-CLASS, it is treated as foreign
key and an appropriate constraint is added to the database.

 * Submarine provides a function to retrieve all the elements of a
given type standing in a many-to-one relation with some DAO object.

 * The DEF-MANY-TO-MANY macro defines a many-to-many relation between
two classes and creates methods appropriate to their retrieval (it
creates a link table in the database).

 * DB-CLASS slots have an additional attribute TRANSIENT. If you set
it to a non-NIL value, it will behave just as a
STANDARD-SLOT-DEFINITION and will be ignored in database related
operations.

 * Submarine uses MOP rather than macros to achieve its purposes. This
makes it easier to maintain and to extend.

ryszard.szopa's avatar
README    
ryszard.szopa committed
100
At the moment there's no real documentation apart from docstrings, but
101
102
103
there's a poor man's tutorial in the file
http://bender.streamtech.nl/darcs/submarine/doc/example.lisp (this
should give you a fairly good overview of the possibilities of
ryszard.szopa's avatar
README    
ryszard.szopa committed
104
Submarine.
ryszard.szopa's avatar
README  
ryszard.szopa committed
105