The Basic Evaluation Rule

Now to connect the FOO language to the processor interface, all you need is a function that takes an object and processes it, invoking the appropriate processor functions to generate HTML. For instance, when given a simple form like this:

  1. (:p "Foo")

this function might execute this sequence of calls on the processor:

  1. (freshline processor)
  2. (raw-string processor "<p" nil)
  3. (raw-string processor ">" nil)
  4. (raw-string processor "Foo" nil)
  5. (raw-string processor "</p>" nil)
  6. (freshline processor)

For now you can define a simple function that just checks whether a form is, in fact, a legal FOO form and, if it is, hands it off to the function process-sexp-html for processing. In the next chapter, you’ll add some bells and whistles to this function to allow it to handle macros and special operators. But for now it looks like this:

  1. (defun process (processor form)
  2.   (if (sexp-html-p form)
  3.     (process-sexp-html processor form)
  4.     (error "Malformed FOO form: ~s" form)))

The function sexp-html-p determines whether the given object is a legal FOO expression, either a self-evaluating form or a properly formatted cons.

  1. (defun sexp-html-p (form)
  2.   (or (self-evaluating-p form) (cons-form-p form)))

Self-evaluating forms are easily handled: just convert to a string with **PRINC-TO-STRING** and escape the characters in the variable *escapes*, which, as you’ll recall, is initially bound to the value of *element-escapes*. Cons forms you pass off to process-cons-sexp-html.

  1. (defun process-sexp-html (processor form)
  2.   (if (self-evaluating-p form)
  3.     (raw-string processor (escape (princ-to-string form) *escapes*) t)
  4.     (process-cons-sexp-html processor form)))

The function process-cons-sexp-html is then responsible for emitting the opening tag, any attributes, the body, and the closing tag. The main complication here is that to generate pretty HTML, you need to emit fresh lines and adjust the indentation according to the type of the element being emitted. You can categorize all the elements defined in HTML into one of three categories: block, paragraph, and inline. Block elements—such as body and ul--are emitted with fresh lines before and after both their opening and closing tags and with their contents indented one level. Paragraph elements—such as p, li, and blockquote--are emitted with a fresh line before the opening tag and after the closing tag. Inline elements are simply emitted in line. The following three parameters list the elements of each type:

  1. (defparameter *block-elements*
  2.   '(:body :colgroup :dl :fieldset :form :head :html :map :noscript :object
  3.     :ol :optgroup :pre :script :select :style :table :tbody :tfoot :thead
  4.     :tr :ul))
  6. (defparameter *paragraph-elements*
  7.   '(:area :base :blockquote :br :button :caption :col :dd :div :dt :h1
  8.     :h2 :h3 :h4 :h5 :h6 :hr :input :li :link :meta :option :p :param
  9.     :td :textarea :th :title))
  11. (defparameter *inline-elements*
  12.   '(:a :abbr :acronym :address :b :bdo :big :cite :code :del :dfn :em
  13.     :i :img :ins :kbd :label :legend :q :samp :small :span :strong :sub
  14.     :sup :tt :var))

The functions block-element-p and paragraph-element-p test whether a given tag is a member of the corresponding list.6

  1. (defun block-element-p (tag) (find tag *block-elements*))
  3. (defun paragraph-element-p (tag) (find tag *paragraph-elements*))

