From 5be31565b7d87b90f0e79a9e61af84ad05e12920 Mon Sep 17 00:00:00 2001 From: Marcus Pearce Date: Wed, 19 May 2004 23:07:05 +0000 Subject: [PATCH] r9402: Reworked docstrings. --- ChangeLog | 6 +++ doc/TODO | 7 +++ sql/recording.lisp | 105 ++++++++++++++++++++++++++------------------- sql/syntax.lisp | 74 ++++++++++++++++++-------------- 4 files changed, 116 insertions(+), 76 deletions(-) diff --git a/ChangeLog b/ChangeLog index c6cd486..4667f2c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +19 May 2004 Marcus Pearce (m.t.pearce@city.ac.uk) + * sql/recording.lisp: reworked docstrings. + * sql/syntax.lisp: reworked docstrings. + * doc/TODO: added notes about extensions to SQL-RECORDING-P and the + SQL syntax state functions being macros. + 19 May 2004 Kevin Rosenberg (kevin@rosenberg.net) * sql/package.lisp: Export initialize-database-type and *initialize-database-types* from CLSQL package. diff --git a/doc/TODO b/doc/TODO index b288ef0..f6b1715 100644 --- a/doc/TODO +++ b/doc/TODO @@ -4,6 +4,8 @@ DOCUMENTATION TO DO LIST - Ideally, this will be extremely minimal + - The SQL syntax state functions are macros in CLSQL. + 2. Underdocumented CommonSQL features: - Retrieval immediate @@ -28,6 +30,11 @@ DOCUMENTATION TO DO LIST - SELECT: additional keyword arguments accepted include :LIMIT, :OFFSET, :INNER-JOIN and :ON. + - SQL-RECORDING-P: also accepts :both and :either values for the TYPE + parameter. + + - SQL-EXPRESSION: also accepts a :params keyword arg which is passed + 4. Documenting lower level, non-CommonSQL functions (some of this is already done). diff --git a/sql/recording.lisp b/sql/recording.lisp index 7df9a8b..8bff335 100644 --- a/sql/recording.lisp +++ b/sql/recording.lisp @@ -16,12 +16,16 @@ (in-package #:clsql-sys) (defun start-sql-recording (&key (type :commands) (database *default-database*)) - "Begin recording SQL command or result traffic. By default the -broadcast stream is just *STANDARD-OUTPUT* but this can be modified -using ADD-SQL-STREAM or DELETE-SQL-STREAM. TYPE determines whether SQL -command or result traffic is recorded, or both. It must be either -:commands, :results or :both, and defaults to :commands. DATABASE -defaults to *default-database*." + "Starts recording of SQL commands sent to and/or results +returned from DATABASE which defaults to *DEFAULT-DATABASE*. The +SQL is output on one or more broadcast streams, initially just +*STANDARD-OUTPUT*, and the functions ADD-SQL-STREAM and +DELETE-SQL-STREAM may be used to add or delete command or result +recording streams. The default value of TYPE is :commands which +means that SQL commands sent to DATABASE are recorded. If TYPE +is :results then SQL results returned from DATABASE are +recorded. Both commands and results may be recorded by passing +TYPE value of :both." (when (or (eq type :both) (eq type :commands)) (setf (command-recording-stream database) (make-broadcast-stream *standard-output*))) @@ -31,10 +35,13 @@ defaults to *default-database*." (values)) (defun stop-sql-recording (&key (type :commands) (database *default-database*)) - "Stops recording of SQL command or result traffic. TYPE determines -whether to stop SQL command or result traffic, or both. It must be -either :commands, :results or :both, defaulting to :commands. DATABASE -defaults to *default-database*." + "Stops recording of SQL commands sent to and/or results +returned from DATABASE which defaults to *DEFAULT-DATABASE*. The +default value of TYPE is :commands which means that SQL commands +sent to DATABASE will no longer be recorded. If TYPE is :results +then SQL results returned from DATABASE will no longer be +recorded. Recording may be stopped for both commands and results +by passing TYPE value of :both." (when (or (eq type :both) (eq type :commands)) (setf (command-recording-stream database) nil)) (when (or (eq type :both) (eq type :results)) @@ -42,9 +49,10 @@ defaults to *default-database*." (values)) (defun sql-recording-p (&key (type :commands) (database *default-database*)) - "Returns t if recording of TYPE of SQL interaction specified is -enabled. TYPE must be either :commands, :results, :both or :either. -DATABASE defaults to *default-database*." + "Predicate to test whether the SQL recording specified by TYPE +is currently enabled for DATABASE which defaults to *DEFAULT-DATABASE*. +TYPE may be one of :commands, :results, :both or :either, defaulting to +:commands, otherwise nil is returned." (when (or (and (eq type :commands) (command-recording-stream database)) (and (eq type :results) @@ -59,10 +67,13 @@ DATABASE defaults to *default-database*." (defun add-sql-stream (stream &key (type :commands) (database *default-database*)) - "Add the given STREAM as a component stream for the recording -broadcast stream for the given SQL interaction TYPE. TYPE must be -either :commands, :results, or :both, defaulting to :commands. -DATABASE defaults to *default-database*." + "Adds the supplied stream STREAM (or T for *standard-output*) +as a component of the recording broadcast stream for the SQL +recording type specified by TYPE on DATABASE which defaults to +*DEFAULT-DATABASE*. TYPE must be one of :commands, :results, +or :both, defaulting to :commands, depending on whether the +stream is to be added for recording SQL commands, results or +both." (when (or (eq type :both) (eq type :commands)) (unless (member stream (list-sql-streams :type :commands :database database)) @@ -80,10 +91,12 @@ DATABASE defaults to *default-database*." (defun delete-sql-stream (stream &key (type :commands) (database *default-database*)) - "Removes the given STREAM from the recording broadcast stream for -the given TYPE of SQL interaction. TYPE must be either :commands, -:results, or :both, defaulting to :commands. DATABASE defaults to -*default-database*." + "Removes the supplied stream STREAM from the recording broadcast +stream for the SQL recording type specified by TYPE on DATABASE +which defaults to *DEFAULT-DATABASE*. TYPE must be one +of :commands, :results, or :both, defaulting to :commands, +depending on whether the stream is to be added for recording SQL +commands, results or both." (when (or (eq type :both) (eq type :commands)) (setf (command-recording-stream database) (apply #'make-broadcast-stream @@ -97,10 +110,12 @@ the given TYPE of SQL interaction. TYPE must be either :commands, stream) (defun list-sql-streams (&key (type :commands) (database *default-database*)) - "Returns the set of streams which the recording broadcast stream -send SQL interactions of the given TYPE sends data. TYPE must be -either :commands, :results, or :both, defaulting to :commands. -DATABASE defaults to *default-database*." + "Returns the list of component streams for the broadcast stream +recording SQL commands sent to and/or results returned from +DATABASE which defaults to *DEFAULT-DATABASE*. TYPE must be one +of :commands, :results, or :both, defaulting to :commands, and +determines whether the listed streams contain those recording SQL +commands, results or both." (let ((crs (command-recording-stream database)) (rrs (result-recording-stream database))) (cond @@ -115,9 +130,11 @@ DATABASE defaults to *default-database*." (error "Unknown recording type. ~A" type))))) (defun sql-stream (&key (type :commands) (database *default-database*)) - "Returns the broadcast streams used for recording SQL commands or -results traffic. TYPE must be either :commands or :results defaulting -to :commands while DATABASE defaults to *default-database*." + "Returns the broadcast stream used for recording SQL commands +sent to or results returned from DATABASE which defaults to +*DEFAULT-DATABASE*. TYPE must be one of :commands or :results, +defaulting to :commands, and determines whether the stream +returned is that used for recording SQL commands or results." (cond ((eq type :commands) (command-recording-stream database)) @@ -127,24 +144,24 @@ to :commands while DATABASE defaults to *default-database*." (error "Unknown recording type. ~A" type)))) (defun record-sql-command (expr database) - (if database - (with-slots (command-recording-stream) - database - (if command-recording-stream - (format command-recording-stream "~&;; ~A ~A => ~A~%" - (iso-timestring (get-time)) - (database-name database) - expr))))) + (when database + (with-slots (command-recording-stream) + database + (when command-recording-stream + (format command-recording-stream "~&;; ~A ~A => ~A~%" + (iso-timestring (get-time)) + (database-name database) + expr))))) (defun record-sql-result (res database) - (if database - (with-slots (result-recording-stream) - database - (if result-recording-stream - (format result-recording-stream "~&;; ~A ~A <= ~A~%" - (iso-timestring (get-time)) - (database-name database) - res))))) + (when database + (with-slots (result-recording-stream) + database + (when result-recording-stream + (format result-recording-stream "~&;; ~A ~A <= ~A~%" + (iso-timestring (get-time)) + (database-name database) + res))))) diff --git a/sql/syntax.lisp b/sql/syntax.lisp index 6d771da..c265f63 100644 --- a/sql/syntax.lisp +++ b/sql/syntax.lisp @@ -30,15 +30,17 @@ ;; Exported functions for disabling SQL syntax. (defmacro disable-sql-reader-syntax () - "Turn off SQL square bracket syntax changing syntax state. Set state -such that RESTORE-SQL-READER-SYNTAX-STATE will make the syntax -disabled if it is consequently locally enabled." + "Turns off the SQL reader syntax setting the syntax state such +that if the syntax is subsequently enabled, +RESTORE-SQL-READER-SYNTAX-STATE will disable it again." '(eval-when (:compile-toplevel :load-toplevel :execute) - (setf *restore-sql-reader-syntax* nil) - (%disable-sql-reader-syntax))) + (setf *restore-sql-reader-syntax* nil) + (%disable-sql-reader-syntax))) (defmacro locally-disable-sql-reader-syntax () - "Turn off SQL square bracket syntax and do not change syntax state." + "Turns off the SQL reader syntax without changing the syntax +state such that RESTORE-SQL-READER-SYNTAX-STATE will re-establish +the current syntax state." '(eval-when (:compile-toplevel :load-toplevel :execute) (%disable-sql-reader-syntax))) @@ -52,17 +54,19 @@ disabled if it is consequently locally enabled." ;; Exported functions for enabling SQL syntax. (defmacro enable-sql-reader-syntax () - "Turn on SQL square bracket syntax changing syntax state. Set state -such that RESTORE-SQL-READER-SYNTAX-STATE will make the syntax enabled -if it is consequently locally disabled." + "Turns on the SQL reader syntax setting the syntax state such +that if the syntax is subsequently disabled, +RESTORE-SQL-READER-SYNTAX-STATE will enable it again." '(eval-when (:compile-toplevel :load-toplevel :execute) - (setf *restore-sql-reader-syntax* t) - (%enable-sql-reader-syntax))) + (setf *restore-sql-reader-syntax* t) + (%enable-sql-reader-syntax))) (defmacro locally-enable-sql-reader-syntax () - "Turn on SQL square bracket syntax and do not change syntax state." + "Turns on the SQL reader syntax without changing the syntax +state such that RESTORE-SQL-READER-SYNTAX-STATE will re-establish +the current syntax state." '(eval-when (:compile-toplevel :load-toplevel :execute) - (%enable-sql-reader-syntax))) + (%enable-sql-reader-syntax))) (defun %enable-sql-reader-syntax () (unless *original-reader-enter* @@ -72,10 +76,10 @@ if it is consequently locally disabled." (values)) (defmacro restore-sql-reader-syntax-state () - "Sets the enable/disable square bracket syntax state to reflect the -last call to either DISABLE-SQL-READER-SYNTAX or -ENABLE-SQL-READER-SYNTAX. The default state of the square bracket -syntax is disabled." + "Enables the SQL reader syntax if ENABLE-SQL-READER-SYNTAX has +been called more recently than DISABLE-SQL-READER-SYNTAX and +otherwise disables the SQL reader syntax. By default, the SQL +reader syntax is disabled." '(eval-when (:compile-toplevel :load-toplevel :execute) (if *restore-sql-reader-syntax* (%enable-sql-reader-syntax) @@ -92,13 +96,15 @@ syntax is disabled." (cons (sql-operator (car sqllist)) (cdr sqllist))) (t (apply #'generate-sql-reference sqllist))))) -;; Internal function that disables the close syntax when leaving sql context. (defun disable-sql-close-syntax () + "Internal function that disables the close syntax when leaving + sql context." (set-macro-character *sql-macro-close-char* *original-reader-exit*) (setf *original-reader-exit* nil)) -;; Internal function that enables close syntax when entering SQL context. (defun enable-sql-close-syntax () + "Internal function that enables close syntax when entering SQL + context." (setf *original-reader-exit* (get-macro-character *sql-macro-close-char*)) (set-macro-character *sql-macro-close-char* (get-macro-character #\)))) @@ -106,14 +112,14 @@ syntax is disabled." (cond ((= (length arglist) 1) ; string, table or attribute (if (stringp (car arglist)) (sql-expression :string (car arglist)) - (sql-expression :attribute (car arglist)))) + (sql-expression :attribute (car arglist)))) ((<= 2 (length arglist)) (let ((sqltype (if (keywordp (caddr arglist)) (caddr arglist) nil)) (sqlparam (if (keywordp (caddr arglist)) (caddr arglist)))) (cond - ((stringp (cadr arglist)) + ((stringp (cadr arglist)) (sql-expression :table (car arglist) :alias (cadr arglist) :type sqltype)) @@ -133,17 +139,17 @@ syntax is disabled." ;; Exported functions for dealing with SQL syntax (defun sql (&rest args) - "Generates SQL from a set of expressions given by ARGS. Each -argument is translated into SQL and then the args are concatenated -with a single space between each pair." + "Returns an SQL string generated from the SQL expressions +ARGS. The expressions are translated into SQL strings and then +concatenated with a single space delimiting each expression." (format nil "~{~A~^ ~}" (mapcar #'sql-output args))) (defun sql-expression (&key string table alias attribute type params) - "Generates an SQL expression from the given keywords. Valid -combinations of the arguments are: string; table; table and alias; -table and attribute; table, attribute, and type; table or alias, and -attribute; table or alias, and attribute and type; attribute; and -attribute and type." + "Returns an SQL expression constructed from the supplied arguments +which may be combined as follows: ATTRIBUTE and TYPE; ATTRIBUTE; +ALIAS or TABLE and ATTRIBUTE and TYPE; ALIAS or TABLE and +ATTRIBUTE; TABLE, ATTRIBUTE and TYPE; TABLE and ATTRIBUTE; TABLE +and ALIAS; TABLE; and STRING." (cond (string (make-instance 'sql :string string)) @@ -157,15 +163,19 @@ attribute and type." :table-alias alias)))) (defun sql-operator (operation) - "Takes an SQL operator as an argument and returns the Lisp symbol -for the operator." + "Returns the Lisp symbol corresponding to the SQL operation + represented by the symbol OPERATION." (typecase operation (string nil) (symbol (gethash (symbol-name-default-case (symbol-name operation)) *sql-op-table*)))) (defun sql-operation (operation &rest rest) - "Generates an SQL statement from an operator and arguments." + "Returns an SQL expression constructed from the supplied SQL +operator or function OPERATION and its arguments REST. If +OPERATION is passed the symbol FUNCTION then the first value in +REST is taken to be a valid SQL function and the remaining values +in REST its arguments." (if (sql-operator operation) (apply (symbol-function (sql-operator operation)) rest) (error "~A is not a recognized SQL operator." operation))) -- 2.34.1