(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*)))
(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))
(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)
(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))
(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
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
(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))
(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)))))
;; 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)))
;; 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*
(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)
(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 #\))))
(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))
;; 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))
: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)))
projects / clsql.git / commitdiff