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