refactor test-connect and test-setup-database to be these two separate things (from...

[clsql.git] / doc / ref-syntax.xml

diff --git a/doc/ref-syntax.xml b/doc/ref-syntax.xml
index c83cab344d41ad08852dfb922f4db23adba092a7..e0364fabd825483540f4d323de1c210d69a019dc 100644 (file)
--- a/doc/ref-syntax.xml
+++ b/doc/ref-syntax.xml
@@ -16,6 +16,12 @@
       utilities for enabling and disabling the square bracket reader
       syntax and for constructing symbolic SQL expressions.
     </para>
+    <tip>
+      <title>Tip: just want it on</title>
+      <simpara>
+       <link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link> at the top of each file is easiest.
+      </simpara>
+    </tip>
   </partintro>  
 
   <refentry id="enable-sql-reader-syntax">
@@ -23,7 +29,7 @@
       <refentrytitle>ENABLE-SQL-READER-SYNTAX</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Macro</emphasis> <emphasis role="bold">ENABLE-SQL-READER-SYNTAX</emphasis></refname>
+      <refname>ENABLE-SQL-READER-SYNTAX</refname>
       <refpurpose>Globally enable square bracket reader syntax.</refpurpose>
       <refclass>Macro</refclass>
     </refnamediv>
@@ -57,6 +63,12 @@
       <para> 
         Modifies the default readtable.
       </para>
+      <warning>
+       <para>
+       &clsql; tries to keep track of whether the syntax has already been enabled. This can be problematic if the syntax is somehow disabled externally to &clsql; as future attempts to enable the syntax will do nothing--the system thinks it is already enabled. This may happen if there is an enable, but no disable, in a file that is processed with load or compile-file as the lisp implementation will restore the readtable on completion. Or, even if there is a disable but a compiler-error is encountered before running the disable. If you encounter this try running <link linkend="disable-sql-reader-syntax"><function>disable-sql-reader-syntax</function></link> a couple times in the REPL.
+       </para>
+       <para>See <link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link> for an alternative.</para>
+      </warning>
     </refsect1>
     <refsect1>
       <title>Affected by</title>
@@ -77,6 +89,7 @@
         <member><link linkend="locally-enable-sql-reader-syntax"><function>locally-enable-sql-reader-syntax</function></link></member>
         <member><link linkend="locally-disable-sql-reader-syntax"><function>locally-disable-sql-reader-syntax</function></link></member>
         <member><link linkend="restore-sql-reader-syntax-state"><function>restore-sql-reader-syntax-state</function></link></member>
+       <member><link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link></member>
       </simplelist>
     </refsect1>
     <refsect1>
@@ -97,7 +110,7 @@
       <refentrytitle>DISABLE-SQL-READER-SYNTAX</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Macro</emphasis> <emphasis role="bold">DISABLE-SQL-READER-SYNTAX</emphasis></refname>
+      <refname>DISABLE-SQL-READER-SYNTAX</refname>
       <refpurpose>Globally disable square bracket reader syntax.</refpurpose>
       <refclass>Macro</refclass>
     </refnamediv>
@@ -151,6 +164,7 @@
         <member><link linkend="locally-enable-sql-reader-syntax"><function>locally-enable-sql-reader-syntax</function></link></member>
         <member><link linkend="locally-disable-sql-reader-syntax"><function>locally-disable-sql-reader-syntax</function></link></member>
         <member><link linkend="restore-sql-reader-syntax-state"><function>restore-sql-reader-syntax-state</function></link></member>
+       <member><link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link></member>
       </simplelist>
     </refsect1>
     <refsect1>
@@ -171,8 +185,8 @@
       <refentrytitle>LOCALLY-ENABLE-SQL-READER-SYNTAX</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Macro</emphasis> <emphasis role="bold">LOCALLY-ENABLE-SQL-READER-SYNTAX</emphasis></refname>
-      <refpurpose>Globally enable square bracket reader syntax.</refpurpose>
+      <refname>LOCALLY-ENABLE-SQL-READER-SYNTAX</refname>
+      <refpurpose>Locally enable square bracket reader syntax.</refpurpose>
       <refclass>Macro</refclass>
     </refnamediv>
     <refsect1>
@@ -210,6 +224,12 @@
       <para>
         Modifies the default readtable.
       </para>
+      <warning>
+       <para>
+       &clsql; tries to keep track of whether the syntax has already been enabled. This can be problematic if the syntax is somehow disabled externally to &clsql; as future attempts to enable the syntax will do nothing--the system thinks it is already enabled. This may happen if there is an enable, but no disable, in a file that is processed with load or compile-file as the lisp implementation will restore the readtable on completion. Or, even if there is a disable but a compiler-error is encountered before running the disable. If you encounter this try running <link linkend="disable-sql-reader-syntax"><function>disable-sql-reader-syntax</function></link> a couple times in the REPL.
+       </para>
+       <para>See <link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link> for an alternative.</para>
+      </warning>
     </refsect1>
     <refsect1>
       <title>Affected by</title>
@@ -228,6 +248,7 @@
         <member><link linkend="disable-sql-reader-syntax"><function>disable-sql-reader-syntax</function></link></member>
         <member><link linkend="locally-disable-sql-reader-syntax"><function>locally-disable-sql-reader-syntax</function></link></member>
         <member><link linkend="restore-sql-reader-syntax-state"><function>restore-sql-reader-syntax-state</function></link></member>
+       <member><link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link></member>
       </simplelist>
     </refsect1>
     <refsect1>
@@ -249,7 +270,7 @@
       <refentrytitle>LOCALLY-DISABLE-SQL-READER-SYNTAX</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Macro</emphasis> <emphasis role="bold">LOCALLY-DISABLE-SQL-READER-SYNTAX</emphasis></refname>
+      <refname>LOCALLY-DISABLE-SQL-READER-SYNTAX</refname>
       <refpurpose>Locally disable square bracket reader syntax.</refpurpose>
       <refclass>Macro</refclass>
     </refnamediv>
@@ -310,6 +331,7 @@
         <member><link linkend="disable-sql-reader-syntax"><function>disable-sql-reader-syntax</function></link></member>
         <member><link linkend="locally-enable-sql-reader-syntax"><function>locally-enable-sql-reader-syntax</function></link></member>
         <member><link linkend="restore-sql-reader-syntax-state"><function>restore-sql-reader-syntax-state</function></link></member>
+       <member><link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link></member>
       </simplelist>
     </refsect1>
     <refsect1>
@@ -330,7 +352,7 @@
       <refentrytitle>RESTORE-SQL-READER-SYNTAX-STATE</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Macro</emphasis> <emphasis role="bold">RESTORE-SQL-READER-SYNTAX-STATE</emphasis></refname>
+      <refname>RESTORE-SQL-READER-SYNTAX-STATE</refname>
       <refpurpose>
         Restore square bracket reader syntax to its previous state.
       </refpurpose>
@@ -394,6 +416,7 @@
         <member><link linkend="disable-sql-reader-syntax"><function>disable-sql-reader-syntax</function></link></member>
         <member><link linkend="locally-enable-sql-reader-syntax"><function>locally-enable-sql-reader-syntax</function></link></member>
         <member><link linkend="locally-disable-sql-reader-syntax"><function>locally-disable-sql-reader-syntax</function></link></member>
+       <member><link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link></member>
       </simplelist>
     </refsect1>
     <refsect1>
@@ -409,12 +432,86 @@
     </refsect1>
   </refentry>
 
+  <refentry id="file-enable-sql-reader-syntax">
+    <refmeta>
+      <refentrytitle>FILE-ENABLE-SQL-READER-SYNTAX</refentrytitle>
+    </refmeta>
+    <refnamediv>
+      <refname>FILE-ENABLE-SQL-READER-SYNTAX</refname>
+      <refpurpose>
+       Enable the square bracket reader syntax for the duration of the file.
+      </refpurpose>
+      <refclass>Macro</refclass>
+    </refnamediv>
+    <refsect1>
+      <title>Syntax</title>
+      <synopsis>
+      <function>file-enable-sql-reader-syntax</function> => <returnvalue></returnvalue></synopsis>
+    </refsect1>
+    <refsect1>
+      <title>Arguments and Values</title>
+      <para>None.</para> 
+    </refsect1>
+    <refsect1>
+      <title>Description</title>
+      <para>Uncoditionally enables the SQL reader syntax. Unlike <link
+      linkend="enable-sql-reader-syntax">
+      <function>enable-sql-reader-syntax</function></link> and <link
+      linkend="disable-sql-reader-syntax">
+      <function>disable-sql-reader-syntax</function></link> which try to keep track of whether
+       the syntax has been enabled or disabled and keep track of the old read-table for restoration this function just enables it unconditionally.
+      </para>
+      <para>Once enabled this way there is no corresponding disable function but instead relies on being used in a file context. The spec for <ulink url="http://www.lispworks.com/documentation/lw51/CLHS/Body/f_load.htm">load</ulink> and <ulink url="http://www.lispworks.com/documentation/lw51/CLHS/Body/f_cmp_fi.htm">compile-file</ulink> states that the *readtable* will be restored after processing the file.</para>
+    </refsect1>
+    <refsect1>
+      <title>Examples</title>
+      <para>Intended to be used at the top of a file that contains sql reader syntax.</para>
+      <screen>
+       (in-package :my-package)
+       (clsql:file-enable-sql-reader-syntax)
+       ...
+       ;;functions that use the square bracket syntax.
+      </screen> 
+    </refsect1>
+    <refsect1>
+      <title>Side Effects</title>
+      <para>
+        Modifies the readtable for #\[ and #\]
+      </para> 
+    </refsect1>
+    <refsect1>
+      <title>Affected by</title>
+      <para>None.</para> 
+    </refsect1>
+    <refsect1>
+      <title>Exceptional Situations</title>
+      <para>
+        None. 
+      </para>
+    </refsect1>
+    <refsect1>
+      <title>See Also</title>
+      <simplelist>
+        <member><link linkend="enable-sql-reader-syntax"><function>enable-sql-reader-syntax</function></link></member>
+        <member><link linkend="disable-sql-reader-syntax"><function>disable-sql-reader-syntax</function></link></member>
+        <member><link linkend="locally-enable-sql-reader-syntax"><function>locally-enable-sql-reader-syntax</function></link></member>
+        <member><link linkend="locally-disable-sql-reader-syntax"><function>locally-disable-sql-reader-syntax</function></link></member>
+      </simplelist>
+    </refsect1>
+    <refsect1>
+      <title>Notes</title>
+      <para> 
+        Unique to &clsql;, not present in &commonsql;.
+      </para>
+    </refsect1>
+  </refentry>
+
   <refentry id="sql">
     <refmeta>
       <refentrytitle>SQL</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">SQL</emphasis></refname>
+      <refname>SQL</refname>
       <refpurpose>Construct an SQL string from supplied expressions.</refpurpose>
       <refclass>Function</refclass>
     </refnamediv>
@@ -513,7 +610,7 @@
       <refentrytitle>SQL-EXPRESSION</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">SQL-EXPRESSION</emphasis></refname>
+      <refname>SQL-EXPRESSION</refname>
       <refpurpose>Constructs an SQL expression from supplied keyword arguments.</refpurpose>
       <refclass>Function</refclass>
     </refnamediv>
@@ -671,7 +768,7 @@
       <refentrytitle>SQL-OPERATION</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">SQL-OPERATION</emphasis></refname>
+      <refname>SQL-OPERATION</refname>
       <refpurpose>Constructs an SQL expression from a supplied operator and arguments.</refpurpose>
       <refclass>Function</refclass>
     </refnamediv>
@@ -775,7 +872,7 @@
       <refentrytitle>SQL-OPERATOR</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">SQL-OPERATOR</emphasis></refname>
+      <refname>SQL-OPERATOR</refname>
       <refpurpose>Returns the symbol for the supplied SQL operator.</refpurpose>
       <refclass>Function</refclass>
     </refnamediv>
@@ -847,80 +944,73 @@
       </para> 
       <simplelist> 
         <!-- CommonSQL Compatible --> 
-        <member><function>any
-        </function></member>, 
-        <member><function>some 
-        </function></member>, 
-        <member><function>all
-        </function></member>, 
-        <member><function>not
-        </function></member>, 
-        <member><function>union
-        </function></member>, 
-        <member><function>intersect
-        </function></member>, 
-        <member><function>minus
-        </function></member>, 
+        <member><function>any</function></member> 
+        <member><function>some</function></member> 
+        <member><function>all</function></member> 
+        <member><function>not</function></member> 
+        <member><function>union</function></member> 
+        <member><function>intersect</function></member> 
+        <member><function>minus</function></member>
         <member><function>except 
-        </function></member>, 
+        </function></member> 
         <member><function>order-by 
-        </function></member>, 
+        </function></member> 
         <member><function>null
-        </function></member>, 
+        </function></member> 
         <member><function>*
-        </function></member>, 
+        </function></member> 
         <member><function>+
-        </function></member>, 
+        </function></member> 
         <member><function>/
-        </function></member>, 
+        </function></member> 
         <member><function>-
-        </function></member>, 
+        </function></member> 
         <member><function>like
-        </function></member>, 
+        </function></member> 
         <member><function>and
-        </function></member>, 
+        </function></member> 
         <member><function>or
-        </function></member>, 
+        </function></member> 
         <member><function>in
-        </function></member>, 
+        </function></member> 
         <member><function>substr 
-        </function></member>, 
+        </function></member> 
         <member><function>|| 
-        </function></member>, 
+        </function></member> 
         <member><function>=
-        </function></member>, 
+        </function></member> 
         <member><function>&lt;
-        </function></member>, 
+        </function></member> 
         <member><function>>
-        </function></member>, 
+        </function></member> 
         <member><function>>=
-        </function></member>, 
+        </function></member> 
         <member><function>&lt;=
-        </function></member>, 
+        </function></member> 
         <member><function>&lt;>
-        </function></member>, 
+        </function></member> 
         <member><function>count
-        </function></member>, 
+        </function></member> 
         <member><function>max
-        </function></member>, 
+        </function></member> 
         <member><function>min
-        </function></member>, 
+        </function></member> 
         <member><function>avg
-        </function></member>, 
+        </function></member> 
         <member><function>sum
-        </function></member>, 
+        </function></member> 
         <member><function>function 
-        </function></member>, 
+        </function></member> 
         <member><function>between 
-        </function></member>, 
+        </function></member> 
         <member><function>distinct 
-        </function></member>, 
+        </function></member> 
         <member><function>nvl 
-        </function></member>, 
+        </function></member> 
         <member><function>slot-value
-        </function></member>, 
+        </function></member> 
         <member><function>userenv 
-        </function></member>, 
+        </function></member> 
       </simplelist> 
       <para>
         as well as the pseudo-operator <function>function</function>. 
@@ -930,30 +1020,30 @@
       <simplelist> 
         <!-- CLSQL Extensions --> 
         <member><function>concat
-        </function></member>, 
+        </function></member> 
         <member><function>substring 
-        </function></member>, 
+        </function></member> 
         <member><function>limit 
-        </function></member>, 
+        </function></member> 
         <member><function>group-by
-        </function></member>, 
+        </function></member> 
         <member><function>having
-        </function></member>, 
+        </function></member> 
         <member><function>not-null
-        </function></member>, 
+        </function></member> 
         <member><function>exists
-        </function></member>, 
+        </function></member> 
         <member><function>uplike
-        </function></member>, 
+        </function></member> 
         <member><function>is
-        </function></member>, 
+        </function></member> 
         <member><function>==
-        </function></member>, 
+        </function></member> 
         <member><function>the 
-        </function></member>, 
+        </function></member> 
         <member><function>coalesce 
-        </function></member>, 
-        <member><function>view-class.
+        </function></member> 
+        <member><function>view-class
         </function></member> 
       </simplelist>
       </para>