r9749: more documentation

diff --git a/doc/ref-ooddl.xml b/doc/ref-ooddl.xml
index 54a7d8c3646701d64a88eacf192e760f7f145767..6ea4d9cdccba6290377c343842c48c5660099217 100644 (file)
--- a/doc/ref-ooddl.xml
+++ b/doc/ref-ooddl.xml
@@ -8,25 +8,25 @@
 <!-- Object Oriented Data Definition Language --> 
 <reference id="ref-ooddl"> 
   <title>Object Oriented Data Definition Language (OODDL)</title> 
 <!-- Object Oriented Data Definition Language --> 
 <reference id="ref-ooddl"> 
   <title>Object Oriented Data Definition Language (OODDL)</title> 

-    <partintro>
-      <para>
-       The Object Oriented Data Definition Language (OODDL) provides
-       access to relational SQL tables using Common Lisp Object System
-       (CLOS) objects.  SQL tables are mapped to CLOS objects with the
-       SQL columns being mapped to slots of the CLOS object.
-      </para>
-      <para> 
-       The mapping between SQL tables and CLOS objects is defined
-       with the macro <link
-       linkend="def-view-class"><function>def-view-class</function></link>. SQL
-       tables are created with <link
-       linkend="create-view-from-class"><function>create-view-from-class</function></link>
-       and SQL tables can be deleted with <link
-       linkend="drop-view-from-class"><function>drop-view-from-class</function></link>.
-      </para>
-      <note>The above functions refer to the Lisp <emphasis>view</emphasis> of the SQL
-      table. This Lisp view should not be confused with SQL <function>VIEW</function> statement.
-      </note>
+  <partintro>
+    <para>
+      The Object Oriented Data Definition Language (OODDL) provides
+      access to relational SQL tables using Common Lisp Object System
+      (CLOS) objects.  SQL tables are mapped to CLOS objects with the
+      SQL columns being mapped to slots of the CLOS object.
+    </para>
+    <para> 
+      The mapping between SQL tables and CLOS objects is defined
+      with the macro <link
+      linkend="def-view-class"><function>def-view-class</function></link>. SQL
+      tables are created with <link
+      linkend="create-view-from-class"><function>create-view-from-class</function></link>
+      and SQL tables can be deleted with <link
+      linkend="drop-view-from-class"><function>drop-view-from-class</function></link>.
+    </para>
+    <note>The above functions refer to the Lisp <emphasis>view</emphasis> of the SQL
+    table. This Lisp view should not be confused with SQL <function>VIEW</function> statement.
+    </note>

   </partintro>
 
   <refentry id="standard-db-object">
   </partintro>
 
   <refentry id="standard-db-object">


@@ -38,11 +38,11 @@
     <refsect1>
       <title>Class Precedence List</title>
       <para>
     <refsect1>
       <title>Class Precedence List</title>
       <para>

-        <simplelist type="inline">
-          <member><type>standard-db-object</type></member>
-          <member><type>standard-object</type></member>
-          <member><type>t</type></member>
-        </simplelist>
+       <simplelist type="inline">
+         <member><type>standard-db-object</type></member>
+         <member><type>standard-object</type></member>
+         <member><type>t</type></member>
+       </simplelist>

       </para>
     </refsect1>
     <refsect1>
       </para>
     </refsect1>
     <refsect1>


@@ -56,11 +56,11 @@
     <refsect1>
       <title class="contenttitle">Slots</title>
       <para>
     <refsect1>
       <title class="contenttitle">Slots</title>
       <para>

-        <simplelist> 
-          <property>slot VIEW-DATABASE is of type (OR NULL DATABASE)
+       <simplelist> 
+         <property>slot VIEW-DATABASE is of type (OR NULL DATABASE)

          which stores the associated database for the
          instance.</property>
          which stores the associated database for the
          instance.</property>

-        </simplelist> 
+       </simplelist> 

       </para>
     </refsect1>
   </refentry>
       </para>
     </refsect1>
   </refentry>


@@ -74,7 +74,7 @@
     <refsect1>
       <title>Value Type</title>
       <para>
     <refsect1>
       <title>Value Type</title>
       <para>

-        Fixnum
+       Fixnum

       </para> 
     </refsect1>
     <refsect1>
       </para> 
     </refsect1>
     <refsect1>


