r1683: *** empty log message ***

[clsql.git] / doc / ref.sgml

diff --git a/doc/ref.sgml b/doc/ref.sgml
index 71d6da3a3afb6af0053ac3b702df619b4c6e4226..a24ae22b0d337952b4fba2c2af9f476c0c715c1d 100644 (file)
--- a/doc/ref.sgml
+++ b/doc/ref.sgml
@@ -1780,7 +1780,7 @@
       </refnamediv>
       <refsect1>
        <title>Syntax</title>
-       <synopsis><function>query</function> <replaceable>query-expression</replaceable> &amp;key <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
+       <synopsis><function>query</function> <replaceable>query-expression</replaceable> &amp;key <replaceable>database</replaceable> <replaceable>types</replaceable> => <returnvalue>result</returnvalue></synopsis>
       </refsect1>
       <refsect1>
        <title>Arguments and Values</title>
@@ -1803,6 +1803,48 @@
                of <symbol>*default-database*</symbol>.</para>
            </listitem>
          </varlistentry>
+         <varlistentry>
+           <term><parameter>types</parameter></term>
+           <listitem>
+             <para>A 
+               <glossterm linkend="gloss-field-types">field type
+                 specififier</glossterm>. The default is &nil;.
+               </para>
+               <para>
+                 The purpose of this argument is cause &clsql; to
+                 import SQL numeric fields into numeric Lisp objects
+                 rather than strings. This reduces the cost of
+                 allocating a temporary string and the &clsql; users'
+                 inconvenience of converting number strings into number
+                 objects.
+               </para>
+               <para>
+                 A value of <symbol>:auto</symbol> causes &clsql;
+                 to automatically convert SQL fields into a
+                 numeric format where applicable. The default value of
+                 &nil; causes all fields to be returned as strings
+                 regardless of the SQL type. Otherwise a list is expected
+                 which has a element for each field that specifies the
+                 conversion. If the list is shorter than the number
+                 of fields, the a value of <symbol>t</symbol> is
+                 assumed for the field.  If the list is longer than
+                 the number of fields, the extra elements are
+                 ignored.
+                 <simplelist type="vert">
+                   <member><symbol>:int</symbol> Field is imported as a
+                     signed integer, from 8-bits to 64-bits depending
+                      upon the field type.
+                   </member>
+                   <member><symbol>:double</symbol> Field is imported as a
+                     double-float number.
+                   </member>
+                   <member><symbol>t</symbol> Field is imported as a
+                     string.
+                   </member>
+                 </simplelist>
+               </para>
+           </listitem>
+         </varlistentry>
          <varlistentry>
            <term><returnvalue>result</returnvalue></term>
            <listitem>
@@ -1889,7 +1931,7 @@
       </refnamediv>
       <refsect1>
        <title>Syntax</title>
-       <synopsis><function>map-query</function> <replaceable>output-type-spec</replaceable> <replaceable>function</replaceable> <replaceable>query-expression</replaceable> &amp;key <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
+       <synopsis><function>map-query</function> <replaceable>output-type-spec</replaceable> <replaceable>function</replaceable> <replaceable>query-expression</replaceable> &amp;key <replaceable>database</replaceable> <replaceable>types</replaceable> => <returnvalue>result</returnvalue></synopsis>
       </refsect1>
       <refsect1>
        <title>Arguments and Values</title>
@@ -1929,6 +1971,17 @@
                of <symbol>*default-database*</symbol>.</para>
            </listitem>
          </varlistentry>
+         <varlistentry>
+           <term><parameter>types</parameter></term>
+           <listitem>
+             <para>
+               A <glossterm linkend="gloss-field-types">field type specififier</glossterm>. 
+               The default is &nil;. See <link
+               linkend="query"><function>query</function></link>
+               for the semantics of this argument.  
+             </para>
+           </listitem>
+         </varlistentry>
          <varlistentry>
            <term><returnvalue>result</returnvalue></term>
            <listitem>
@@ -1985,8 +2038,9 @@
 (map-query '(vector double-float)
           #'(lambda (salary name)
               (declare (ignorable name))
-              (coerce (read-from-string salary) 'double-float))
-          "select salary,name from simple where salary > 8000")
+               (let ((*read-default-float-format* 'double-float))
+                (coerce (read-from-string salary) 'double-float))
+                 "select salary,name from simple where salary > 8000"))
 => #(10000.0d0 8000.5d0)
 (type-of *)
 => (SIMPLE-ARRAY DOUBLE-FLOAT (2))
@@ -2048,7 +2102,7 @@
       </refnamediv>
       <refsect1>
        <title>Syntax</title>
-       <synopsis><function>do-query</function> ((&amp;rest <replaceable>args</replaceable>) <replaceable>query-expression</replaceable> &amp;key <replaceable>database</replaceable>) &amp;body <replaceable>body</replaceable> => <returnvalue>nil</returnvalue></synopsis>
+       <synopsis><function>do-query</function> ((&amp;rest <replaceable>args</replaceable>) <replaceable>query-expression</replaceable> &amp;key <replaceable>database</replaceable> <replaceable>types</replaceable>) &amp;body <replaceable>body</replaceable> => <returnvalue>nil</returnvalue></synopsis>
       </refsect1>
       <refsect1>
        <title>Arguments and Values</title>
@@ -2078,6 +2132,17 @@
                <symbol>*default-database*</symbol>.</para>
            </listitem>
          </varlistentry>
+         <varlistentry>
+           <term><parameter>types</parameter></term>
+           <listitem>
+             <para>
+               A <glossterm linkend="gloss-field-types">field type specififier</glossterm>. 
+               The default is &nil;. See <link
+               linkend="query"><function>query</function></link>
+               for the semantics of this argument.  
+             </para>
+           </listitem>
+         </varlistentry>
          <varlistentry>
            <term><parameter>body</parameter></term>
            <listitem>
@@ -2163,6 +2228,10 @@
        query via a loop clause</refpurpose>
        <refclass>Loop Clause</refclass>
       </refnamediv>
+      <refsect1>
+        <title>Compatibility</title>
+        <caution><para><function>loop-for-as-tuples</function> only works with &cmucl;.</para></caution>
+      </refsect1>
       <refsect1>
        <title>Syntax</title>
        <synopsis><replaceable>var</replaceable> [<replaceable>type-spec</replaceable>] being {each | the} {record | records | tuple | tuples} {in | of} <replaceable>query</replaceable> [from <replaceable>database</replaceable>]</synopsis>
@@ -2289,6 +2358,7 @@
       </refsect1>
     </refentry>
   </reference>
+
   <reference>
     <title><symbol>CLSQL-SYS</symbol></title>
     <partintro>
@@ -2297,11 +2367,6 @@
        exported from <symbol>CLSQL</symbol>.  These symbols are part of
        the interface for database back-ends, but not part of the normal
        user-interface of &clsql;.</para>
-      <note>
-       <para>This part has only one demonstration entry, since the
-         rest still has to be written.  In the meantime, use the
-         source to understand the database back-end interface.</para>
-      </note>
     </partintro>
     <refentry id="database-initialize-database-type">
       <refnamediv>