HTML-TEMPLATE - Use HTML templates from Common Lisp

Abstract
HTML-TEMPLATE is a portable library for Common Lisp which can be used to fill templates with arbitrary (string) values at runtime. (Actually, it doesn't matter whether the result is HTML. It's just very likely that this will be what the library is mostly used for.)
It is loosely modeled after the Perl module HTML::Template and partially compatible with a its syntax, though both libraries contain some extensions that the other does not support.
HTML-TEMPLATE translates templates into efficient closures which can be re-used as often as needed. It uses an intelligent cache mechanism so you can nevertheless update templates while your program is running and have the changes take effect immediately.
The rationale behind something like HTML-TEMPLATE or HTML::Template is that you want to separate code and layout (I think in Newspeak these are called the "Business Layer" and the "Presentation Layer") as much as possible when generating HTML, especially if you work with graphical artists who are responsible for the visual appearance of your site but aren't programmers. Matter of fact, you can't separate code and layout completely. I've worked (or had to work) with several different approaches over the years, including emitting HTML from CGI scripts directly, using tools like Embperl, Mason, PHP (yuk!), or Java/XML/XLST stuff, or employing different Lisp markup languages but found that HTML::Template's approach usually works best for me: The graphical designers only need to learn a minimal set of new tags and can update their templates independently from the work done on the backend. It is simple and it just works. YMMV, of course...
HTML-TEMPLATE is intended to be portable and should work with all conforming Common Lisp implementations but is mainly tested and deployed with LispWorks. Let us know if you encounter any problems.
It comes with a BSD-style license so you can basically do with it whatever you want.
HTML-TEMPLATE is used by Planet Lisp, Cleartrip, Booble, and Heike Stephan.
Download shortcut: http://weitz.de/files/html-template.tar.gz.

Simple example
Download and installation
Support and mailing lists
Syntax
Semantics
The HTML-TEMPLATE dictionary
Acknowledgements

Simple example

Although there's a wealth of functions, special variables, condition types, and restarts listed below, most of the time you'll just have to deal with one function and the syntax of the templates should be quite easy to grasp. Here's a small example.

If you have a text file #p"/tmp/foo.tmpl" like this

<table border=1>
  <!-- TMPL_LOOP rows -->
    <tr>
      <!-- TMPL_LOOP cols -->
        <!-- TMPL_IF colorful-style -->
          <td align="right" bgcolor="pink"><!-- TMPL_VAR content --></td>
        <!-- TMPL_ELSE -->
          <td align="right" ><!-- TMPL_VAR content --></td>
        <!-- /TMPL_IF -->
      <!-- /TMPL_LOOP -->
    </tr>
  <!-- /TMPL_LOOP -->
</table>

then the following code

