r9220: Added type specifier for universal-time.

[clsql.git] / sql / generics.lisp

diff --git a/sql/generics.lisp b/sql/generics.lisp
index d1b642aecf2202ebcf595302c926b082b5caa393..f38b80bb01d37900386f7f8ac8b69fe8b22c96f7 100644 (file)
--- a/sql/generics.lisp
+++ b/sql/generics.lisp
@@ -18,6 +18,38 @@
 
 (in-package #:clsql-sys)
 
+(defgeneric select (&rest args) 
+  (:documentation
+   "The function SELECT selects data from DATABASE, which has a
+default value of *DEFAULT-DATABASE*, given the constraints
+specified by the rest of the ARGS. It returns a list of objects
+as specified by SELECTIONS. By default, the objects will each be
+represented as lists of attribute values. The argument SELECTIONS
+consists either of database identifiers, type-modified database
+identifiers or literal strings. A type-modifed database
+identifier is an expression such as [foo :string] which means
+that the values in column foo are returned as Lisp strings.  The
+FLATP argument, which has a default value of nil, specifies if
+full bracketed results should be returned for each matched
+entry. If FLATP is nil, the results are returned as a list of
+lists. If FLATP is t, the results are returned as elements of a
+list, only if there is only one result per row. The arguments
+ALL, SET-OPERATION, DISTINCT, FROM, WHERE, GROUP-BY, HAVING and
+ORDER-by have the same function as the equivalent SQL expression.
+The SELECT function is common across both the functional and
+object-oriented SQL interfaces. If selections refers to View
+Classes then the select operation becomes object-oriented. This
+means that SELECT returns a list of View Class instances, and
+SLOT-VALUE becomes a valid SQL operator for use within the where
+clause. In the View Class case, a second equivalent select call
+will return the same View Class instance objects. If REFRESH is
+true, then existing instances are updated if necessary, and in
+this case you might need to extend the hook INSTANCE-REFRESHED.
+The default value of REFRESH is nil. SQL expressions used in the
+SELECT function are specified using the square bracket syntax,
+once this syntax has been enabled using
+ENABLE-SQL-READER-SYNTAX."))
+
 (defgeneric update-record-from-slot (object slot &key database)
   (:documentation
    "The generic function UPDATE-RECORD-FROM-SLOT updates an individual
@@ -84,11 +116,6 @@ your application needs to take action when a View Class instance has
 been updated by (select ... :refresh t) then add an INSTANCE-REFRESH
 method specializing on your subclass of STANDARD-DB-OBJECT."))
 
-(defgeneric database-null-value (type)
-  (:documentation 
-   "Return an expression of type TYPE which SQL NULL values will be
-converted into."))
-
 (defgeneric update-slot-with-null (instance slotname slotdef)
   (:documentation "Called to update a slot when its column has a NULL
 value.  If nulls are allowed for the column, the slot's value will be