@@ -95,11 +95,11 @@
       <title>Examples</title>
       <screen>
        (let ((*default-string-length* 80))
       <title>Examples</title>
       <screen>
        (let ((*default-string-length* 80))

-         (def-view-class s80 ()
-            ((a :type string)
-            (b :type (string 80))
-            (c :type varchar))))
-         (create-view-from-class 's80)   
+       (def-view-class s80 ()
+       ((a :type string)
+       (b :type (string 80))
+       (c :type varchar))))
+       (create-view-from-class 's80)   

       </screen>
       <para>
        The above code causes a SQL table to be created with the SQL command
       </screen>
       <para>
        The above code causes a SQL table to be created with the SQL command


@@ -137,36 +137,36 @@
       <variablelist>
        <varlistentry>
          <term><parameter>view-class-name</parameter></term>
       <variablelist>
        <varlistentry>
          <term><parameter>view-class-name</parameter></term>

-          <listitem>
-            <para>
-              The name of a view class that has been defined with
+         <listitem>
+           <para>
+             The name of a view class that has been defined with

              <link linkend="def-view-class"><function>def-view-class</function></link>.
              <link linkend="def-view-class"><function>def-view-class</function></link>.

-            </para>
-          </listitem>
-        </varlistentry>
+           </para>
+         </listitem>
+       </varlistentry>

        <varlistentry>
          <term><parameter>database</parameter></term>
        <varlistentry>
          <term><parameter>database</parameter></term>

-          <listitem>
-            <para>
-              The database in which to create the SQL table.
+         <listitem>
+           <para>
+             The database in which to create the SQL table.

            </para>
            </para>

-          </listitem>
-        </varlistentry>
+         </listitem>
+       </varlistentry>

        <varlistentry>
          <term><parameter>transactions</parameter></term>
        <varlistentry>
          <term><parameter>transactions</parameter></term>

-          <listitem>
-            <para>
-              When &nil; specifies that a table type which does not support transactions should be used.
-            </para>
-          </listitem>
-        </varlistentry>
+         <listitem>
+           <para>
+             When &nil; specifies that a table type which does not support transactions should be used.
+           </para>
+         </listitem>
+       </varlistentry>

       </variablelist>
     </refsect1>
     <refsect1>
       <title>Description</title>
       </variablelist>
     </refsect1>
     <refsect1>
       <title>Description</title>

-      <para>Creates a table as defined by the View Class
-      VIEW-CLASS-NAME in DATABASE which defaults to
-      *DEFAULT-DATABASE*.
+      <para>
+       Creates a table as defined by the View Class
+       <parameter>view-class-name</parameter> in <parameter>database</parameter>.

       </para>
     </refsect1>
     <refsect1>
       </para>
     </refsect1>
     <refsect1>


@@ -197,14 +197,14 @@
     <refsect1>
       <title>Exceptional Situations</title>
       <para>
     <refsect1>
       <title>Exceptional Situations</title>
       <para>

-        A condition will be signaled if the table can not be created
-        in the SQL database.
+       A condition will be signaled if the table can not be created
+       in the SQL database.

       </para>
     </refsect1>
     <refsect1>
       <title>See Also</title>
       <para>
       </para>
     </refsect1>
     <refsect1>
       <title>See Also</title>
       <para>

-        <simplelist>
+       <simplelist>

          <member><link linkend="def-view-class"><function>def-view-class</function></link></member>
          <member><link linkend="drop-view-from-class"><function>drop-view-from-class</function></link></member>
        </simplelist>
          <member><link linkend="def-view-class"><function>def-view-class</function></link></member>
          <member><link linkend="drop-view-from-class"><function>drop-view-from-class</function></link></member>
        </simplelist>


@@ -218,6 +218,11 @@
        applications which would benefit from faster table access and
        do not require transaction support.
       </para>
        applications which would benefit from faster table access and
        do not require transaction support.
       </para>

+      <para>
+       The case of the table name is determined by the type of the
+       database. &mysql;, for example, creates databases in upper-case
+       while &postgresql; uses lowercase.
+      </para>

     </refsect1>
   </refentry>
 
     </refsect1>
   </refentry>
 


@@ -230,197 +235,261 @@
     <refsect1>
       <title>Syntax</title>
       <synopsis>
     <refsect1>
       <title>Syntax</title>
       <synopsis>

-      <function>(def-view-class name superclasses slots &amp;rest class-options) [macro]</function> => <returnvalue>class</returnvalue></synopsis>
+      <function>(def-view-class name superclasses slots &amp;rest class-options)</function> => <returnvalue>class</returnvalue></synopsis>

     </refsect1>
     <refsect1>
       <title>Arguments and Values</title>
       <variablelist>
     </refsect1>
     <refsect1>
       <title>Arguments and Values</title>
       <variablelist>

-        <varlistentry>
-          <term><parameter>name</parameter></term>
-          <listitem>
-            <para>
-             The class name.
-            </para>
-          </listitem>
-        </varlistentry>
-        <varlistentry>
-          <term><parameter>name</parameter></term>
-          <listitem>
-            <para>
-             The superclasses for the defined class.
-            </para>
-          </listitem>
-        </varlistentry>
-        <varlistentry>
-          <term><parameter>slots</parameter></term>
-          <listitem>
-            <para>
-             The class slot definitions.
-            </para>
-          </listitem>
-        </varlistentry>
-        <varlistentry>
-          <term><parameter>class</parameter></term>
-          <listitem>
-            <para>
-             The defined class.
-            </para>
-          </listitem>
-        </varlistentry>
-      </variablelist>
-    </refsect1>
-    <refsect1>
-      <title>Slot Options</title>
-       <itemizedlist>
+       <varlistentry>
+         <term><parameter>name</parameter></term>

          <listitem>
            <para>
          <listitem>
            <para>

-             <parameter>:db-kind</parameter> - specifies the kind of
-             DB mapping which is performed for this slot and defaults
-             to <parameter>:base</parameter> which indicates that the
-             slot maps to an ordinary column of the database table. A
-             <parameter>:db-kind</parameter> value of
-             <parameter>:key</parameter> indicates that this slot is
-             a special kind of <parameter>:base</parameter> slot
-             which maps onto a column which is one of the unique keys
-             for the database table, the value
-             <parameter>:join</parameter> indicates this slot
-             represents a join onto another View Class which contains
-             View Class objects, and the value
-             <parameter>:virtual</parameter> indicates a standard
-             CLOS slot which does not map onto columns of the
-             database table.
+             The class name.

            </para>
          </listitem>
            </para>
          </listitem>

+       </varlistentry>
+       <varlistentry>
+         <term><parameter>name</parameter></term>

          <listitem>
            <para>
          <listitem>
            <para>

-             <parameter>:db-info</parameter> - if a slot is specified with
-             <parameter>:db-kind</parameter> <parameter>:join</parameter>, the
-             slot option <parameter>:db-info</parameter> contains a list
-             which specifies the nature of the join.
+             The superclasses for the defined class.

            </para>
          </listitem>
            </para>
          </listitem>

+       </varlistentry>
+       <varlistentry>
+         <term><parameter>slots</parameter></term>

          <listitem>
            <para>
          <listitem>
            <para>

-             <parameter>:type</parameter> - for slots of
-             <parameter>:db-kind</parameter> <parameter>:base</parameter> or
-             <parameter>:key</parameter>, the <parameter>:type</parameter> slot
-             option has a special interpretation such that Lisp
-             types, such as string, integer and float are
-             automatically converted into appropriate SQL types for
-             the column onto which the slot maps. This behaviour may
-             be overridden using the <parameter>:db-type</parameter> slot
-             option. The valid values are:
-             <simplelist>
-               <member>
-                 <parameter>string</parameter> - a variable length character field up to
-                 <link linkend="default-string-length">*default-string-length*</link> characters.
-               </member>
-               <member>
-                 <parameter>(string n)</parameter> - a fixed length character field 
-                 <parameter>n</parameter> characters long.
-               </member>
-               <member>
-                 <parameter>varchar</parameter> - a variable length character field up to
-                 <link linkend="default-string-length">*default-string-length*</link> characters.
-               </member>
-               <member>
-                 <parameter>(varchar n)</parameter> - a variable length character field up to
-                 <parameter>n</parameter> characters in length.
-               </member>
-               <member>
-                 <parameter>char</parameter> - a single character field 
-               </member>
-               <member><parameter>integer</parameter> - signed integer at least 32-bits wide</member>
-               <member><parameter>(integer n)</parameter></member>
-               <member><parameter>float</parameter></member>
-               <member><parameter>(float n)</parameter></member>
-               <member><parameter>long-float</parameter></member>
-               <member><parameter>number</parameter></member>
-               <member><parameter>(number n)</parameter></member>
-               <member><parameter>(number n p)</parameter></member>
-               <member>
-                 <parameter>smallint</parameter> - An integer column 16-bits
-                 wide. [not supported by all database backends]
-               </member>
-               <member>
-                 <parameter>bigint</parameter> - An integer column 
-                 64-bits wide. [not supported by all database backends]
-               </member>
-               <member>
-                 <parameter>universal-time</parameter> - an integer
-                 field sufficiently wide to store a
-                 universal-time. On most databases, a slot of this
-                 type assigned a SQL type of
-                 <parameter>BIGINT</parameter>
-               </member>
-               <member>
-                 <parameter>wall-time</parameter> - a slot which
-                 stores a date and time in a SQL timestamp
-                 column. &clsql; provides a number of time
-                 manipulation functions to support objects of type
-                 <type>wall-time</type>.
-               </member>
-               <member>
-                 <parameter>duration</parameter> - stores a <type>duration</type> structure.
-                 &clsql; provides routines for <type>wall-time</type> and <type>duration</type>
-                 processing.
-               </member>
-               <member><parameter>boolean</parameter> - stores a &t; or &nil; value.</member>
-               <member>
-                 <parameter>generalized-boolean</parameter> - similar
-                 to a <parameter>boolean</parameter> in that either a
-                 &t; or &nil; value is stored in the SQL
-                 database. However, any Lisp object can be stored in
-                 the Lisp object. A Lisp value of &nil; is stored as
-                 <constant>FALSE</constant> in the database, any
-                 other Lisp value is stored as
-                 <constant>TRUE</constant>.
-               </member>
-               <member>
-                 <parameter>keyword</parameter> - stores a keyword
-               </member>       
-               <member><parameter>symbol</parameter> - stores a symbol</member>
-               <member>
-                 <parameter>list</parameter> - stores a list by writing it to a string. The items
-                 in the list must be able to be readable written.
-               </member>
-               <member><parameter>vector</parameter> - stores a vector similarly to <parameter>list</parameter></member>
-               <member><parameter>array</parameter> - stores a array similarly to <parameter>list</parameter></member>
-             </simplelist>
+             The class slot definitions.

            </para>
            </para>

-           

          </listitem>
          </listitem>

+       </varlistentry>
+       <varlistentry>
+         <term><parameter>class</parameter></term>

          <listitem>
            <para>
          <listitem>
            <para>

-             <parameter>:column</parameter> - specifies the name of
-             the SQL column which the slot maps onto, if
-             <parameter>:db-kind</parameter> is not
-             <parameter>:virtual</parameter>, and defaults to the
-             slot name.
+             The defined class.

            </para>
          </listitem>
            </para>
          </listitem>

-         <listitem>
+       </varlistentry>
+      </variablelist>
+    </refsect1>
+    <refsect1>
+      <title>Slot Options</title>
+      <itemizedlist>
+       <listitem>
+         <para>
+           <parameter>:db-kind</parameter> - specifies the kind of
+           database mapping which is performed for this slot and defaults
+           to <parameter>:base</parameter> which indicates that the
+           slot maps to an ordinary column of the database table. A
+           <parameter>:db-kind</parameter> value of
+           <parameter>:key</parameter> indicates that this slot is
+           a special kind of <parameter>:base</parameter> slot
+           which maps onto a column which is one of the unique keys
+           for the database table, the value
+           <parameter>:join</parameter> indicates this slot
+           represents a join onto another View Class which contains
+           View Class objects, and the value
+           <parameter>:virtual</parameter> indicates a standard
+           CLOS slot which does not map onto columns of the
+           database table.
+         </para>
+       </listitem>
+       <listitem>
+         <para>
+           <parameter>:db-info</parameter> - if a slot is specified with
+           <parameter>:db-kind</parameter> <parameter>:join</parameter>, the
+           slot option <parameter>:db-info</parameter> contains a property list
+           which specifies the nature of the join. The valid members of the list
+           are:
+         </para>
+         <itemizedlist>
+           <listitem>
+             <para>
+               <parameter>:join-class</parameter>
+               <emphasis>class-name</emphasis> - the name of the
+               class to join on.
+             </para>
+           </listitem>
+           <listitem>
+             <para>
+               <parameter>:home-key</parameter>
+               <emphasis>slot-name</emphasis> - the name of the slot
+               of this class for joining
+             </para>
+           </listitem>
+           <listitem>
+             <para>
+               <parameter>:foreign-key</parameter>
+               <emphasis>slot-name</emphasis> - the name of the slot
+               of the <parameter>:join-class</parameter> for joining
+             </para>
+           </listitem>
+           <listitem>
+             <para>
+               <parameter>:target-slot</parameter>
+               <emphasis>target-slot</emphasis> - this is an optional
+               parameter. If specified, then the join slot of the
+               defining class will contain instances of this target
+               slot rather than of the join class. This can be useful
+               when the <parameter>:join-class</parameter> is an
+               intermediate class in a
+               <emphasis>many-to-many</emphasis> relationship and the
+               application is actually interested in the
+               <parameter>:target-slot</parameter>.
+             </para>
+           </listitem>
+           <listitem>
+             <para>
+               <parameter>:retrieval</parameter>
+               <emphasis>time</emphasis> - The default value is
+               <parameter>:deferred</parameter>, which defers filling
+               this slot until the value is accessed. The other valid
+               value is <parameter>:immediate</parameter> which
+               performs the SQL query when the instance of the class
+               is created. In this case, the
+               <parameter>:set</parameter> is automatically set to
+               &nil;
+             </para>
+           </listitem>
+           <listitem>
+             <para>
+               <parameter>:set</parameter>
+               <emphasis>set</emphasis> - This controls what is stored in the join slot.
+               The default value is &t;. When <emphasis>set</emphasis> is &t; and 
+               <emphasis>target-slot</emphasis> is undefined, the join slot will contain
+               a list of instances of the join class. Whereas, if <emphasis>target-slot</emphasis> is defined, 
+               then the join slot will contain a list of pairs of <emphasis>(target-value join-instance)</emphasis>.
+               When <emphasis>set</emphasis> is &nil;, the join slot will contain a single instances.
+             </para>
+           </listitem>
+         </itemizedlist>
+       </listitem>
+       <listitem>
+         <para>
+           <parameter>:type</parameter> - for slots of
+           <parameter>:db-kind</parameter> <parameter>:base</parameter> or
+           <parameter>:key</parameter>, the <parameter>:type</parameter> slot
+           option has a special interpretation such that Lisp
+           types, such as string, integer and float are
+           automatically converted into appropriate SQL types for
+           the column onto which the slot maps. This behaviour may
+           be overridden using the <parameter>:db-type</parameter> slot
+           option. The valid values are:
+           <simplelist>
+             <member>
+               <parameter>string</parameter> - a variable length character field up to
+               <link linkend="default-string-length">*default-string-length*</link> characters.
+             </member>
+             <member>
+               <parameter>(string n)</parameter> - a fixed length character field  
+               <parameter>n</parameter> characters long.
+             </member>
+             <member>
+               <parameter>varchar</parameter> - a variable length character field up to
+               <link linkend="default-string-length">*default-string-length*</link> characters.
+             </member>
+             <member>
+               <parameter>(varchar n)</parameter> - a variable length character field up to
+               <parameter>n</parameter> characters in length.
+             </member>
+             <member>
+               <parameter>char</parameter> - a single character field 
+             </member>
+             <member><parameter>integer</parameter> - signed integer at least 32-bits wide</member>
+             <member><parameter>(integer n)</parameter></member>
+             <member><parameter>float</parameter></member>
+             <member><parameter>(float n)</parameter></member>
+             <member><parameter>long-float</parameter></member>
+             <member><parameter>number</parameter></member>
+             <member><parameter>(number n)</parameter></member>
+             <member><parameter>(number n p)</parameter></member>
+             <member>
+               <parameter>smallint</parameter> - An integer column 16-bits
+               wide. [not supported by all database backends]
+             </member>
+             <member>
+               <parameter>bigint</parameter> - An integer column 
+               64-bits wide. [not supported by all database backends]
+             </member>
+             <member>
+               <parameter>universal-time</parameter> - an integer
+               field sufficiently wide to store a
+               universal-time. On most databases, a slot of this
+               type assigned a SQL type of
+               <parameter>BIGINT</parameter>
+             </member>
+             <member>
+               <parameter>wall-time</parameter> - a slot which
+               stores a date and time in a SQL timestamp
+               column. &clsql; provides a number of time
+               manipulation functions to support objects of type
+               <type>wall-time</type>.
+             </member>
+             <member>
+               <parameter>duration</parameter> - stores a <type>duration</type> structure.
+               &clsql; provides routines for <type>wall-time</type> and <type>duration</type>
+               processing.
+             </member>
+             <member><parameter>boolean</parameter> - stores a &t; or &nil; value.</member>
+             <member>
+               <parameter>generalized-boolean</parameter> - similar
+               to a <parameter>boolean</parameter> in that either a
+               &t; or &nil; value is stored in the SQL
+               database. However, any Lisp object can be stored in
+               the Lisp object. A Lisp value of &nil; is stored as
+               <constant>FALSE</constant> in the database, any
+               other Lisp value is stored as
+               <constant>TRUE</constant>.
+             </member>
+             <member>
+               <parameter>keyword</parameter> - stores a keyword
+             </member> 
+             <member><parameter>symbol</parameter> - stores a symbol</member>
+             <member>
+               <parameter>list</parameter> - stores a list by writing it to a string. The items
+               in the list must be able to be readable written.
+             </member>
+             <member><parameter>vector</parameter> - stores a vector similarly to <parameter>list</parameter></member>
+             <member><parameter>array</parameter> - stores a array similarly to <parameter>list</parameter></member>
+           </simplelist>
+         </para>
+         
+       </listitem>
+       <listitem>
+         <para>
+           <parameter>:column</parameter> - specifies the name of
+           the SQL column which the slot maps onto, if
+           <parameter>:db-kind</parameter> is not
+           <parameter>:virtual</parameter>, and defaults to the
+           slot name. If the slot name is used for the SQL column
+           name, any hypens in the slot name are converted
+           to underscore characters.
+         </para>
+       </listitem>
+       <listitem>

          <para>
            <parameter>:void-value</parameter> - specifies
          <para>
            <parameter>:void-value</parameter> - specifies

-             the value to store in the Lisp instance if the SQL value is NULL and defaults
-             to NIL.
+           the value to store in the Lisp instance if the SQL value is NULL and defaults
+           to NIL.

          </para>
          </para>

-         </listitem>
-         <listitem>
-           <para>
-             <parameter>:db-constraints</parameter> - is a string
-             representing an SQL table constraint expression or a
-             list of such strings.
-           </para>
-         </listitem>
-         <listitem>
-           <para>
-             <parameter>:db-type</parameter> - a string to specify the SQL
-             column type. If specified, this string overrides the SQL
-             column type as computed from the <parameter>:type</parameter>
-             slot value.
-           </para>
-         </listitem>
+       </listitem>
+       <listitem>
+         <para>
+           <parameter>:db-constraints</parameter> - is a string
+           representing an SQL table constraint expression or a
+           list of such strings.
+         </para>
+       </listitem>
+       <listitem>
+         <para>
+           <parameter>:db-type</parameter> - a string to specify the SQL
+           column type. If specified, this string overrides the SQL
+           column type as computed from the <parameter>:type</parameter>
+           slot value.
+         </para>
+       </listitem>

       </itemizedlist>
     </refsect1>
     <refsect1>
       </itemizedlist>
     </refsect1>
     <refsect1>


@@ -430,7 +499,8 @@
          <listitem>
            <para>
              <parameter>:base-table</parameter> - specifies the name of the
          <listitem>
            <para>
              <parameter>:base-table</parameter> - specifies the name of the

-             SQL database table. The default value is the class name.
+             SQL database table. The default value is the class name. Like slot names,
+             hypens in the class name are converted to underscore characters.

            </para>
          </listitem>
        </itemizedlist>
            </para>
          </listitem>
        </itemizedlist>


@@ -439,23 +509,167 @@
     <refsect1>
       <title>Description</title>
       <para>
     <refsect1>
       <title>Description</title>
       <para>

-       Creates a View Class called <parameter>NAME</parameter> whose
-       slots <parameter>SLOTS</parameter> can map onto the attributes
+       Creates a View Class called <parameter>name</parameter> whose
+       slots <parameter>slots</parameter> can map onto the attributes

        of a table in a database. If
        of a table in a database. If

-       <parameter>SUPERCLASSES</parameter> is &nil; then the
-       superclass of <parameter>CLASS</parameter> will be
-       <parameter>STANDARD-DB-OBJECT</parameter>, otherwise
-       <parameter>SUPERCLASSES</parameter> is a list of superclasses
-       for <parameter>CLASS</parameter> which must include
-       <parameter>STANDARD-DB-OBJECT</parameter> or a descendent of this
+       <parameter>superclasses</parameter> is &nil; then the
+       superclass of <parameter>class</parameter> will be
+       <parameter>standard-db-object</parameter>, otherwise
+       <parameter>superclasses</parameter> is a list of superclasses
+       for <parameter>class</parameter> which must include
+       <parameter>standard-db-object</parameter> or a descendent of this

        class.
       </para>
 
     </refsect1>
     <refsect1>
       <title>Examples</title>
        class.
       </para>
 
     </refsect1>
     <refsect1>
       <title>Examples</title>

+      <para>
+       The following examples are from the &clsql; test suite.
+      </para>

       <screen>
       <screen>

-        <!-- examples -->
+(def-view-class person (thing)
+  ((height :db-kind :base :accessor height :type float
+           :initarg :height)
+   (married :db-kind :base :accessor married :type boolean
+            :initarg :married)
+   (birthday :type clsql:wall-time :initarg :birthday)
+   (bd-utime :type clsql:universal-time :initarg :bd-utime)
+   (hobby :db-kind :virtual :initarg :hobby :initform nil)))
+  
+(def-view-class employee (person)
+  ((emplid
+    :db-kind :key
+    :db-constraints :not-null
+    :type integer
+    :initarg :emplid)
+   (groupid
+    :db-kind :key
+    :db-constraints :not-null
+    :type integer
+    :initarg :groupid)
+   (first-name
+    :accessor first-name
+    :type (varchar 30)
+    :initarg :first-name)
+   (last-name
+    :accessor last-name
+    :type (varchar 30)
+    :initarg :last-name)
+   (email
+    :accessor employee-email
+    :type (varchar 100)
+    :initarg :email)
+   (ecompanyid
+    :type integer
+    :initarg :companyid)
+   (company
+    :accessor employee-company
+    :db-kind :join
+    :db-info (:join-class company
+                         :home-key ecompanyid
+                         :foreign-key companyid
+                         :set nil))
+   (managerid
+    :type integer
+    :initarg :managerid)
+   (manager
+    :accessor employee-manager
+    :db-kind :join
+    :db-info (:join-class employee
+                         :home-key managerid
+                         :foreign-key emplid
+                         :set nil))
+   (addresses
+    :accessor employee-addresses
+    :db-kind :join
+    :db-info (:join-class employee-address
+                         :home-key emplid
+                         :foreign-key aemplid
+                         :target-slot address
+                         :set t)))
+  (:base-table employee))
+
+(def-view-class company ()
+  ((companyid
+    :db-kind :key
+    :db-constraints :not-null
+    :type integer
+    :initarg :companyid)
+   (groupid
+    :db-kind :key
+    :db-constraints :not-null
+    :type integer
+    :initarg :groupid)
+   (name
+    :type (varchar 100)
+    :initarg :name)
+   (presidentid
+    :type integer
+    :initarg :presidentid)
+   (president
+    :reader president
+    :db-kind :join
+    :db-info (:join-class employee
+                         :home-key presidentid
+                         :foreign-key emplid
+                         :set nil))
+   (employees
+    :reader company-employees
+    :db-kind :join
+    :db-info (:join-class employee
+                         :home-key (companyid groupid)
+                         :foreign-key (ecompanyid groupid)
+                         :set t))))
+
+(def-view-class address ()
+  ((addressid
+    :db-kind :key
+    :db-constraints :not-null
+    :type integer
+    :initarg :addressid)
+   (street-number
+    :type integer
+    :initarg :street-number)
+   (street-name
+    :type (varchar 30)
+    :void-value ""
+    :initarg :street-name)
+   (city
+    :column "city_field"
+    :void-value "no city"
+    :type (varchar 30)
+    :initarg :city)
+   (postal-code
+    :column zip
+    :type integer
+    :void-value 0
+    :initarg :postal-code))
+  (:base-table addr))
+
+;; many employees can reside at many addressess
+(def-view-class employee-address ()
+  ((aemplid :type integer :initarg :emplid)
+   (aaddressid :type integer :initarg :addressid)
+   (verified :type boolean :initarg :verified)
+   (address :db-kind :join
+           :db-info (:join-class address
+                                 :home-key aaddressid
+                                 :foreign-key addressid
+                                 :retrieval :immediate)))
+  (:base-table "ea_join"))
+
+(def-view-class deferred-employee-address ()
+  ((aemplid :type integer :initarg :emplid)
+   (aaddressid :type integer :initarg :addressid)
+   (verified :type boolean :initarg :verified)
+   (address :db-kind :join
+           :db-info (:join-class address
+                                 :home-key aaddressid
+                                 :foreign-key addressid
+                                 :retrieval :deferred
+                                 :set nil)))
+  (:base-table "ea_join"))

       </screen>
     </refsect1>
     <refsect1>
       </screen>
     </refsect1>
     <refsect1>


@@ -471,17 +685,17 @@
     <refsect1>
       <title>Exceptional Situations</title>
       <para>
     <refsect1>
       <title>Exceptional Situations</title>
       <para>

-        None.
+       None.

       </para>
     </refsect1>
     <refsect1>
       <title>See Also</title>
       <para>
       </para>
     </refsect1>
     <refsect1>
       <title>See Also</title>
       <para>

-        <simplelist>
+       <simplelist>

          <member><link linkend="create-view-from-class"><function>create-view-from-class</function></link></member>
          <member><link linkend="standard-db-object"><parameter>standard-db-object</parameter></link></member>
          <member><link linkend="drop-view-from-class"><function>drop-view-from-class</function></link></member>
          <member><link linkend="create-view-from-class"><function>create-view-from-class</function></link></member>
          <member><link linkend="standard-db-object"><parameter>standard-db-object</parameter></link></member>
          <member><link linkend="drop-view-from-class"><function>drop-view-from-class</function></link></member>

-        </simplelist>
+       </simplelist>

       </para>
     </refsect1>
     <refsect1>
       </para>
     </refsect1>
     <refsect1>


@@ -520,14 +734,14 @@
     <refsect1>
       <title>Arguments and Values</title>
       <variablelist>
     <refsect1>
       <title>Arguments and Values</title>
       <variablelist>

-        <varlistentry>
-          <term><parameter>view-class-name</parameter></term>
-          <listitem>
-            <para>
+       <varlistentry>
+         <term><parameter>view-class-name</parameter></term>
+         <listitem>
+           <para>

              The name of the view class.
              The name of the view class.

-            </para>
-          </listitem>
-        </varlistentry>
+           </para>
+         </listitem>
+       </varlistentry>

       </variablelist>
     </refsect1>
     <refsect1>
       </variablelist>
     </refsect1>
     <refsect1>


@@ -571,16 +785,16 @@
     <refsect1>
       <title>See Also</title>
       <para>
     <refsect1>
       <title>See Also</title>
       <para>

-        <simplelist>
+       <simplelist>

          <member><link linkend="create-view-from-class"><function>create-view-from-class</function></link></member>
          <member><link linkend="def-view-class"><function>def-view-class</function></link></member>
          <member><link linkend="create-view-from-class"><function>create-view-from-class</function></link></member>
          <member><link linkend="def-view-class"><function>def-view-class</function></link></member>

-        </simplelist>
+       </simplelist>

       </para>
     </refsect1>
     <refsect1>
       <title>Notes</title>
       <para>
       </para>
     </refsect1>
     <refsect1>
       <title>Notes</title>
       <para>

-        <!-- notes --> 
+       <!-- notes --> 

       </para>
     </refsect1>
   </refentry>
       </para>
     </refsect1>
   </refentry>


@@ -599,63 +813,61 @@
     <refsect1>
       <title>Arguments and Values</title>
       <variablelist>
     <refsect1>
       <title>Arguments and Values</title>
       <variablelist>

-        <varlistentry>
-          <term><parameter>test</parameter></term>
-          <listitem>
-            <para>
+       <varlistentry>
+         <term><parameter>test</parameter></term>
+         <listitem>
+           <para>

              a function used to filter the search. By default, <parameter>identity</parameter> is used which
              will return all classes.
              a function used to filter the search. By default, <parameter>identity</parameter> is used which
              will return all classes.

-            </para>
-          </listitem>
-        </varlistentry>
-        <varlistentry>
-          <term><parameter>root-class</parameter></term>
-          <listitem>
-            <para>
+           </para>
+         </listitem>
+       </varlistentry>
+       <varlistentry>
+         <term><parameter>root-class</parameter></term>
+         <listitem>
+           <para>

              specifies the root class to the search. By default, <parameter>standard-db-object</parameter> is used
              which is the root for all view classes.
              specifies the root class to the search. By default, <parameter>standard-db-object</parameter> is used
              which is the root for all view classes.

-            </para>
-          </listitem>
-        </varlistentry>
-        <varlistentry>
-          <term><parameter>database</parameter></term>
-          <listitem>
-            <para>
+           </para>
+         </listitem>
+       </varlistentry>
+       <varlistentry>
+         <term><parameter>database</parameter></term>
+         <listitem>
+           <para>

              The database to search for view classes.
              The database to search for view classes.

-            </para>
-          </listitem>
-        </varlistentry>
-        <varlistentry>
-          <term><parameter>classes</parameter></term>
-          <listitem>
-            <para>
+           </para>
+         </listitem>
+       </varlistentry>
+       <varlistentry>
+         <term><parameter>classes</parameter></term>
+         <listitem>
+           <para>

              List of view classes.
              List of view classes.

-            </para>
-          </listitem>
-        </varlistentry>
+           </para>
+         </listitem>
+       </varlistentry>

       </variablelist>
     </refsect1>
     <refsect1>
       <title>Description</title>
       <para>Returns a list of all the View Classes which have been
       defined in the Lisp session and are connected to
       </variablelist>
     </refsect1>
     <refsect1>
       <title>Description</title>
       <para>Returns a list of all the View Classes which have been
       defined in the Lisp session and are connected to

-      <parameter>DATABASE</parameter>, which defaults to
-      <parameter>*DEFAULT-DATABASE*</parameter>, and which descended
-      from the class ROOT-CLASS and which satisfy the function
-      TEST. By default ROOT-CLASS is STANDARD-DB-OBJECT and
-      <parameter>TEST</parameter> is IDENTITY.
+      <parameter>database</parameter> and which descended from the
+      class <parameter>root-class</parameter> and which satisfy the
+      function <parameter>test</parameter>.

       </para>
     </refsect1>
     <refsect1>
       <title>Examples</title>
       <screen>
       </para>
     </refsect1>
     <refsect1>
       <title>Examples</title>
       <screen>

-        * (list-classes)
-        (#&lt;clsql-sys::standard-db-class big> #&lt;clsql-sys::standard-db-class employee-address>
-        #&lt;clsql-sys::standard-db-class address> #&lt;clsql-sys::standard-db-class company> 
+       * (list-classes)
+       (#&lt;clsql-sys::standard-db-class big> #&lt;clsql-sys::standard-db-class employee-address>
+       #&lt;clsql-sys::standard-db-class address> #&lt;clsql-sys::standard-db-class company> 

        #&lt;clsql-sys::standard-db-class employee>)
 
        #&lt;clsql-sys::standard-db-class employee>)
 

-        * (list-classes :test #'(lambda (c) (> (length (symbol-name (class-name c))) 3)))
-        (#&lt;clsql-sys::standard-db-class employee-address> #&lt;clsql-sys::standard-db-class address>
+       * (list-classes :test #'(lambda (c) (> (length (symbol-name (class-name c))) 3)))
+       (#&lt;clsql-sys::standard-db-class employee-address> #&lt;clsql-sys::standard-db-class address>

        #&lt;clsql-sys::standard-db-class company> #&lt;clsql-sys::standard-db-class employee>)
       </screen>
     </refsect1>
        #&lt;clsql-sys::standard-db-class company> #&lt;clsql-sys::standard-db-class employee>)
       </screen>
     </refsect1>


@@ -668,9 +880,9 @@
     <refsect1>
       <title>Affected by</title>
       <para>
     <refsect1>
       <title>Affected by</title>
       <para>

-        <simplelist>
+       <simplelist>

          Which view classes have been defined in the Lisp session.
          Which view classes have been defined in the Lisp session.

-        </simplelist>
+       </simplelist>

       </para>
     </refsect1>
     <refsect1>
       </para>
     </refsect1>
     <refsect1>


@@ -682,17 +894,11 @@
     <refsect1>
       <title>See Also</title>
       <para>
     <refsect1>
       <title>See Also</title>
       <para>

-        <simplelist>
+       <simplelist>

          <member><link linkend="def-view-class"><function>def-view-class</function></link></member>
        </simplelist>
       </para>
     </refsect1>
          <member><link linkend="def-view-class"><function>def-view-class</function></link></member>
        </simplelist>
       </para>
     </refsect1>

-    <refsect1>
-      <title>Notes</title>
-      <para>
-        <!-- notes --> 
-      </para>
-    </refsect1>

   </refentry>
 
 
   </refentry>