(let* ((rows (loop for i below 49 by 7
                   collect (list :cols
                                 (loop for j from i below (+ i 7)
                                       for string = (format nil "~R" j)
                                       collect (list :content string
                                                     :colorful-style (oddp j))))))
       (values (list :rows rows)))
  (fill-and-print-template #p"/tmp/foo.tmpl" values))

will produce this HTML table:

zero one two three four five six

seven eight nine ten eleven twelve thirteen

fourteen fifteen sixteen seventeen eighteen nineteen twenty

twenty-one twenty-two twenty-three twenty-four twenty-five twenty-six twenty-seven

twenty-eight twenty-nine thirty thirty-one thirty-two thirty-three thirty-four

thirty-five thirty-six thirty-seven thirty-eight thirty-nine forty forty-one

forty-two forty-three forty-four forty-five forty-six forty-seven forty-eight

Download and installation

HTML-TEMPLATE together with this documentation can be downloaded from http://weitz.de/files/html-template.tar.gz. The current version is 0.9.1.

If you're on Debian you should probably use the cl-html-template Debian package which is available thanks to Peter van Eynde and Kevin Rosenberg. There's also a port for Gentoo Linux thanks to Matthew Kennedy.

HTML-TEMPLATE comes with simple system definitions for MK:DEFSYSTEM and ASDF so you can either adapt it to your needs or just unpack the archive and from within the HTML-TEMPLATE directory start your Lisp image and evaluate the form (mk:compile-system "html-template") (or the equivalent one for asdf) which should compile and load the whole system. Installation via asdf-install should also be possible.

If for some reason you don't want to use MK:DEFSYSTEM or asdf you can just LOAD the file load.lisp or you can also get away with something like this:

(loop for name in '("packages" "specials" "errors" "util" "template" "api")
      do (compile-file (make-pathname :name name
                                      :type "lisp"))
         (load name))

Note that on CL implementations which use the Python compiler (i.e. CMUCL, SBCL, SCL) you can concatenate the compiled object files to create one single object file which you can load afterwards:

cat {packages,specials,errors,util,template,api}.x86f > html-template.x86f

(Replace ".x86f" with the correct suffix for your platform.)

The distribution includes a test file "test.lisp" which you can LOAD after loading HTML-TEMPLATE itself to check if everything works as intended. If all is well you should just see these two messages:

Please wait a couple of seconds.
All tests passed...

Some of the tests assume the existence of a directory #p"/tmp/" where you can create files. If you're on Windows you should probably change this - see the variable TMP-DIR in test.lisp.

Note that there is no public CVS repository for HTML-TEMPLATE - the repository at common-lisp.net is out of date and not in sync with the (current) version distributed from weitz.de.

Luís Oliveira maintains a darcs repository of HTML-TEMPLATE at http://common-lisp.net/~loliveira/ediware/.

Support and mailing lists

For questions, bug reports, feature requests, improvements, or patches please use the html-template-devel mailing list. If you want to be notified about future releases subscribe to the html-template-announce mailing list. These mailing lists were made available thanks to the services of common-lisp.net.

If you want to send patches, please read this first.

Syntax

A template is just ordinary text (a file or a string) interspersed with template tags. A template tag looks like

  <!-- name [attribute] -->

where name is one of TMPL_VAR, TMPL_LOOP, TMPL_REPEAT, TMPL_CALL, TMPL_IF, TMPL_UNLESS, TMPL_INCLUDE, /TMPL_LOOP, /TMPL_REPEAT, /TMPL_IF, /TMPL_UNLESS, or TMPL_ELSE. Case doesn't matter, i.e. tmpl_var or Tmpl_Var would also be legal names.

If name is one of the first seven listed above then attribute must follow, otherwise it must not follow where attribute is any sequence of characters delimited by ", ', or by whitespace. There's currently no way to escape the delimiters, i.e. if the attribute starts with " then the next " (and nothing else) will end it.

Any amount (including the empty string) of whitespace directly after '' is optional and will be ignored. However, at least one whitespace character between name and attribute (if present) is mandatory. But note that if attribute is not delimited by " or ' then there must be whitespace to separate attribute from the closing '-->'.

The following are examples for legal template tags

  <!-- TMPL_VAR foo -->
  <!--TMPL_LOOP 'foo'-->
  <!-- tmpl_include "/tmp/foo.html" -->
  <!-- Tmpl_Else -->
  <!-- /TMPL_LOOP -->
  <!-- TMPL_LOOP foo--><!-- -->

But note that in the last example the attribute is 'foo--><!--' which is probably not what you expected...

These are not legal:

  <!-- TMPL_VAR -->
  <!-- Tmpl_Else baz -->
  <!-- TMPL_VARfoo -->
  <!--TMPL_LOOP 'foo\'bar'-->
  <tmpl_include "/tmp/foo.html">
  <!-- TMPL_VAR NAME="foo" -->

TMPL_VAR must always be followed by an attribute (1st example) while TMPL_ELSE must not (2nd example). The third one isn't recognized as a template tag because of the missing whitespace behind TMPL_VAR. The tag will simply be ignored and the parser will look for the next occurence of '<!--'.

The fourth example doesn't work because the second apostrophe isn't escaped by the backslash as you might have thought. Instead, the parser will think the attribute ends there and will complain about the string "bar'" following it. The next example fails because, other than with HTML::Template, the HTML comment markers are mandatory. (But note that you can change that by setting the variables *TEMPLATE-START-MARKER* and *TEMPLATE-END-MARKER*.) The last example uses HTML::Template's optional "NAME=" notation which is not supported by HTML-TEMPLATE.

The TMPL_VAR, TMPL_INCLUDE, and TMPL_CALL tags can appear anywhere and as often as you like in your templates while the other tags must obey certain rules - they must follow one of these patterns

  <!-- TMPL_IF attribute --> text <!-- /TMPL_IF -->
  <!-- TMPL_IF attribute --> text <!-- TMPL_ELSE --> text' <!-- /TMPL_IF -->
  <!-- TMPL_LOOP attribute --> text <!-- /TMPL_LOOP -->
  <!-- TMPL_REPEAT attribute --> text <!-- /TMPL_REPEAT -->

where text and text' themselves must be valid templates. In other words: These constructs must nest properly.

Note that, despite of its name, HTML-TEMPLATE knows absolutely nothing about HTML syntax so you can use it for other texts as well. Also, because the templates are filled in before they're sent to the browser, you can use template tags anywhere you like and not only in places where HTML comments would be legal. These two examples, e.g., will work:

  <!-- Start of comment <!-- TMPL_VAR foo --> End of comment -->
  <A HREF="<!-- TMPL_VAR link -->">foobar</A>

Semantics

The generic function CREATE-TEMPLATE-PRINTER will convert a template into a template printer. A template printer is a function which accepts one argument - a template structure - which describes how the template should be filled and prints the filled template to the stream bound to the internal variable *TEMPLATE-OUTPUT*. You can FUNCALL a template printer, but the preferred way to use it is to invoke it with FILL-AND-PRINT-TEMPLATE (which can also create template printers as needed). Note that template printers are compiled closures but although you'll usually create them at runtime the Lisp compiler isn't invoked for this task so you can safely excise it from your image if you so wish.

For the rest of this document we will make a distinction between generation time which is the time the template printer is created (either explicitly by CREATE-TEMPLATE-PRINTER or implicitly by FILL-AND-PRINT-TEMPLATE) and invocation time which is the time the printer is used (by FUNCALL or FILL-AND-PRINT-TEMPLATE) to fill and print a template.

Each of the template tags TMPL_VAR, TMPL_IF, TMPL_UNLESS, TMPL_LOOP, TMPL_CALL, and TMPL_REPEAT is associated with a particular symbol at generation time. This symbol is the result of INTERNing the tag's attribute string into the package *TEMPLATE-SYMBOL-PACKAGE*. The template structure - the argument given to the template printer - associates these symbols with values. By default this is done by means of a property list but this can be changed at template invocation time by changing the contents of the variable *VALUE-ACCESS-FUNCTION*. (Note that the name structure doesn't imply that template structures are structures in the sense of Common Lisp. Usually they aren't.)

The template tags work as follows:

This tag will be replaced by the value associated with symbol which should be (see *FORMAT-NON-STRINGS*) a string (or maybe NIL - see *CONVERT-NIL-TO-EMPTY-STRING*). *STRING-MODIFIER* is applied to the string before it is output.
* (let ((tp (create-template-printer "Hello !")))
    (fill-and-print-template tp '(:foo "World"))
    (terpri)
    (fill-and-print-template tp '(:foo "Folks"))
    (terpri)
    (fill-and-print-template tp '(:foo symbol)))
Hello World!
Hello Folks!
Hello SYMBOL!

text
text

In the first case, if the value associated with symbol is not NIL the (sub-)template text will be filled and printed. Otherwise, the whole construct will be replaced by an empty string. In the second case, it's the other way around.
* (let ((tp (create-template-printer "The quick brown fox")))
    (fill-and-print-template tp '(:fast t))
    (terpri)
    (fill-and-print-template tp '(:fast nil)))
The quick brown fox
The brown fox

texttext'
texttext'

In the first case, if the value associated with symbol is not NIL, the (sub-)template text will be filled and printed. Otherwise, text' is used instead. In the second case, it's the other way around.
* (let ((tp (create-template-printer "The quickslow brown fox")))
    (fill-and-print-template tp '(:fast t))
    (terpri)
    (fill-and-print-template tp '(:fast nil)))
The quick brown fox
The slow brown fox

text

The value associated with symbol should be a sequence (see *SEQUENCES-ARE-LISTS*) of template structures. For each element of this sequence the (sub-)template text is filled and printed using the corresponding template structure.
Note that each template (sub-)structure which is used to fill text introduces a new set of associations between symbols and their values. While the template printer is within text the outer template structure is temporarily "forgotten" unless *VALUE-ACCESS-FUNCTION* (note the in-loop-p paramter in particular) takes care of that.
* (defparameter *tp*
    (create-template-printer
     "[,]"))

*TP*
* (fill-and-print-template *tp*
                           '(:foo ((:bar "EINS" :baz "ONE")
                                   (:bar "ZWEI" :baz "TWO"))))
[EINS,ONE][ZWEI,TWO]
* (let ((*value-access-function*
         (lambda (symbol values &optional in-loop-p)
           (declare (ignore in-loop-p))
           (getf values symbol))))
    (fill-and-print-template *tp* '(:baz "ONE"
                                    :foo ((:bar "EINS")
                                          (:bar "UNO")))))
[EINS,][UNO,]
* (fill-and-print-template *tp* '(:baz "ONE"
                                  :foo ((:bar "EINS")
                                        (:bar "UNO"))))
[EINS,ONE][UNO,ONE]

text

If the value associated with symbol is a positive integer N, then the (sub-)template text will be filled and printed N times. Otherwise, the whole construct will be replace with an empty string.
* (let ((tp (create-template-printer "The very fast brown fox")))
    (fill-and-print-template tp '(:three 3))
    (terpri)
    (fill-and-print-template tp '(:three "3")))
The very very very fast brown fox
The fast brown fox
Note that the original HTML::Template library doesn't have the TMPL_REPEAT tag - if that matters to you.

The string pathname should be a valid pathname for an existing textfile. This textfile is implicitly converted into a template printer at generation time as if it were explicitly converted by a call to CREATE-TEMPLATE-PRINTER. At invocation time the tag will be replaced by the result of FUNCALLing this template printer with the current template structure. (Note that this implies that the included file has to be a valid template, i.e. you can't, say, have a TMPL_IF tag in your main file and put the closing /TMPL_IF into the included file.)
* (with-open-file (s "/tmp/foo" :direction :output :if-exists :supersede)
    (write-string "The quick brown fox" s))
"The quick brown fox"
* (fill-and-print-template " jumps over the lazy dog" '(:fast t))
Warning:  New template printer for #p"/tmp/foo" created
The quick brown fox jumps over the lazy dog
* (fill-and-print-template " jumps over the lazy dog" '(:fast nil))
The brown fox jumps over the lazy dog
These tags can be nested, i.e. included files can themselves include other files. Included template printers are always taken from the cache at invocation time which means you can update them seperately from the including printer.

The value associated with symbol should be a sequence (as specified by *SEQUENCES-ARE-LISTS*) of template calls, each of which specifies a substructure and a template to apply to that. By default, calls are just lists, with the car specifying the template name and the cdr containing the substructure. (See *CALL-TEMPLATE-ACCESS-FUNCTION* and *CALL-VALUE-ACCESS-FUNCTION* for ways to customize what calls look like.)
TMPL_CALL combines aspects of TMPL_LOOP and TMPL_INCLUDE - it iterates over a sequence of values the way loops do, but instead of using part of the current template to print the values each value contains its own information about which subtemplate should be applied to it.
* (with-open-file (s "/tmp/paragraph" :direction :output :if-exists :supersede)
    (write-string "<p class='fancy'></p>" s))
"<p class='fancy'></p>"
* (with-open-file (s "/tmp/header" :direction :output :if-exists :supersede)
    (write-string "<h1></h1>" s))
"<h1></h1>"
* (fill-and-print-template "<body></body>"
                           '(:parts ((#P"/tmp/header" :text "Chapter 1")
                                     (#P"/tmp/paragraph" :text "There once was a platypus...")
                                     (#P"/tmp/header" :text "Chapter 5")
                                     (#P"/tmp/paragraph" :text "And lived happily ever after."))))
<h1>Chapter 1</h1><p class='fancy'>There once was a platypus...</p><h1>Chapter 5</h1><p class='fancy'>And lived happily ever after.</p></body>
Note that you do not have to include full pathnames in the call structures. You can use *DEFAULT-TEMPLATE-PATHNAME* to specify most of it, or set *CALL-TEMPLATE-ACCESS-FUNCTION* to a function that creates pathnames any way you like.

Also note that the original HTML::Template library doesn't have the TMPL_CALL tag - if that matters to you.

The HTML-TEMPLATE dictionary

HTML-TEMPLATE exports the following symbols (some of which are also exported by CL-WHO, by the way, so beware if you're using both libraries):

Creating and using template printers

If you're OK with the default settings you will probably only use the two functions described in this section.

[Generic function]
create-template-printer template &key force element-type if-does-not-exist external-format => printer

This function will create and return a template printer printer created from the template denoted by template. The behaviour of this function depends on the type of template.

If template is a stream, it should be an open character input stream which is read character by character with READ-CHAR and the resulting text is used as the template.
If template is a string, it is converted into a string stream which is again fed into CREATE-TEMPLATE-PRINTER.
If template is a pathname, it should denote an existing text file. The file is opened by WITH-OPEN-FILE and the resulting stream is again fed into CREATE-TEMPLATE-PRINTER. All keyword arguments except force are used as keyword arguments for WITH-OPEN-FILE. The pathname will be merged with *DEFAULT-TEMPLATE-PATHNAME* before it is used.
HTML-TEMPLATE maintains a cache of previously created template printers. If the (merged) pathname can be found in this cache and the file denoted by this pathname hasn't changed since the associated cached template printer was created (which is tested by FILE-WRITE-DATE) the cached value will be used and no new template printer will be created. This can be overriden by the keyword argument force, i.e. when force is true a new template printer will unconditionally be created (and cached unless force is the keyword :DO-NOT-CACHE). The default value for force is the value of *FORCE-DEFAULT*. (See also *NO-CACHE-CHECK*.) Note that you may have to use force if you've changed one of the customization variables described below and want to create a template printer based on these new settings although the template file itself hasn't changed. Also note that FILE-WRITE-DATE might not be able to see a difference if the newer version of a file is only fractions of a second newer than the older one.
This function will signal an error of type TEMPLATE-INVOCATION-ERROR if template is not a pathname and one of the keyword arguments is provided.
* (with-input-from-string (stream "The  brown fox")
    (funcall (create-template-printer stream) '(:speed "quick")))
The quick brown fox
* (funcall (create-template-printer "The  brown fox") '(:speed "slow"))
The slow brown fox
* (with-open-file (stream "/tmp/foo.tmpl" :direction :output)
    (write-string "The  brown fox" stream))

"The  brown fox"
* (funcall (create-template-printer #p"/tmp/foo.tmpl") '(:speed "fast"))
Warning:  New template printer for #p"/tmp/foo.tmpl" created
The fast brown fox
* (funcall (create-template-printer #p"/tmp/foo.tmpl") '(:speed "extremely fast"))
The extremely fast brown fox
* (funcall (create-template-printer #p"/tmp/foo.tmpl" :force t) '(:speed "very fast"))
Warning:  New template printer for #p"/tmp/foo.tmpl" created
The very fast brown fox
* (probe-file "/tmp/bar.tmpl")

NIL
* (funcall (create-template-printer #p"/tmp/bar.tmpl" :if-does-not-exist :create) '(:foo "foo"))
Warning:  New template printer for #p"/tmp/bar.tmpl" created

* (probe-file "/tmp/bar.tmpl")

#p"/tmp/bar.tmpl"

[Generic function]
fill-and-print-template template/printer values &key stream &allow-other-keys => |

This function will fill the template denoted by template/printer with the values provided by values and print the resulting text to stream which defaults to *DEFAULT-TEMPLATE-OUTPUT*. The value of values should be a template structure matching the current value of *VALUE-ACCESS-FUNCTION*.
If template/printer is a function, it will be used as if it were a template printer. Otherwise, template/printer will first be fed into CREATE-TEMPLATE-PRINTER and the resulting template printer will be used. Note that this implies that the caching mechanism described above is in effect here as well.
If template/printer is a pathname, all keyword arguments except for stream will be used as keyword arguments for CREATE-TEMPLATE-PRINTER. If it is not a pathname, keyword arguments other than stream will result in an error of type TEMPLATE-INVOCATION-ERROR.
* (fill-and-print-template "The  brown fox" '(:speed "slow"))
The slow brown fox
* (with-input-from-string (stream "The  brown fox")
    (fill-and-print-template stream '(:speed "quick")))
The quick brown fox
* (with-open-file (stream "/tmp/foo.tmpl" :direction :output :if-exists :supersede)
    (write-string "The  brown fox" stream))

"The  brown fox"
* (fill-and-print-template #p"/tmp/foo.tmpl" '(:speed "fast"))
Warning:  New template printer for #p"/tmp/foo.tmpl" created
The fast brown fox
* (fill-and-print-template #p"/tmp/foo.tmpl" '(:speed "very fast"))
The very fast brown fox
* (let ((tp (create-template-printer "The  brown fox")))
    (fill-and-print-template tp '(:speed "tardy")))
The tardy brown fox

Template cache

The functions and variables in this section are related to the cache mechanism described in the entry for CREATE-TEMPLATE-PRINTER.

[Function]
clear-template-cache => |

This function will completely clear the cache used by HTML-TEMPLATE.

[Function]
delete-from-template-cache pathname => result

This function will remove the template printer associated with pathname from HTML-TEMPLATE's cache. result is true if there was such a template printer, or NIL otherwise.

[Special variable]
*no-cache-check*

If the value of this variable is true (the default is NIL) CREATE-TEMPLATE-PRINTER and FILL-AND-PRINT-TEMPLATE won't check whether a template file has changed since it has been cached, but instead will always use the cached template printer if there is one, i.e. there will be no more disk I/O once all template printers are generated. This option is intended to be used for sites with heavy traffic when you don't expect your templates to change anymore.

Customizations

This section assembles more than a dozen special variables which can be used to customize HTML-TEMPLATE's behaviour.

[Special variable]
*template-start-marker*

This should be a string (the default is "<!--") which is used at generation time to determine the start of a template tag.

[Special variable]
*template-end-marker*

This should be a string (the default is "-->") which is used at generation time to determine the end of a template tag.
* (let ((*template-start-marker* "<")
        (*template-end-marker* ">"))
    (fill-and-print-template "The <TMPL_VAR 'speed'> <brown> fox" '(:speed "quick")))
The quick <brown> fox

[Special variable]
*default-template-pathname*

This should be a pathname (the default is the result of calling MAKE-PATHNAME with no arguments) which is merged with the sole argument of CREATE-TEMPLATE-PRINTER if this argument is a pathname.
* (with-open-file (stream "/tmp/foo.tmpl" :direction :output :if-exists :supersede)
    (write-string "The  brown fox" stream))

"The  brown fox"
* (setq *default-template-pathname* #p"/tmp/")

#p"/tmp/"
* (fill-and-print-template #p"foo.tmpl" '(:speed "very fast"))
Warning:  New template printer for #p"/tmp/foo.tmpl" created
The very fast brown fox

[Special variable]
*default-template-output*

This should be a stream (the default is the value of *STANDARD-OUTPUT* when HTML-TEMPLATE is loaded) which is used as the output stream of FILL-AND-PRINT-TEMPLATE if no stream keyword argument was provided.
* (fill-and-print-template "The  brown fox" '(:speed "slow"))
The slow brown fox
* (with-output-to-string (*default-template-output*)
    (fill-and-print-template "The  brown fox" '(:speed "slow")))

"The slow brown fox"

[Special variable]
*convert-nil-to-empty-string*

If the values of this variable is true (which is the default), TMPL_VAR tags will be replaced by the empty string if the associated value is NIL, otherwise an error of type TEMPLATE-MISSING-VALUE-ERROR is signaled. This variable takes effect at invocation time.
* (let ((tp (create-template-printer "The  brown fox")))
    (handler-bind
      ((template-missing-value-error (lambda (condition)
                                       (declare (ignore condition))
                                       (use-value "slow"))))
      (let ((*convert-nil-to-empty-string* nil))
        (fill-and-print-template tp '(:foo "bar")))))
The slow brown fox

[Special variable]
*format-non-strings*

If the value of this variable is true (which is the default), TMPL_VAR will accept non-string values and convert them to strings using (FORMAT NIL "~A" ...). Note that the check for *CONVERT-NIL-TO-EMPTY-STRING* will happen first, though. This variable takes effect at invocation time.
* (fill-and-print-template "The  brown fox" '(:speed :tardy))
The TARDY brown fox

[Special variable]
*sequences-are-lists*

If the values of this variable is true (which is the default) the code generated by a TMPL_LOOP tag expects its associated value to be a list, otherwise it expects it to be a vector. This variable takes effect at generation time.

* (fill-and-print-template "<!-- TMPL_LOOP list -->[<!-- TMPL_VAR item -->]<!-- /TMPL_LOOP -->"
                           '(:list ((:item "1")
                                    (:item "2")
                                    (:item "3"))))
[1][2][3]
* (let ((*sequences-are-lists* nil))
    (fill-and-print-template "<!-- TMPL_LOOP vector -->[<!-- TMPL_VAR item -->]<!-- /TMPL_LOOP -->"
                             '(:vector #((:item "1")
                                         (:item "2")
                                         (:item "3")))))
[1][2][3]

[Special variable]
*upcase-attribute-strings*

If the values of this variable is true (which is the default) attribute strings are fed to STRING-UPCASE before they are interned. This variable takes effect at generation time.
* (let ((*upcase-attribute-strings* nil))
    (fill-and-print-template "The  brown fox" '(:speed "quick" :|speed| "slow")))
The slow brown fox

[Special variable]
*string-modifier*

A designator for the function which is applied to strings which replace TMPL_VAR tags. The default is #'ESCAPE-STRING-ISO-8859-1. Use #'CL:IDENTITY if you want to leave the string as is.
* (fill-and-print-template "The  brown fox" '(:speed "<quick>"))
The &lt;quick&gt; brown fox

* (let ((*string-modifier* #'identity))
    (fill-and-print-template "The  brown fox" '(:speed "<quick>")))
The <quick> brown fox

[Special variable]
*template-symbol-package*

The value of this variable should be a package designator designating the package attribute strings are interned into. The default is the KEYWORD package. This variable takes effect at generation time.
* *package*

#<The COMMON-LISP-USER package, 20/21 internal, 0/9 external>
* (let ((*template-symbol-package* (find-package :common-lisp-user)))
    (fill-and-print-template "The  brown fox" '(:speed "quick" speed "slow")))
The slow brown fox

[Special variable]
*force-default*

The default value for the force keyword argument to CREATE-TEMPLATE-PRINTER. Its initial value is NIL.

[Special variable]
*value-access-function*

The value of this variable should be a designator for a function with the lambda list (symbol values &optional in-loop-p) which is used to associate symbols with their values when a template printer is invoked. in-loop-p is true whenever this function is called from within a TMPL_LOOP or TMPL_CALL tag.

The default value is

(lambda (symbol values &optional in-loop-p)
  (let ((result (getf values symbol)))
    (cond (in-loop-p
           (loop for element in result
                 when (listp element)
                   ;; keep values from upper levels
                   collect (append element values)
                 else
                   collect element))
          (t result))))

This variable takes effect at invocation time.

* (let ((tp (create-template-printer "The <!-- TMPL_VAR speed --> brown fox"))
        ;; for brevity, we'll ignore the third argument here
        (*value-access-function* #'gethash)
        (hash (make-hash-table :test #'eq)))
    (setf (gethash :speed hash) "fast")
    (fill-and-print-template tp hash))
The fast brown fox

[Special variable]
*call-template-access-function*

The value of this variable should be a designator for a function which takes one argument (the call structure) and returns either a template printer or a value that can be used as the first argument to create-template-printer. This function will be used to determine the template that should be used for a call in a TMPL_CALL tag.
The default value is #'CAR. This variable takes effect at invocation time.

[Special variable]
*call-value-access-function*

The value of this variable should be a designator for a function which takes one argument (the call structure) and returns a structure to use as the value for a call in a TMPL_CALL tag.
The default value is #'CDR. This variable takes effect at invocation time.

[Special variable]
*ignore-empty-lines*

If the value of this variable is true (the default is NIL), template printers will suppress any whitespace in front of template tags up to (but excluding) the first #\Newline and any whitespace behind template tags up to (and including) the first #\Newline. This holds for all tags except TMPL_VAR. The idea is that you might want to put tags like TMPL_LOOP on lines of their own in order to increase the legibility of your template files without creating unnecessary empty lines in your output. This variable takes effect at generation time.
* (with-open-file (s "/tmp/foo.tmpl" :direction :input)
    (loop for line = (read-line s nil nil)
          while line
          do (print line))
    (values))

"<table>"
"  "
"  <tr>"
"    "
"    <td></td>"
"    "
"  </tr>"
"  "
"</table>"
* (let ((values (list :row-loop
                      (loop for row in '((1 2 3 4) (2 3 4 5) (3 4 5 6))
                            collect (list :col-loop
                                          (loop for col in row
                                                collect (list :item
                                                              (format nil "~A" col)))))))
      (*ignore-empty-lines* t))
  (fill-and-print-template #p"/tmp/foo.tmpl" values :force t))
Warning:  New template printer for #p"/tmp/foo.tmpl" created
<table>
  <tr>
    <td>1</td>
    <td>2</td>
    <td>3</td>
    <td>4</td>
  </tr>
  <tr>
    <td>2</td>
    <td>3</td>
    <td>4</td>
    <td>5</td>
  </tr>
  <tr>
    <td>3</td>
    <td>4</td>
    <td>5</td>
    <td>6</td>
  </tr>
</table>

[Special variable]
*warn-on-creation*

If this variable is true (which is the default), CREATE-TEMPLATE-PRINTER will warn you whenever a template printer is newly created from a pathname argument instead of being taken from the cache.

Conditions

This section lists the conditions signaled by HTML-TEMPLATE and the corresponding accessors.

[Condition type]
template-error

Every error signaled by HTML-TEMPLATE is of type TEMPLATE-ERROR. This is a direct subtype of SIMPLE-ERROR without any additional slots or options.

[Condition type]
template-invocation-error

Errors of type TEMPLATE-INVOCATION-ERROR are signaled if CREATE-TEMPLATE-PRINTER or FILL-AND-PRINT-TEMPLATE are called with wrong keyword arguments. This is a direct subtype of TEMPLATE-ERROR without any additional slots or options.

[Condition type]
template-missing-value-error

An error of type TEMPLATE-MISSING-VALUE-ERROR is signaled if a template printer for TMPL_VAR is provided with a NIL value although *CONVERT-NIL-TO-EMPTY-STRING* is false. This is a direct subtype of TEMPLATE-ERROR without any additional slots or options. Whenever a TEMPLATE-MISSING-VALUE-ERROR is signaled, an associated USE-VALUE restart is available.

[Condition type]
template-not-a-string-error

An error of type TEMPLATE-NOT-A-STRING-ERROR is signaled if a template printer for TMPL_VAR is provided with a value which is neither a string nor NIL and *FORMAT-NON-STRINGS* is false. This is a direct subtype of TEMPLATE-ERROR with one additional slot for the value which can be read by TEMPLATE-NOT-A-STRING-ERROR-VALUE. Whenever a TEMPLATE-NOT-A-STRING-ERROR is signaled, an associated USE-VALUE restart is available.

[Generic function]
template-not-a-string-error-value condition => value

If condition is a condition of type TEMPLATE-NOT-A-STRING-ERROR, this function will return the (non-string) value causing the error.

* (let ((tp (create-template-printer "A square has <!-- TMPL_VAR number --> corners")))
    (handler-bind
      ((template-not-a-string-error (lambda (condition)
                                      (use-value
                                        (format nil "~R"
                                                (template-not-a-string-error-value condition))))))
      (let ((*format-non-strings* nil))
        (fill-and-print-template tp '(:number 4)))))
A square has four corners

[Condition type]
template-syntax-error

An error of type TEMPLATE-SYNTAX-ERROR is signaled at generation time when HTML-TEMPLATE is not able to create a template printer due to syntax errors in the template. This is a direct subtype of TEMPLATE-ERROR with three additional slots. These denote the stream from which HTML-TEMPLATE was reading when it encountered the error and a line and column within this stream. (See the next three entries on how to access these slots.)
As many syntax errors can't be detected before the parser is at the end of the stream, the row and column usually denote the last position where the parser was happy and not the position where it gave up.
* (handler-case
    (fill-and-print-template "A square has  corners"
                             '(:number "four"))
    (template-syntax-error (condition)
      (format t "Houston, we've got a problem on stream ~A:~%~
                 Looks like something went wrong after line ~A, column ~A.~%~
                 The last message we received was '~?'."
              (template-syntax-error-stream condition)
              (template-syntax-error-line condition)
              (template-syntax-error-col condition)
              (simple-condition-format-control condition)
              (simple-condition-format-arguments condition))
      (values)))
Houston, we've got a problem on stream #<String-Input Stream>:
Looks like something went wrong after line 1, column 26.
The last message we received was 'Unexpected EOF'.
Note that column 26 is the position directly behind "TMPL_VAR".

[Generic function]
template-syntax-error-stream condition => stream

If condition is a condition of type TEMPLATE-SYNTAX-ERROR, this function will return the stream the parser was reading from when the error was encountered.

[Generic function]
template-syntax-error-line condition => number

If condition is a condition of type TEMPLATE-SYNTAX-ERROR, this function will return the line number which was associated with this error. As in Emacs, lines are counted beginning with 1. HTML-TEMPLATE increases the line counter whenever it reads a #\Newline from its input stream.

[Generic function]
template-syntax-error-col condition => number

If condition is a condition of type TEMPLATE-SYNTAX-ERROR, this function will return the column number which was associated with this error. As in Emacs, columns are counted beginning with 0.

Escaping

Functions and variables which can be used to encode characters for HTML documents - see *STRING-MODIFIER*.

[Function]
escape-string string &key test => escaped-string

This function will accept a string string and will replace every character for which test returns true with its (decimal) character entity. test must be a designator for a function of one argument which accepts a character and returns a generalized boolean. The default is the value of *ESCAPE-CHAR-P*.
* (escape-string "<Hühner> 'naïve'")
"&lt;H&#252;hner&gt; &#039;na&#239;ve&#039;"

[Special variable]
*escape-char-p*

This is the default for the test keyword argument to ESCAPE-STRING. Its initial value is
#'(lambda (char)
    (or (find char "<>&'\"")
        (> (char-code char) 127)))

[Function]
escape-string-minimal string => escaped-string
[Function]
escape-string-minimal-plus-quotes string => escaped-string
[Function]
escape-string-iso-8859-1 string => escaped-string
[Function]
escape-string-all string => escaped-string

These are convenience function based on ESCAPE-STRING. They are defined as follows:

(defun escape-string-minimal (string)
  "Escape only #\<, #\>, and #\& in STRING."
  (escape-string string :test #'(lambda (char) (find char "<>&"))))

(defun escape-string-minimal-plus-quotes (string)
  "Like ESCAPE-STRING-MINIMAL but also escapes quotes."
  (escape-string string :test #'(lambda (char) (find char "<>&'\""))))

(defun escape-string-iso-8859-1 (string)
  "Escapes all characters in STRING which aren't defined in ISO-8859-1."
  (escape-string string :test #'(lambda (char)
                                  (or (find char "<>&'\"")
                                      (> (char-code char) 255)))))

(defun escape-string-all (string)
  "Escapes all characters in STRING which aren't in the 7-bit ASCII
character set."
  (escape-string string :test #'(lambda (char)
                                  (or (find char "<>&'\"")
                                      (> (char-code char) 127)))))

Acknowledgements

Thanks to Sam Tregar for HTML::Template which I've used successfully for many years together with mod_perl and which inspired me to write HTML-TEMPLATE.

Thanks to James Anderson and Kent M. Pitman who helped to de-confuse me about restarts.

Thanks to Marijn Haverbeke for a very clean and comprehensive patch for the TMPL_CALL code.

$Header: /usr/local/cvsrep/html-template/doc/index.html,v 1.56 2007/11/16 21:09:26 edi Exp $

BACK TO MY HOMEPAGE

zero	one	two	three	four	five	six
seven	eight	nine	ten	eleven	twelve	thirteen
fourteen	fifteen	sixteen	seventeen	eighteen	nineteen	twenty
twenty-one	twenty-two	twenty-three	twenty-four	twenty-five	twenty-six	twenty-seven
twenty-eight	twenty-nine	thirty	thirty-one	thirty-two	thirty-three	thirty-four
thirty-five	thirty-six	thirty-seven	thirty-eight	thirty-nine	forty	forty-one
forty-two	forty-three	forty-four	forty-five	forty-six	forty-seven	forty-eight