Two other categorizations with their own predicates are the elements that are always empty, such as br and hr, and the three elements, pre, style, and script, in which whitespace is supposed to be preserved. The former are handled specially when generating regular HTML (in other words, not XHTML) since they’re not supposed to have a closing tag. And when emitting the three tags in which whitespace is preserved, you can temporarily turn off indentation so the pretty printer doesn’t add any spaces that aren’t part of the element’s actual contents.

  1. (defparameter *empty-elements*
  2.   '(:area :base :br :col :hr :img :input :link :meta :param))
  4. (defparameter *preserve-whitespace-elements* '(:pre :script :style))
  6. (defun empty-element-p (tag) (find tag *empty-elements*))
  8. (defun preserve-whitespace-p (tag) (find tag *preserve-whitespace-elements*))

The last piece of information you need when generating HTML is whether you’re generating XHTML since that affects how you emit empty elements.

  1. (defparameter *xhtml* nil)

With all that information, you’re ready to process a cons FOO form. You use parse-cons-form to parse the list into three parts, the tag symbol, a possibly empty plist of attribute key/value pairs, and a possibly empty list of body forms. You then emit the opening tag, the body, and the closing tag with the helper functions emit-open-tag, emit-element-body, and emit-close-tag.

  1. (defun process-cons-sexp-html (processor form)
  2.   (when (string= *escapes* *attribute-escapes*)
  3.     (error "Can't use cons forms in attributes: ~a" form))
  4.   (multiple-value-bind (tag attributes body) (parse-cons-form form)
  5.     (emit-open-tag     processor tag body attributes)
  6.     (emit-element-body processor tag body)
  7.     (emit-close-tag    processor tag body)))

In emit-open-tag you have to call freshline when appropriate and then emit the attributes with emit-attributes. You need to pass the element’s body to emit-open-tag so when it’s emitting XHTML, it knows whether to finish the tag with /> or >.

  1. (defun emit-open-tag (processor tag body-p attributes)
  2.   (when (or (paragraph-element-p tag) (block-element-p tag))
  3.     (freshline processor))
  4.   (raw-string processor (format nil "<~(~a~)" tag))
  5.   (emit-attributes processor attributes)
  6.   (raw-string processor (if (and *xhtml* (not body-p)) "/>" ">")))

In emit-attributes the attribute names aren’t evaluated since they must be keyword symbols, but you should invoke the top-level process function to evaluate the attribute values, binding *escapes* to *attribute-escapes*. As a convenience for specifying boolean attributes, whose value should be the name of the attribute, if the value is **T**--not just any true value but actually **T**--then you replace the value with the name of the attribute.7

  1. (defun emit-attributes (processor attributes)
  2.   (loop for (k v) on attributes by #'cddr do
  3.        (raw-string processor (format nil " ~(~a~)='" k))
  4.        (let ((*escapes* *attribute-escapes*))
  5.          (process processor (if (eql v t) (string-downcase k) v)))
  6.        (raw-string processor "'")))

Emitting the element’s body is similar to emitting the attribute values: you can loop through the body calling process to evaluate each form. The rest of the code is dedicated to emitting fresh lines and adjusting the indentation as appropriate for the type of element.

  1. (defun emit-element-body (processor tag body)
  2.   (when (block-element-p tag)
  3.     (freshline processor)
  4.     (indent processor))
  5.   (when (preserve-whitespace-p tag) (toggle-indenting processor))
  6.   (dolist (item body)  (process processor item))
  7.   (when (preserve-whitespace-p tag) (toggle-indenting processor))
  8.   (when (block-element-p tag)
  9.     (unindent processor)
  10.     (freshline processor)))

Finally, emit-close-tag, as you’d probably expect, emits the closing tag (unless no closing tag is necessary, such as when the body is empty and you’re either emitting XHTML or the element is one of the special empty elements). Regardless of whether you actually emit a close tag, you need to emit a final fresh line for block and paragraph elements.

  1. (defun emit-close-tag (processor tag body-p)
  2.   (unless (and (or *xhtml* (empty-element-p tag)) (not body-p))
  3.     (raw-string processor (format nil "</~(~a~)>" tag)))
  4.   (when (or (paragraph-element-p tag) (block-element-p tag))
  5.     (freshline processor)))

The function process is the basic FOO interpreter. To make it a bit easier to use, you can define a function, emit-html, that invokes process, passing it an html-pretty-printer and a form to evaluate. You can define and use a helper function, get-pretty-printer, to get the pretty printer, which returns the current value of *html-pretty-printer* if it’s bound; otherwise, it makes a new instance of html-pretty-printer with *html-output* as its output stream.

  1. (defun emit-html (sexp) (process (get-pretty-printer) sexp))
  3. (defun get-pretty-printer ()
  4.   (or *html-pretty-printer*
  5.       (make-instance 
  6.        'html-pretty-printer
  7.        :printer (make-instance 'indenting-printer :out *html-output*))))

With this function, you can emit HTML to *html-output*. Rather than expose the variable *html-output* as part of FOO’s public API, you should define a macro, with-html-output, that takes care of binding the stream for you. It also lets you specify whether you want pretty HTML output, defaulting to the value of the variable *pretty*.

  1. (defmacro with-html-output ((stream &key (pretty *pretty*)) &body body)
  2.   `(let* ((*html-output* ,stream)
  3.           (*pretty* ,pretty))
  4.     ,@body))

So, if you wanted to use emit-html to generate HTML to a file, you could write the following:

  1. (with-open-file (out "foo.html" :direction output)
  2.   (with-html-output (out :pretty t)
  3.     (emit-html *some-foo-expression*)))