Common Lisp's condition system, with its exceptions and restarts, is one of its unique features. Unfortunately, there aren't many good tutorials explaining this concept very well. One good introduction to this is the chapter on conditions and restarts in Peter Seibel's excellent book, Practical Common Lisp (see 1, 2). This tutorial assumes some knowledge of the condition system, so you might want to read that chapter before proceeding.
I'll attempt to show how effective CL's condition system can be, with a validator for CSV (comma-separated values) files. The validator will check that all the fields in each row of the file are valid (according to some defined criteria).
The first row of the CSV will be a comma-separated list of headers, followed by rows with each column corresponding to the headers in the first row. A sample file looks like this:
rating,url,visitors,date 4,http://chaitanyagupta.com/home,1233445,2000-01-01 5,http://chaitanyagupta.com/blog,33333,2006-02-02 5,http://chaitanyagupta.com/code,2121212,2007-03-03
First we write functions to validate the four headers we used above:
date. Note that these functions
depend on the CL-PPCRE package (http://weitz.de/cl-ppcre).
(defun validate-url (string) "The URL of the page; should start with http:// or https://." (unless (cl-ppcre:scan "^https?://" string) (csv-error "URL invalid." :value string))) (defun validate-rating (string) "String should contain an integer between 1 and 5, inclusive." (let ((rating (parse-integer string :junk-allowed t))) (unless (and (integerp rating) (<= 1 rating 5)) (csv-error "Rating not an integer in range." :value string)))) (defun validate-visitors (string) "The number of visitors to the page; string should contain an integer more than or equal to zero." (let ((visitors (parse-integer string :junk-allowed nil))) (unless (and (integerp visitors) (>= visitors 0)) (csv-error "Number of visitors invalid." :value string)))) (defun validate-date (string) "The published date of the URL. Should be in yyyy-mm-dd format." (let ((split (cl-ppcre:split "-" string))) (flet ((!valid-number-of-digits-p (string n) ; See note 3 (and (every #'digit-char-p string) (= (length string) n)))) (unless (and (!valid-number-of-digits-p (first split) 4) (!valid-number-of-digits-p (second split) 2) (!valid-number-of-digits-p (third split) 2)) (csv-error "Published date not in valid format." :value string)))))
All these functions take a string as an argument, and if it doesn't
satisfy the validation criteria, an error is signalled using the
csv-error. This is defined next.
csv-error signals a condition of type
both of which are defined below.
(define-condition csv-error (error) ((message :initarg :message :accessor csv-error-message :initform nil :documentation "Text message indicating what went wrong with the validation.") (value :initarg :value :accessor csv-error-value :initform nil :documentation "The value of the field for which the error is signalled.") (line-number :initarg :line-number :accessor csv-error-line-number :initform nil :documentation "The line number of the row in for the error was signalled."))) ;; Do something more useful than the default printer behaviour (defmethod print-object ((object csv-error) stream) (print-unreadable-object (object stream :type t :identity t) (format stream "~@[L~A ~]~S~@[: ~S~]" (csv-error-line-number object) (csv-error-message object) (csv-error-value object)))) ;; We use this function to signal our validation error (defun csv-error (message &key value line-number) (error 'csv-error :message message :value value :line-number line-number))
The parser converts raw CSV text into a list of lists -- each item in these lists corresponds to a field in the CSV.
(defun parse-csv-file (file) (with-open-file (f file :direction :input) (loop for line = (read-line f nil) while line collect (cl-ppcre:split "," line))))
Finally, we get down to writing the validator,
validate-csv. If the
validation is succesful (i.e. all the fields in the CSV are valid),
the function returns normally. If any invalid field is present, an
error will be signalled (using the validator functions defined above).
This version of the validator doesn't contain any restarts though.
(defun validate-csv (file) (destructuring-bind (headers . rows) (parse-csv-file file) (loop for row in rows for line-number upfrom 2 do (when (/= (length row) (length headers)) (csv-error "Number of fields doesn't equal number of headers." :line-number line-number)) (handler-bind ;; Set the LINE-NUMBER slot of the signalled ;; csv-error. Note that since this clause returns normally, ;; the error doesn't stop here, it goes "up" the stack ((csv-error #'(lambda (c) (setf (csv-error-line-number c) line-number)))) (loop for header in headers for field in row do (validate-field header field)))))) ;; Takes a header name and a string value as arguments; checks the ;; validity of the value by calling the appropriate validator function (defun validate-field (header value) (flet ((!header-matches (string) (string-equal header string))) (cond ((!header-matches "url") (validate-url value)) ((!header-matches "rating") (validate-rating value)) ((!header-matches "visitors") (validate-visitors value)) ((!header-matches "date") (validate-date value)) (t (csv-error "Invalid header." :value header)))))
There are a few actions we can take once an "invalid" field has been
detected (i.e. a
csv-error is signalled), e.g. we can abort the
validation, we can continue validation on the next row, or we continue
validation with the remaining fields in the same row (to name just a
Aborting the validation is as simple as invoking the
in the debugger, or doing something like this:
(handler-case (progn (validate-csv "~/tmp/test.csv") :success) (csv-error () :failure))
To continue validation on the same row, or the next one, we add a
couple of restarts using the
(defun validate-csv (file) (destructuring-bind (headers . rows) (parse-csv-file file) (loop for row in rows for line-number upfrom 2 do ;; If this restart is invoked, validation will continue on ;; the next row (with-simple-restart (continue-next-row "Continue validation on next row.") (when (/= (length row) (length headers)) (csv-error "Number of fields doesn't equal number of headers." :line-number line-number)) (loop for header in headers for field in row do (handler-bind ((csv-error #'(lambda (c) (setf (csv-error-line-number c) line-number)))) ;; If this restart is invoked, validation will continue ;; on the next field in the row (with-simple-restart (continue-next-field "Continue validation on next field.") (validate-field header field))))))))
Time for some fun now. Pass an invalid file to the validator, and what
do we see in the debugger? Two new restarts:
CONTINUE-NEXT-ROW. Select any one of them to see the validation
move forward. The
ABORT restart should be present all the time, so
we can end the validation any time we want.
We'll add one more restart now: this will allow us to revalidate the whole file if an error is signalled.
;; Note that what was known as VALIDATE-CSV earlier is now called ;; VALIDATE-CSV-AUX. (defun validate-csv (file) (restart-case (validate-csv-aux file) (retry-file () :report (lambda (stream) (format stream "Retry validating the file ~A." file)) (validate-csv file)))) (defun validate-csv-aux (file) (destructuring-bind (headers . rows) (parse-csv-file file) (loop for row in rows for line-number upfrom 2 do (with-simple-restart (continue-next-row "Continue validation on next row.") (when (/= (length row) (length headers)) (csv-error "Number of fields doesn't equal number of headers." :line-number line-number)) (loop for header in headers for field in row do (handler-bind ((csv-error #'(lambda (c) (setf (csv-error-line-number c) line-number)))) (with-simple-restart (continue-next-field "Continue validation on next field.") (validate-field header field))))))))
Now what happens if we pass an invalid file to
validate-csv? We get
RETRY-FILE restart in the debugger. This means that we can fix
the problematic field, save the file, and start the validation all
over again, without having exited the debugger!
Apart from the debugger, we can also handle restarts using
For example, the following function will continue validating the file
as long as CSV-ERRORs are signalled and one of
CONTINUE-NEXT-ROW restarts is available. It collects those errors
in a list and returns the same.
(defun list-csv-errors (file) (let ((result nil)) (handler-bind ((csv-error #'(lambda (c) (let ((restart (or (find-restart 'continue-next-field) (find-restart 'continue-next-row)))) (when restart (push c result) (invoke-restart restart)))))) (validate-csv file)) (nreverse result)))
If we want a non-programmer to use the validator, we can provide a way
to upload the CSV file (e.g. using Hunchentoot) and give a nicely
formatted output of
list-csv-errors in the browser.
What I really like about the condition system is how it allows one to
defer decisions to higher-level functions. The low-level functions
provide different ways to move forward in case of exceptions (this is
validate-csv does), while the higher-level functions actually get
to decide what path to take (like
If we wanted
list-csv-errors to list only one error per each row,
that change would have been trivial, thanks to the restarts we have
provided. This separation of logic, IMHO, makes it a very elegant tool
in dealing with problems like these.
If you have any questions or comments, drop a mail to: mail at chaitanyagupta . com
Date: 2008/05/06 21:12:25