doc/ref-syntax.xml

   1 <?xml version='1.0' ?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % myents SYSTEM "entities.inc">
   5 %myents;
   6 ]>
   7
   8 <!-- Symbolic SQL Syntax -->
   9 <reference id="ref-syntax">
  10   <title>The Symbolic SQL Syntax</title>
  11   <partintro>
  12     <para>
  13       &clsql; provides a symbolic syntax allowing the construction of
  14       SQL expressions as lists delimited by square brackets. The
  15       syntax is turned off by default. This section describes
  16       utilities for enabling and disabling the square bracket reader
  17       syntax and for constructing symbolic SQL expressions.
  18     </para>
  19     <tip>
  20       <title>Tip: just want it on</title>
  21       <simpara>
  22         <link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link> at the top of each file is easiest.
  23       </simpara>
  24     </tip>
  25   </partintro>
  26
  27   <refentry id="enable-sql-reader-syntax">
  28     <refmeta>
  29       <refentrytitle>ENABLE-SQL-READER-SYNTAX</refentrytitle>
  30     </refmeta>
  31     <refnamediv>
  32       <refname>ENABLE-SQL-READER-SYNTAX</refname>
  33       <refpurpose>Globally enable square bracket reader syntax.</refpurpose>
  34       <refclass>Macro</refclass>
  35     </refnamediv>
  36     <refsect1>
  37       <title>Syntax</title>
  38       <synopsis>
  39       <function>enable-sql-reader-syntax</function> => <returnvalue></returnvalue></synopsis>
  40     </refsect1>
  41     <refsect1>
  42       <title>Arguments and Values</title>
  43       <para>None.</para>
  44     </refsect1>
  45     <refsect1>
  46       <title>Description</title>
  47       <para>Turns on the SQL reader syntax setting the syntax state
  48       such that if the syntax is subsequently disabled, <link
  49       linkend="restore-sql-reader-syntax-state">
  50       <function>restore-sql-reader-syntax-state</function></link> will
  51       enable it again.
  52       </para>
  53     </refsect1>
  54     <refsect1>
  55       <title>Examples</title>
  56       <para>None.</para>
  57     </refsect1>
  58     <refsect1>
  59       <title>Side Effects</title>
  60       <para>
  61         Sets the internal syntax state to enabled.
  62       </para>
  63       <para>
  64         Modifies the default readtable.
  65       </para>
  66       <warning>
  67         <para>
  68         &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.
  69         </para>
  70         <para>See <link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link> for an alternative.</para>
  71       </warning>
  72     </refsect1>
  73     <refsect1>
  74       <title>Affected by</title>
  75       <para>
  76         None.
  77       </para>
  78     </refsect1>
  79     <refsect1>
  80       <title>Exceptional Situations</title>
  81       <para>
  82         None.
  83       </para>
  84     </refsect1>
  85     <refsect1>
  86       <title>See Also</title>
  87       <simplelist>
  88         <member><link linkend="disable-sql-reader-syntax"><function>disable-sql-reader-syntax</function></link></member>
  89         <member><link linkend="locally-enable-sql-reader-syntax"><function>locally-enable-sql-reader-syntax</function></link></member>
  90         <member><link linkend="locally-disable-sql-reader-syntax"><function>locally-disable-sql-reader-syntax</function></link></member>
  91         <member><link linkend="restore-sql-reader-syntax-state"><function>restore-sql-reader-syntax-state</function></link></member>
  92         <member><link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link></member>
  93       </simplelist>
  94     </refsect1>
  95     <refsect1>
  96       <title>Notes</title>
  97       <para>
  98         The symbolic SQL syntax is disabled by default.
  99       </para>
 100       <para>
 101         &clsql; differs from &commonsql; in that
 102         <function>enable-sql-reader-syntax</function> is defined as a
 103         macro rather than a function.
 104       </para>
 105     </refsect1>
 106   </refentry>
 107
 108   <refentry id="disable-sql-reader-syntax">
 109     <refmeta>
 110       <refentrytitle>DISABLE-SQL-READER-SYNTAX</refentrytitle>
 111     </refmeta>
 112     <refnamediv>
 113       <refname>DISABLE-SQL-READER-SYNTAX</refname>
 114       <refpurpose>Globally disable square bracket reader syntax.</refpurpose>
 115       <refclass>Macro</refclass>
 116     </refnamediv>
 117     <refsect1>
 118       <title>Syntax</title>
 119       <synopsis>
 120       <function>disable-sql-reader-syntax</function> => <returnvalue></returnvalue></synopsis>
 121     </refsect1>
 122     <refsect1>
 123       <title>Arguments and Values</title>
 124       <para>None.</para>
 125     </refsect1>
 126     <refsect1>
 127       <title>Description</title>
 128       <para>Turns off the SQL reader syntax setting the syntax state
 129       such that if the syntax is subsequently enabled,
 130       <link linkend="restore-sql-reader-syntax-state">
 131         <function>restore-sql-reader-syntax-state</function></link> will
 132         disable it again.
 133       </para>
 134     </refsect1>
 135     <refsect1>
 136       <title>Examples</title>
 137       <para>None.</para>
 138     </refsect1>
 139     <refsect1>
 140       <title>Side Effects</title>
 141       <para>
 142         Sets the internal syntax state to disabled.
 143       </para>
 144       <para>
 145         Modifies the default readtable.
 146       </para>
 147     </refsect1>
 148     <refsect1>
 149       <title>Affected by</title>
 150       <para>
 151         None.
 152       </para>
 153     </refsect1>
 154     <refsect1>
 155       <title>Exceptional Situations</title>
 156       <para>
 157         None.
 158       </para>
 159     </refsect1>
 160     <refsect1>
 161       <title>See Also</title>
 162       <simplelist>
 163         <member><link linkend="enable-sql-reader-syntax"><function>enable-sql-reader-syntax</function></link></member>
 164         <member><link linkend="locally-enable-sql-reader-syntax"><function>locally-enable-sql-reader-syntax</function></link></member>
 165         <member><link linkend="locally-disable-sql-reader-syntax"><function>locally-disable-sql-reader-syntax</function></link></member>
 166         <member><link linkend="restore-sql-reader-syntax-state"><function>restore-sql-reader-syntax-state</function></link></member>
 167         <member><link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link></member>
 168       </simplelist>
 169     </refsect1>
 170     <refsect1>
 171       <title>Notes</title>
 172       <para>
 173         The symbolic SQL syntax is disabled by default.
 174       </para>
 175       <para>
 176         &clsql; differs from &commonsql; in that
 177         <function>disable-sql-reader-syntax</function> is defined as a
 178         macro rather than a function.
 179       </para>
 180     </refsect1>
 181   </refentry>
 182
 183   <refentry id="locally-enable-sql-reader-syntax">
 184     <refmeta>
 185       <refentrytitle>LOCALLY-ENABLE-SQL-READER-SYNTAX</refentrytitle>
 186     </refmeta>
 187     <refnamediv>
 188       <refname>LOCALLY-ENABLE-SQL-READER-SYNTAX</refname>
 189       <refpurpose>Locally enable square bracket reader syntax.</refpurpose>
 190       <refclass>Macro</refclass>
 191     </refnamediv>
 192     <refsect1>
 193       <title>Syntax</title>
 194       <synopsis>
 195       <function>locally-enable-sql-reader-syntax</function> => <returnvalue></returnvalue></synopsis>
 196     </refsect1>
 197     <refsect1>
 198       <title>Arguments and Values</title>
 199       <para>None.</para>
 200     </refsect1>
 201     <refsect1>
 202       <title>Description</title>
 203       <para>Turns on the SQL reader syntax without changing the syntax
 204       state such that <link linkend="restore-sql-reader-syntax-state">
 205       <function>restore-sql-reader-syntax-state</function></link> will
 206       re-establish the current syntax state.
 207       </para>
 208     </refsect1>
 209     <refsect1>
 210       <title>Examples</title>
 211       <para>Intended to be used in a file for code which uses the
 212       square bracket syntax without changing the global state.
 213       </para>
 214       <screen>
 215         #.(locally-enable-sql-reader-syntax)
 216
 217         ... CODE USING SYMBOLIC SQL SYNTAX ...
 218
 219         #.(restore-sql-reader-syntax-state)
 220       </screen>
 221     </refsect1>
 222     <refsect1>
 223       <title>Side Effects</title>
 224       <para>
 225         Modifies the default readtable.
 226       </para>
 227       <warning>
 228         <para>
 229         &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.
 230         </para>
 231         <para>See <link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link> for an alternative.</para>
 232       </warning>
 233     </refsect1>
 234     <refsect1>
 235       <title>Affected by</title>
 236       <para>None.</para>
 237     </refsect1>
 238     <refsect1>
 239       <title>Exceptional Situations</title>
 240       <para>
 241         None.
 242       </para>
 243     </refsect1>
 244     <refsect1>
 245       <title>See Also</title>
 246       <simplelist>
 247         <member><link linkend="enable-sql-reader-syntax"><function>enable-sql-reader-syntax</function></link></member>
 248         <member><link linkend="disable-sql-reader-syntax"><function>disable-sql-reader-syntax</function></link></member>
 249         <member><link linkend="locally-disable-sql-reader-syntax"><function>locally-disable-sql-reader-syntax</function></link></member>
 250         <member><link linkend="restore-sql-reader-syntax-state"><function>restore-sql-reader-syntax-state</function></link></member>
 251         <member><link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link></member>
 252       </simplelist>
 253     </refsect1>
 254     <refsect1>
 255       <title>Notes</title>
 256       <para>
 257         The symbolic SQL syntax is disabled by default.
 258       </para>
 259       <para>
 260         &clsql; differs from &commonsql; in that
 261         <function>locally-enable-sql-reader-syntax</function> is
 262         defined as a macro rather than a function.
 263       </para>
 264     </refsect1>
 265   </refentry>
 266
 267
 268   <refentry id="locally-disable-sql-reader-syntax">
 269     <refmeta>
 270       <refentrytitle>LOCALLY-DISABLE-SQL-READER-SYNTAX</refentrytitle>
 271     </refmeta>
 272     <refnamediv>
 273       <refname>LOCALLY-DISABLE-SQL-READER-SYNTAX</refname>
 274       <refpurpose>Locally disable square bracket reader syntax.</refpurpose>
 275       <refclass>Macro</refclass>
 276     </refnamediv>
 277     <refsect1>
 278       <title>Syntax</title>
 279       <synopsis>
 280       <function>locally-disable-sql-reader-syntax</function> => <returnvalue></returnvalue></synopsis>
 281     </refsect1>
 282     <refsect1>
 283       <title>Arguments and Values</title>
 284       <para>None.</para>
 285     </refsect1>
 286     <refsect1>
 287       <title>Description</title>
 288       <para>Turns off the SQL reader syntax without changing the
 289       syntax state such that <link
 290       linkend="restore-sql-reader-syntax-state">
 291       <function>restore-sql-reader-syntax-state</function></link> will
 292       re-establish the current syntax state.
 293       </para>
 294     </refsect1>
 295     <refsect1>
 296       <title>Examples</title>
 297       <para>Intended to be used in a file for code in which the square
 298       bracket syntax should be disabled without changing the global
 299       state.
 300       </para>
 301       <screen>
 302         #.(locally-disable-sql-reader-syntax)
 303
 304         ... CODE NOT USING SYMBOLIC SQL SYNTAX ...
 305
 306         #.(restore-sql-reader-syntax-state)
 307       </screen>
 308     </refsect1>
 309     <refsect1>
 310       <title>Side Effects</title>
 311       <para>
 312         Modifies the default readtable.
 313       </para>
 314     </refsect1>
 315     <refsect1>
 316       <title>Affected by</title>
 317       <para>
 318         None.
 319       </para>
 320     </refsect1>
 321     <refsect1>
 322       <title>Exceptional Situations</title>
 323       <para>
 324         None.
 325       </para>
 326     </refsect1>
 327     <refsect1>
 328       <title>See Also</title>
 329       <simplelist>
 330         <member><link linkend="enable-sql-reader-syntax"><function>enable-sql-reader-syntax</function></link></member>
 331         <member><link linkend="disable-sql-reader-syntax"><function>disable-sql-reader-syntax</function></link></member>
 332         <member><link linkend="locally-enable-sql-reader-syntax"><function>locally-enable-sql-reader-syntax</function></link></member>
 333         <member><link linkend="restore-sql-reader-syntax-state"><function>restore-sql-reader-syntax-state</function></link></member>
 334         <member><link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link></member>
 335       </simplelist>
 336     </refsect1>
 337     <refsect1>
 338       <title>Notes</title>
 339       <para>
 340         The symbolic SQL syntax is disabled by default.
 341       </para>
 342       <para>
 343         &clsql; differs from &commonsql; in that
 344         <function>locally-disable-sql-reader-syntax</function> is
 345         defined as a macro rather than a function.
 346       </para>
 347     </refsect1>
 348   </refentry>
 349
 350   <refentry id="restore-sql-reader-syntax-state">
 351     <refmeta>
 352       <refentrytitle>RESTORE-SQL-READER-SYNTAX-STATE</refentrytitle>
 353     </refmeta>
 354     <refnamediv>
 355       <refname>RESTORE-SQL-READER-SYNTAX-STATE</refname>
 356       <refpurpose>
 357         Restore square bracket reader syntax to its previous state.
 358       </refpurpose>
 359       <refclass>Macro</refclass>
 360     </refnamediv>
 361     <refsect1>
 362       <title>Syntax</title>
 363       <synopsis>
 364       <function>restore-sql-reader-syntax-state</function> => <returnvalue></returnvalue></synopsis>
 365     </refsect1>
 366     <refsect1>
 367       <title>Arguments and Values</title>
 368       <para>None.</para>
 369     </refsect1>
 370     <refsect1>
 371       <title>Description</title>
 372       <para>Enables the SQL reader syntax if <link
 373       linkend="enable-sql-reader-syntax">
 374       <function>enable-sql-reader-syntax</function></link> has been
 375       called more recently than <link
 376       linkend="disable-sql-reader-syntax">
 377       <function>disable-sql-reader-syntax</function></link> and
 378       otherwise disables the SQL reader syntax. By default, the SQL
 379       reader syntax is disabled.
 380       </para>
 381     </refsect1>
 382     <refsect1>
 383       <title>Examples</title>
 384       <para>
 385         See <link
 386         linkend="locally-enable-sql-reader-syntax">
 387         <function>locally-enable-sql-reader-syntax</function></link> and
 388         <link
 389          linkend="locally-disable-sql-reader-syntax">
 390           <function>locally-disable-sql-reader-syntax</function></link>.
 391       </para>
 392     </refsect1>
 393     <refsect1>
 394       <title>Side Effects</title>
 395       <para>
 396         Reverts the internal syntax state.
 397       </para>
 398       <para>
 399         Modifies the default readtable.
 400       </para>
 401     </refsect1>
 402     <refsect1>
 403       <title>Affected by</title>
 404       <para>The current internal syntax state.</para>
 405     </refsect1>
 406     <refsect1>
 407       <title>Exceptional Situations</title>
 408       <para>
 409         None.
 410       </para>
 411     </refsect1>
 412     <refsect1>
 413       <title>See Also</title>
 414       <simplelist>
 415         <member><link linkend="enable-sql-reader-syntax"><function>enable-sql-reader-syntax</function></link></member>
 416         <member><link linkend="disable-sql-reader-syntax"><function>disable-sql-reader-syntax</function></link></member>
 417         <member><link linkend="locally-enable-sql-reader-syntax"><function>locally-enable-sql-reader-syntax</function></link></member>
 418         <member><link linkend="locally-disable-sql-reader-syntax"><function>locally-disable-sql-reader-syntax</function></link></member>
 419         <member><link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link></member>
 420       </simplelist>
 421     </refsect1>
 422     <refsect1>
 423       <title>Notes</title>
 424       <para>
 425         The symbolic SQL syntax is disabled by default.
 426       </para>
 427       <para>
 428         &clsql; differs from &commonsql; in that
 429         <function>restore-sql-reader-syntax-state</function> is
 430         defined as a macro rather than a function.
 431       </para>
 432     </refsect1>
 433   </refentry>
 434
 435   <refentry id="file-enable-sql-reader-syntax">
 436     <refmeta>
 437       <refentrytitle>FILE-ENABLE-SQL-READER-SYNTAX</refentrytitle>
 438     </refmeta>
 439     <refnamediv>
 440       <refname>FILE-ENABLE-SQL-READER-SYNTAX</refname>
 441       <refpurpose>
 442         Enable the square bracket reader syntax for the duration of the file.
 443       </refpurpose>
 444       <refclass>Macro</refclass>
 445     </refnamediv>
 446     <refsect1>
 447       <title>Syntax</title>
 448       <synopsis>
 449       <function>file-enable-sql-reader-syntax</function> => <returnvalue></returnvalue></synopsis>
 450     </refsect1>
 451     <refsect1>
 452       <title>Arguments and Values</title>
 453       <para>None.</para>
 454     </refsect1>
 455     <refsect1>
 456       <title>Description</title>
 457       <para>Uncoditionally enables the SQL reader syntax. Unlike <link
 458       linkend="enable-sql-reader-syntax">
 459       <function>enable-sql-reader-syntax</function></link> and <link
 460       linkend="disable-sql-reader-syntax">
 461       <function>disable-sql-reader-syntax</function></link> which try to keep track of whether
 462         the syntax has been enabled or disabled and keep track of the old read-table for restoration this function just enables it unconditionally.
 463       </para>
 464       <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>
 465     </refsect1>
 466     <refsect1>
 467       <title>Examples</title>
 468       <para>Intended to be used at the top of a file that contains sql reader syntax.</para>
 469       <screen>
 470         (in-package :my-package)
 471         (clsql:file-enable-sql-reader-syntax)
 472         ...
 473         ;;functions that use the square bracket syntax.
 474       </screen>
 475     </refsect1>
 476     <refsect1>
 477       <title>Side Effects</title>
 478       <para>
 479         Modifies the readtable for #\[ and #\]
 480       </para>
 481     </refsect1>
 482     <refsect1>
 483       <title>Affected by</title>
 484       <para>None.</para>
 485     </refsect1>
 486     <refsect1>
 487       <title>Exceptional Situations</title>
 488       <para>
 489         None.
 490       </para>
 491     </refsect1>
 492     <refsect1>
 493       <title>See Also</title>
 494       <simplelist>
 495         <member><link linkend="enable-sql-reader-syntax"><function>enable-sql-reader-syntax</function></link></member>
 496         <member><link linkend="disable-sql-reader-syntax"><function>disable-sql-reader-syntax</function></link></member>
 497         <member><link linkend="locally-enable-sql-reader-syntax"><function>locally-enable-sql-reader-syntax</function></link></member>
 498         <member><link linkend="locally-disable-sql-reader-syntax"><function>locally-disable-sql-reader-syntax</function></link></member>
 499       </simplelist>
 500     </refsect1>
 501     <refsect1>
 502       <title>Notes</title>
 503       <para>
 504         Unique to &clsql;, not present in &commonsql;.
 505       </para>
 506     </refsect1>
 507   </refentry>
 508
 509   <refentry id="sql">
 510     <refmeta>
 511       <refentrytitle>SQL</refentrytitle>
 512     </refmeta>
 513     <refnamediv>
 514       <refname>SQL</refname>
 515       <refpurpose>Construct an SQL string from supplied expressions.</refpurpose>
 516       <refclass>Function</refclass>
 517     </refnamediv>
 518     <refsect1>
 519       <title>Syntax</title>
 520       <synopsis>
 521       <function>sql &amp;rest</function> <replaceable>args</replaceable> => <returnvalue>sql-expression</returnvalue></synopsis>
 522     </refsect1>
 523     <refsect1>
 524       <title>Arguments and Values</title>
 525       <variablelist>
 526         <varlistentry>
 527           <term><parameter>args</parameter></term>
 528           <listitem>
 529             <para>A set of expressions.</para>
 530           </listitem>
 531         </varlistentry>
 532         <varlistentry>
 533           <term><returnvalue>sql-expression</returnvalue></term>
 534           <listitem>
 535             <para>A string representing an SQL expression.</para>
 536           </listitem>
 537         </varlistentry>
 538       </variablelist>
 539     </refsect1>
 540     <refsect1>
 541       <title>Description</title>
 542       <para>Returns an SQL string generated from the expressions
 543       <parameter>args</parameter>. The expressions are translated into
 544       SQL strings and then concatenated with a single space delimiting
 545       each expression.
 546       </para>
 547     </refsect1>
 548     <refsect1>
 549       <title>Examples</title>
 550       <screen>
 551 (sql nil)
 552 => "NULL"
 553
 554 (sql 'foo)
 555 => "FOO"
 556
 557 (sql "bar")
 558  => "'bar'"
 559
 560 (sql 10)
 561 => "10"
 562
 563 (sql '(nil foo "bar" 10))
 564 => "(NULL,FOO,'bar',10)"
 565
 566 (sql #(nil foo "bar" 10))
 567 => "NULL,FOO,'bar',10"
 568
 569 (sql [select [foo] [bar] :from [baz]] 'having [= [foo id] [bar id]]
 570      'and [foo val] '&lt; 5)
 571 => "SELECT FOO,BAR FROM BAZ HAVING (FOO.ID = BAR.ID) AND FOO.VAL &lt; 5"
 572       </screen>
 573     </refsect1>
 574     <refsect1>
 575       <title>Side Effects</title>
 576       <para>None.</para>
 577     </refsect1>
 578     <refsect1>
 579       <title>Affected by</title>
 580       <para>
 581         None.
 582       </para>
 583     </refsect1>
 584     <refsect1>
 585       <title>Exceptional Situations</title>
 586       <para>An error of type <link
 587       linkend="sql-user-error"><function>sql-user-error</function></link>
 588       is signalled if any element in <parameter>args</parameter> is
 589       not of the supported types (a symbol, string, number or symbolic
 590       SQL expression) or a list or vector containing only these
 591       supported types.
 592       </para>
 593     </refsect1>
 594     <refsect1>
 595       <title>See Also</title>
 596       <simplelist>
 597         <member><link linkend="sql-expression"><function>sql-expression</function></link></member>
 598         <member><link linkend="sql-operation"><function>sql-operation</function></link></member>
 599         <member><link linkend="sql-operator"><function>sql-operator</function></link></member>
 600       </simplelist>
 601     </refsect1>
 602     <refsect1>
 603       <title>Notes</title>
 604       <para>None.</para>
 605     </refsect1>
 606   </refentry>
 607
 608   <refentry id="sql-expression">
 609     <refmeta>
 610       <refentrytitle>SQL-EXPRESSION</refentrytitle>
 611     </refmeta>
 612     <refnamediv>
 613       <refname>SQL-EXPRESSION</refname>
 614       <refpurpose>Constructs an SQL expression from supplied keyword arguments.</refpurpose>
 615       <refclass>Function</refclass>
 616     </refnamediv>
 617     <refsect1>
 618       <title>Syntax</title>
 619       <synopsis>
 620       <function>sql-expression &amp;key</function> <parameter>string</parameter> <parameter>table</parameter> <parameter>alias</parameter> <parameter>attribute</parameter> <parameter>type</parameter> => <returnvalue>result</returnvalue></synopsis>
 621     </refsect1>
 622     <refsect1>
 623       <title>Arguments and Values</title>
 624       <variablelist>
 625         <varlistentry>
 626           <term><parameter>string</parameter></term>
 627           <listitem>
 628             <para>A string.</para>
 629           </listitem>
 630         </varlistentry>
 631         <varlistentry>
 632           <term><parameter>table</parameter></term>
 633           <listitem>
 634             <para>A symbol representing a database table identifier.</para>
 635           </listitem>
 636         </varlistentry>
 637         <varlistentry>
 638           <term><parameter>alias</parameter></term>
 639           <listitem>
 640             <para>A table alias.</para>
 641           </listitem>
 642         </varlistentry>
 643         <varlistentry>
 644           <term><parameter>attribute</parameter></term>
 645           <listitem>
 646             <para>A symbol representing an attribute identifier.</para>
 647           </listitem>
 648         </varlistentry>
 649         <varlistentry>
 650           <term><parameter>type</parameter></term>
 651           <listitem>
 652             <para>A type specifier.</para>
 653           </listitem>
 654         </varlistentry>
 655         <varlistentry>
 656           <term><returnvalue>result</returnvalue></term>
 657           <listitem>
 658             <para>A object of type <type>sql-expression</type>.</para>
 659           </listitem>
 660         </varlistentry>
 661       </variablelist>
 662     </refsect1>
 663     <refsect1>
 664       <title>Description</title>
 665       <para>Returns an SQL expression constructed from the supplied
 666       arguments which may be combined as follows:</para>
 667       <itemizedlist mark='opencircle'>
 668         <listitem>
 669           <para>
 670             <parameter>attribute</parameter> and
 671             <parameter>type</parameter>;
 672           </para>
 673         </listitem>
 674         <listitem>
 675           <para>
 676             <parameter>attribute</parameter>;
 677           </para>
 678         </listitem>
 679         <listitem>
 680           <para>
 681             <parameter>alias</parameter> or <parameter>table</parameter> and
 682             <parameter>attribute</parameter> and
 683             <parameter>type</parameter>;
 684           </para>
 685         </listitem>
 686         <listitem>
 687           <para>
 688             <parameter>alias</parameter> or
 689             <parameter>table</parameter> and
 690             <parameter>attribute</parameter>;
 691           </para>
 692         </listitem>
 693         <listitem>
 694           <para>
 695             <parameter>table</parameter>,
 696             <parameter>attribute</parameter> and
 697             <parameter>type</parameter>;
 698           </para>
 699         </listitem>
 700         <listitem>
 701           <para>
 702             <parameter>table</parameter> and
 703             <parameter>attribute</parameter>;
 704           </para>
 705         </listitem>
 706         <listitem>
 707           <para>
 708             <parameter>table</parameter>
 709             and <parameter>alias</parameter>;
 710           </para>
 711         </listitem>
 712         <listitem>
 713           <para>
 714             <parameter>table</parameter>;
 715           </para>
 716         </listitem>
 717         <listitem>
 718           <para>
 719             <parameter>string</parameter>.
 720           </para>
 721         </listitem>
 722       </itemizedlist>
 723     </refsect1>
 724     <refsect1>
 725       <title>Examples</title>
 726       <screen>
 727 (sql-expression :table 'foo :attribute 'bar)
 728 => #&lt;CLSQL-SYS:SQL-IDENT-ATTRIBUTE FOO.BAR>
 729
 730 (sql-expression :attribute 'baz)
 731 => #&lt;CLSQL-SYS:SQL-IDENT-ATTRIBUTE BAZ>
 732       </screen>
 733     </refsect1>
 734     <refsect1>
 735       <title>Side Effects</title>
 736       <para>None.</para>
 737     </refsect1>
 738     <refsect1>
 739       <title>Affected by</title>
 740       <para>
 741         None.
 742       </para>
 743     </refsect1>
 744     <refsect1>
 745       <title>Exceptional Situations</title>
 746       <para>An error of type <link
 747       linkend="sql-user-error"><function>sql-user-error</function></link>
 748       is signalled if an unsupported combination of keyword arguments is
 749       specified.
 750       </para>
 751     </refsect1>
 752     <refsect1>
 753       <title>See Also</title>
 754       <simplelist>
 755         <member><link linkend="sql"><function>sql</function></link></member>
 756         <member><link linkend="sql-operation"><function>sql-operation</function></link></member>
 757         <member><link linkend="sql-operator"><function>sql-operator</function></link></member>
 758         </simplelist>
 759     </refsect1>
 760     <refsect1>
 761       <title>Notes</title>
 762       <para>None.</para>
 763     </refsect1>
 764   </refentry>
 765
 766   <refentry id="sql-operation">
 767     <refmeta>
 768       <refentrytitle>SQL-OPERATION</refentrytitle>
 769     </refmeta>
 770     <refnamediv>
 771       <refname>SQL-OPERATION</refname>
 772       <refpurpose>Constructs an SQL expression from a supplied operator and arguments.</refpurpose>
 773       <refclass>Function</refclass>
 774     </refnamediv>
 775     <refsect1>
 776       <title>Syntax</title>
 777       <synopsis>
 778       <function>sql-operation</function> <parameter>operator</parameter> <function>&amp;rest</function> <parameter>args</parameter> => <returnvalue>result</returnvalue></synopsis>
 779       <synopsis>
 780       <function>sql-operation</function> 'function <parameter>func</parameter> <function>&amp;rest</function> <parameter>args</parameter> => <returnvalue>result</returnvalue></synopsis>
 781     </refsect1>
 782     <refsect1>
 783       <title>Arguments and Values</title>
 784       <variablelist>
 785         <varlistentry>
 786           <term><parameter>operator</parameter></term>
 787           <listitem>
 788             <para>A symbol denoting an SQL operator.</para>
 789           </listitem>
 790         </varlistentry>
 791         <varlistentry>
 792           <term><parameter>func</parameter></term>
 793           <listitem>
 794             <para>A string denoting an SQL function.</para>
 795           </listitem>
 796         </varlistentry>
 797         <varlistentry>
 798           <term><parameter>args</parameter></term>
 799           <listitem>
 800             <para>A set of arguments for the specified SQL operator or function.</para>
 801           </listitem>
 802         </varlistentry>
 803         <varlistentry>
 804           <term><returnvalue>result</returnvalue></term>
 805           <listitem>
 806             <para>A object of type <function>sql-expression</function>.</para>
 807           </listitem>
 808         </varlistentry>
 809       </variablelist>
 810     </refsect1>
 811     <refsect1>
 812       <title>Description</title>
 813       <para>Returns an SQL expression constructed from the supplied
 814       SQL operator or function <parameter>operator</parameter> and
 815       its arguments <parameter>args</parameter>. If
 816       <parameter>operator</parameter> is passed the symbol 'function
 817       then the first value in <parameter>args</parameter> is taken to
 818       be a valid SQL function and the remaining values in
 819       <parameter>args</parameter> its arguments.
 820       </para>
 821     </refsect1>
 822     <refsect1>
 823       <title>Examples</title>
 824       <screen>
 825 (sql-operation 'select
 826           (sql-expression :table 'foo :attribute 'bar)
 827           (sql-operation 'sum  (sql-expression :table 'foo :attribute 'baz))
 828           :from
 829           (sql-expression :table 'foo)
 830           :where
 831           (sql-operation '> (sql-expression :attribute 'bar) 12)
 832           :order-by (sql-operation 'sum (sql-expression :attribute 'baz)))
 833 => #&lt;SQL-QUERY SELECT FOO.BAR,SUM(FOO.BAZ) FROM FOO WHERE (BAR > 12) ORDER BY SUM(BAZ)>
 834
 835 (sql-operation 'function "strpos" "CLSQL" "SQL")
 836 => #&lt;CLSQL-SYS:SQL-FUNCTION-EXP STRPOS('CLSQL','SQL')>
 837       </screen>
 838     </refsect1>
 839     <refsect1>
 840       <title>Side Effects</title>
 841       <para>None.</para>
 842     </refsect1>
 843     <refsect1>
 844       <title>Affected by</title>
 845       <para>
 846         None.
 847       </para>
 848     </refsect1>
 849     <refsect1>
 850       <title>Exceptional Situations</title>
 851       <para>An error of type <link
 852       linkend="sql-user-error"><function>sql-user-error</function></link>
 853       is signalled if <parameter>operator</parameter> is not a symbol
 854       representing a supported SQL operator.</para>
 855     </refsect1>
 856     <refsect1>
 857       <title>See Also</title>
 858       <simplelist>
 859         <member><link linkend="sql"><function>sql</function></link></member>
 860         <member><link linkend="sql-expression"><function>sql-expression</function></link></member>
 861         <member><link linkend="sql-operator"><function>sql-operator</function></link></member>
 862       </simplelist>
 863     </refsect1>
 864     <refsect1>
 865       <title>Notes</title>
 866       <para>None.</para>
 867     </refsect1>
 868   </refentry>
 869
 870   <refentry id="sql-operator">
 871     <refmeta>
 872       <refentrytitle>SQL-OPERATOR</refentrytitle>
 873     </refmeta>
 874     <refnamediv>
 875       <refname>SQL-OPERATOR</refname>
 876       <refpurpose>Returns the symbol for the supplied SQL operator.</refpurpose>
 877       <refclass>Function</refclass>
 878     </refnamediv>
 879     <refsect1>
 880       <title>Syntax</title>
 881       <synopsis>
 882       <function>sql-operator</function> <parameter>operator</parameter> => <returnvalue>result</returnvalue></synopsis>
 883     </refsect1>
 884     <refsect1>
 885       <title>Arguments and Values</title>
 886       <variablelist>
 887         <varlistentry>
 888           <term><parameter>operator</parameter></term>
 889           <listitem>
 890             <para>A symbol denoting an SQL operator.</para>
 891           </listitem>
 892         </varlistentry>
 893         <varlistentry>
 894           <term><returnvalue>result</returnvalue></term>
 895           <listitem>
 896             <para>The Lisp symbol used by &clsql; to represent the
 897             specified operator.</para>
 898           </listitem>
 899         </varlistentry>
 900       </variablelist>
 901     </refsect1>
 902     <refsect1>
 903       <title>Description</title>
 904       <para>Returns the Lisp symbol corresponding to the SQL operator
 905       represented by the symbol <parameter>operator</parameter>. If
 906       <parameter>operator</parameter> does not represent a supported
 907       SQL operator or is not a symbol, nil is returned.
 908       </para>
 909     </refsect1>
 910     <refsect1>
 911       <title>Examples</title>
 912       <screen>
 913 (sql-operator 'like)
 914 => SQL-LIKE
 915       </screen>
 916     </refsect1>
 917     <refsect1>
 918       <title>Side Effects</title>
 919       <para>None.</para>
 920     </refsect1>
 921     <refsect1>
 922       <title>Affected by</title>
 923       <para>
 924         None.
 925       </para>
 926     </refsect1>
 927     <refsect1>
 928       <title>Exceptional Situations</title>
 929       <para>None.</para>
 930     </refsect1>
 931     <refsect1>
 932       <title>See Also</title>
 933       <simplelist>
 934         <member><link linkend="sql"><function>sql</function></link></member>
 935         <member><link linkend="sql-expression"><function>sql-expression</function></link></member>
 936         <member><link linkend="sql-operation"><function>sql-operation</function></link></member>
 937       </simplelist>
 938     </refsect1>
 939     <refsect1>
 940       <title>Notes</title>
 941       <para>
 942         &clsql;'s symbolic SQL syntax currently has support for the
 943         following &commonsql; compatible SQL operators:
 944       </para>
 945       <simplelist>
 946         <!-- CommonSQL Compatible -->
 947         <member><function>any</function></member>
 948         <member><function>some</function></member>
 949         <member><function>all</function></member>
 950         <member><function>not</function></member>
 951         <member><function>union</function></member>
 952         <member><function>intersect</function></member>
 953         <member><function>minus</function></member>
 954         <member><function>except
 955         </function></member>
 956         <member><function>order-by
 957         </function></member>
 958         <member><function>null
 959         </function></member>
 960         <member><function>*
 961         </function></member>
 962         <member><function>+
 963         </function></member>
 964         <member><function>/
 965         </function></member>
 966         <member><function>-
 967         </function></member>
 968         <member><function>like
 969         </function></member>
 970         <member><function>and
 971         </function></member>
 972         <member><function>or
 973         </function></member>
 974         <member><function>in
 975         </function></member>
 976         <member><function>substr
 977         </function></member>
 978         <member><function>||
 979         </function></member>
 980         <member><function>=
 981         </function></member>
 982         <member><function>&lt;
 983         </function></member>
 984         <member><function>>
 985         </function></member>
 986         <member><function>>=
 987         </function></member>
 988         <member><function>&lt;=
 989         </function></member>
 990         <member><function>&lt;>
 991         </function></member>
 992         <member><function>count
 993         </function></member>
 994         <member><function>max
 995         </function></member>
 996         <member><function>min
 997         </function></member>
 998         <member><function>avg
 999         </function></member>
1000         <member><function>sum
1001         </function></member>
1002         <member><function>function
1003         </function></member>
1004         <member><function>between
1005         </function></member>
1006         <member><function>distinct
1007         </function></member>
1008         <member><function>nvl
1009         </function></member>
1010         <member><function>slot-value
1011         </function></member>
1012         <member><function>userenv
1013         </function></member>
1014       </simplelist>
1015       <para>
1016         as well as the pseudo-operator <function>function</function>.
1017       </para>
1018       <para> The following operators are provided as &clsql; extensions to
1019       the &commonsql; API.
1020       <simplelist>
1021         <!-- CLSQL Extensions -->
1022         <member><function>concat
1023         </function></member>
1024         <member><function>substring
1025         </function></member>
1026         <member><function>limit
1027         </function></member>
1028         <member><function>group-by
1029         </function></member>
1030         <member><function>having
1031         </function></member>
1032         <member><function>not-null
1033         </function></member>
1034         <member><function>exists
1035         </function></member>
1036         <member><function>uplike
1037         </function></member>
1038         <member><function>is
1039         </function></member>
1040         <member><function>==
1041         </function></member>
1042         <member><function>the
1043         </function></member>
1044         <member><function>coalesce
1045         </function></member>
1046         <member><function>view-class
1047         </function></member>
1048       </simplelist>
1049       </para>
1050       <para>
1051         Note that some of these operators are not supported by all of
1052         the RDBMS supported by &clsql; (see the <link
1053         linkend="appendix">Appendix</link> for details).
1054       </para>
1055     </refsect1>
1056   </refentry>
1057
1058 </reference>