X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fref-syntax.xml;h=e0364fabd825483540f4d323de1c210d69a019dc;hb=4871b9ef13ed1cf4f7ef927bd026ca19e845f53c;hp=b13dd32ff0cd7c279673e28e464efe1592244ffe;hpb=aee3ea30595ebee301ccb1532062053c3c580e19;p=clsql.git
diff --git a/doc/ref-syntax.xml b/doc/ref-syntax.xml
index b13dd32..e0364fa 100644
--- 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.
+
+ Tip: just want it on
+
+ file-enable-sql-reader-syntax at the top of each file is easiest.
+
+
@@ -23,7 +29,7 @@
ENABLE-SQL-READER-SYNTAX
- MacroENABLE-SQL-READER-SYNTAX
+ ENABLE-SQL-READER-SYNTAXGlobally enable square bracket reader syntax.Macro
@@ -57,6 +63,12 @@
Modifies the default readtable.
+
+
+ &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 disable-sql-reader-syntax a couple times in the REPL.
+
+ See file-enable-sql-reader-syntax for an alternative.
+ Affected by
@@ -77,6 +89,7 @@
locally-enable-sql-reader-syntaxlocally-disable-sql-reader-syntaxrestore-sql-reader-syntax-state
+ file-enable-sql-reader-syntax
@@ -84,6 +97,11 @@
The symbolic SQL syntax is disabled by default.
+
+ &clsql; differs from &commonsql; in that
+ enable-sql-reader-syntax is defined as a
+ macro rather than a function.
+
@@ -92,7 +110,7 @@
DISABLE-SQL-READER-SYNTAX
- MacroDISABLE-SQL-READER-SYNTAX
+ DISABLE-SQL-READER-SYNTAXGlobally disable square bracket reader syntax.Macro
@@ -146,6 +164,7 @@
locally-enable-sql-reader-syntaxlocally-disable-sql-reader-syntaxrestore-sql-reader-syntax-state
+ file-enable-sql-reader-syntax
@@ -153,6 +172,11 @@
The symbolic SQL syntax is disabled by default.
+
+ &clsql; differs from &commonsql; in that
+ disable-sql-reader-syntax is defined as a
+ macro rather than a function.
+
@@ -161,8 +185,8 @@
LOCALLY-ENABLE-SQL-READER-SYNTAX
- MacroLOCALLY-ENABLE-SQL-READER-SYNTAX
- Globally enable square bracket reader syntax.
+ LOCALLY-ENABLE-SQL-READER-SYNTAX
+ Locally enable square bracket reader syntax.Macro
@@ -200,6 +224,12 @@
Modifies the default readtable.
+
+
+ &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 disable-sql-reader-syntax a couple times in the REPL.
+
+ See file-enable-sql-reader-syntax for an alternative.
+ Affected by
@@ -218,6 +248,7 @@
disable-sql-reader-syntaxlocally-disable-sql-reader-syntaxrestore-sql-reader-syntax-state
+ file-enable-sql-reader-syntax
@@ -225,6 +256,11 @@
The symbolic SQL syntax is disabled by default.
+
+ &clsql; differs from &commonsql; in that
+ locally-enable-sql-reader-syntax is
+ defined as a macro rather than a function.
+
@@ -234,7 +270,7 @@
LOCALLY-DISABLE-SQL-READER-SYNTAX
- MacroLOCALLY-DISABLE-SQL-READER-SYNTAX
+ LOCALLY-DISABLE-SQL-READER-SYNTAXLocally disable square bracket reader syntax.Macro
@@ -295,6 +331,7 @@
disable-sql-reader-syntaxlocally-enable-sql-reader-syntaxrestore-sql-reader-syntax-state
+ file-enable-sql-reader-syntax
@@ -302,6 +339,11 @@
The symbolic SQL syntax is disabled by default.
+
+ &clsql; differs from &commonsql; in that
+ locally-disable-sql-reader-syntax is
+ defined as a macro rather than a function.
+
@@ -310,7 +352,7 @@
RESTORE-SQL-READER-SYNTAX-STATE
- MacroRESTORE-SQL-READER-SYNTAX-STATE
+ RESTORE-SQL-READER-SYNTAX-STATE
Restore square bracket reader syntax to its previous state.
@@ -374,6 +416,7 @@
disable-sql-reader-syntaxlocally-enable-sql-reader-syntaxlocally-disable-sql-reader-syntax
+ file-enable-sql-reader-syntax
@@ -381,6 +424,85 @@
The symbolic SQL syntax is disabled by default.
+
+ &clsql; differs from &commonsql; in that
+ restore-sql-reader-syntax-state is
+ defined as a macro rather than a function.
+
+
+
+
+
+
+ FILE-ENABLE-SQL-READER-SYNTAX
+
+
+ FILE-ENABLE-SQL-READER-SYNTAX
+
+ Enable the square bracket reader syntax for the duration of the file.
+
+ Macro
+
+
+ Syntax
+
+ file-enable-sql-reader-syntax =>
+
+
+ Arguments and Values
+ None.
+
+
+ Description
+ Uncoditionally enables the SQL reader syntax. Unlike
+ enable-sql-reader-syntax and
+ disable-sql-reader-syntax 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.
+
+ Once enabled this way there is no corresponding disable function but instead relies on being used in a file context. The spec for load and compile-file states that the *readtable* will be restored after processing the file.
+
+
+ Examples
+ Intended to be used at the top of a file that contains sql reader syntax.
+
+ (in-package :my-package)
+ (clsql:file-enable-sql-reader-syntax)
+ ...
+ ;;functions that use the square bracket syntax.
+
+
+
+ Side Effects
+
+ Modifies the readtable for #\[ and #\]
+
+
+
+ Affected by
+ None.
+
+
+ Exceptional Situations
+
+ None.
+
+
+
+ See Also
+
+ enable-sql-reader-syntax
+ disable-sql-reader-syntax
+ locally-enable-sql-reader-syntax
+ locally-disable-sql-reader-syntax
+
+
+
+ Notes
+
+ Unique to &clsql;, not present in &commonsql;.
+
@@ -389,7 +511,7 @@
SQL
- FunctionSQL
+ SQLConstruct an SQL string from supplied expressions.Function
@@ -488,7 +610,7 @@
SQL-EXPRESSION
- FunctionSQL-EXPRESSION
+ SQL-EXPRESSIONConstructs an SQL expression from supplied keyword arguments.Function
@@ -646,14 +768,14 @@
SQL-OPERATION
- FunctionSQL-OPERATION
+ SQL-OPERATIONConstructs an SQL expression from a supplied operator and arguments.FunctionSyntax
- sql-operationoperation&restargs => result
+ sql-operationoperator&restargs => resultsql-operation 'function func&restargs => result
@@ -661,7 +783,7 @@
Arguments and Values
- operation
+ operatorA symbol denoting an SQL operator.
@@ -689,9 +811,9 @@
DescriptionReturns an SQL expression constructed from the supplied
- SQL operator or function operation and
+ SQL operator or function operator and
its arguments args. If
- operation is passed the symbol 'function
+ operator is passed the symbol 'function
then the first value in args is taken to
be a valid SQL function and the remaining values in
args its arguments.
@@ -728,7 +850,7 @@
Exceptional SituationsAn error of type sql-user-error
- is signalled if operation is not a symbol
+ is signalled if operator is not a symbol
representing a supported SQL operator.
@@ -750,20 +872,20 @@
SQL-OPERATOR
- FunctionSQL-OPERATOR
+ SQL-OPERATORReturns the symbol for the supplied SQL operator.FunctionSyntax
- sql-operatoroperation => result
+ sql-operatoroperator => resultArguments and Values
- operation
+ operatorA symbol denoting an SQL operator.
@@ -779,9 +901,9 @@
Description
- Returns the Lisp symbol corresponding to the SQL operation
- represented by the symbol operation. If
- operation does not represent a supported
+ Returns the Lisp symbol corresponding to the SQL operator
+ represented by the symbol operator. If
+ operator does not represent a supported
SQL operator or is not a symbol, nil is returned.
@@ -816,117 +938,120 @@
Notes
- &clsql;'s symbolic SQL syntax currently has support for
- the following SQL operators:
+
+ &clsql;'s symbolic SQL syntax currently has support for the
+ following &commonsql; compatible SQL operators:
- any
- ,
- some
- ,
- all
- ,
- not
- ,
- union
- ,
- intersect
- ,
- minus
- ,
+ any
+ some
+ all
+ not
+ union
+ intersect
+ minusexcept
- ,
+
order-by
- ,
+
null
- ,
+
*
- ,
+
+
- ,
+
/
- ,
+
-
- ,
+
like
- ,
+
and
- ,
+
or
- ,
+
in
- ,
+
substr
- ,
+
||
- ,
+
=
- ,
+
<
- ,
+
>
- ,
+
>=
- ,
+
<=
- ,
+
<>
- ,
+
count
- ,
+
max
- ,
+
min
- ,
+
avg
- ,
+
sum
- ,
+
function
- ,
+
between
- ,
+
distinct
- ,
+
nvl
- ,
+
slot-value
- ,
+
userenv
+
+
+
+ as well as the pseudo-operator function.
+
+ The following operators are provided as &clsql; extensions to
+ the &commonsql; API.
+
- ,
concat
- ,
+
substring
- ,
+
limit
- ,
+
group-by
- ,
+
having
- ,
+
not-null
- ,
+
exists
- ,
+
uplike
- ,
+
is
- ,
+
==
- ,
+
the
- ,
+
coalesce
- ,
+
view-class
-
- as well as the pseudo-operator
- function. Note that some of these operators
- are not supported by all of the RDBMS supported by
- &clsql;.
+
+
+
+ Note that some of these operators are not supported by all of
+ the RDBMS supported by &clsql; (see the Appendix for details).
+