Common Lisp: Введение в Условия и Перезапуск (перевод)

Оригинал: Common Lisp: A Tutorial on Conditions and Restarts

 

Содержание

• Предисловие
• Валидация заголовков
• Сигнализируем об ошибках валидации
• Парсинг CSV
• Валидатор (без перезапусков)
• Добавляем перезапуски
• Начинаем всё с начала
• Обработка перезапусков
• Заключение
• Заметки

 

Предисловие

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.

Система условий, с её исключениями и перезапусками, является одной из уникальных особенностей языка Common Lisp (CL). К сожалению, учебных материалов, объясняющих данную концепцию, существует не так уж много. Информацию, касающуюся условий и перезапусков, можно найти в одной из глав прекрасной книги Питера Сибела (Peter Seibel), "Практический Коммон Лисп" (Practical Common Lisp) (см. 1, 2). Настоящее введение предполагает наличие некоторых знаний касательно системы условий, поэтому перед тем как продолжить, необходимо как минимум прочитать эту главу (русский перевод).

I'll attempt to show how effective CL's condition system can be, witha validator for CSV (comma-separated values) files. The validator willcheck that all the fields in each row of the file are valid (accordingto some defined criteria).

Я попытаюсь показать, насколько может быть эффективна система условий в CL на примере валидатора для CSV-файлов. Этот валидатор будет проверять правильность (в соответствии с некоторыми заданными критериями) всех полей данных во всех строках файла.

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:

Первая строка CSV-файла - разделяемый запятыми список заголовков, за которым следуют строки, в которых каждая колонка соответствует заголовку из первой строки. Пример может выглядеть следующим образом:

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: rating, url, visitors, and date. Note that these functions depend on the CL-PPCRE package (http://weitz.de/cl-ppcre).

Сначала напишем функции для валидации четырех заголовков, приведенных выше: rating, url, visitors и date. Заметьте, что эти функции зависят от библиотеки 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 aninteger
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 function csv-error. This is defined next.

Все эти функции принимают в качестве аргумента строку, и если строка не удовлетворяет критерию валидации, они сигнализируют ошибку, вызывая функцию csv-error, определение которой приведено далее.

 

Сигнализируем об ошибках валидации.

The function csv-error signals a condition of type csv-error, both of which are defined below.

Функция csv-error сигнализирует условие, имеющее тип csv-error. Посмотрим на их определения:

(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))

 

Парсим CSV-файл

The parser converts raw CSV text into a list of lists -- each item in these lists corresponds to a field in the CSV.

Парсер преобразует CSV-файл в список списков, каждый элемент которых соответствует полю 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).

Наконец мы дошли до написания валидатора, validate-csv. В случае успешной валидации (т.е. когда все записи верны) происходит обычный возврат из функции. Если же обнаружена неверная запись, валидирующие функции сигнализируют об ошибке.

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 few).

В случае обнаружения "неверной" записи (когда сигнализируется условие csv-error) мы можем предпринять некоторые действия, например, прекратить дальнейшую валидацию, или продолжить валидацию со вледующей строки, или продолжить валидацию остальных полей текущей строки.

Aborting the validation is as simple as invoking the ABORT restart in the debugger, or doing something like this:

Прекращение валидации произойдет если выбрать перезапуск ABORT в отладчике, или если использовать код вроде такого:

(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 with-simple-restart macro:

Чтобы продолжить валидацию с той же строки, или со следующей, добавим пару перезапусков используя макрос with-simple-restart:

(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-FIELD, and 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.

А теперь прикол! Дадим валидатору заведомо неверный файл и что мы видим в отладчике? Два новых перезапуска, CONTINUE-NEXT-FIELD и CONTINUE-NEXT-ROW. Выбор любого из них покажет, что валидация продолжается. Перезапуск ABORT должен присутствовать всегда, чтобы мы могли прекратить валидацию в любой момент.

 

Начинаем всё с начала

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 the 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!

Что произойдет теперь, если указать функции validate-csv неверный файл? Мы получим в отладчике новый перезапуск RETRY-FILE. Это значит, что мы сможем исправить ошибочную запись, сохранить файл и повторить валидацию с начала, и всё это не выходя из отладчика!

 

Обработка перезапусков

Apart from the debugger, we can also handle restarts using handler-bind and find-restart.

Можно обрабатывать перезапуски не только в отладчике, используя handler-bind и find-restart.

For example, the following function will continue validating the file as long as CSV-ERRORs are signalled and one of CONTINUE-NEXT-FIELD or CONTINUE-NEXT-ROW restarts is available. It collects those errors in a list and returns the same.

Например, следующая функция будет продолжать валидировать файл, если при возникновении ошибки CSV-ERROR доступны перезапуски CONTINUE-NEXT-FIELD или CONTINUE-NEXT-ROW. Объекты ошибок будут собраны в список, который функция возвратит на выходе.

(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.

Если мы хотим, чтобы не-программист использовал наш валидатор, мы должны обеспечить возможность загрузки файла на сервер () и предоставить в браузере красиво оформленный список list-csv-errors.

 

Заключение

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 what validate-csv does), while the higher-level functions actually get to decide what path to take (like list-csv-errors).

Что мне больше всего нравится в системе условий (condition system), так это то, что она позволяет переложить принятие решений на функции более высокого уровня. Функции низкого уровня предоставляют различные стратегии при возникновении исключительных ситуаций (как это делает validate-csv), тогда как функции высокого уровня (такие как list-csv-errors) могут выбрать подходящую для них стратегию.

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.

Если нам понадобится, чтобы функция list-csv-errors помещала в список только одну ошибку на каждую строку, то изменения в коде будут тривиальны благодяря предоставляемым перезапускам. Такое разделение логики в программе, на мой взгляд, является очень элегантным инструментом для решения подобных задач.

 

Заметки

1. http://gigamonkeys.com/book/beyond-exception-handling-conditions-and-restarts.html
2. Еще один хороший источник, статья Kent Pitman, "Condition Handling in the Lisp Language Family" -- http://www.nhplace.com/kent/Papers/Condition-Handling-2001.html
3. Я следую соглашению использовать восклицательный знак (!) в качестве префикса для имен локальных функций, объявленных с помощью FLET и LABELS. Это позволяет проще их идентифицировать в коде как локальные.