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, Booble, and Heike Stephan.

Download shortcut: http://weitz.de/files/html-template.tar.gz.


 

Contents

  1. Simple example
  2. Download and installation
  3. Support and mailing lists
  4. Syntax
  5. Semantics
  6. The HTML-TEMPLATE dictionary
    1. Creating and using printers
      1. create-template-printer
      2. fill-and-print-template
    2. The template cache
      1. clear-template-cache
      2. delete-from-template-cache
      3. *no-cache-check*
    3. Customization
      1. *template-start-marker*
      2. *template-end-marker*
      3. *default-template-pathname*
      4. *default-template-output*
      5. *convert-nil-to-empty-string*
      6. *format-non-strings*
      7. *sequences-are-lists*
      8. *upcase-attribute-strings*
      9. *string-modifier*
      10. *template-symbol-package*
      11. *force-default*
      12. *value-access-function*
      13. *call-template-access-function*
      14. *call-value-access-function*
      15. *ignore-empty-lines*
      16. *warn-on-creation*
    4. Conditions
      1. template-error
      2. template-invocation-error
      3. template-missing-value-error
      4. template-not-a-string-error
      5. template-not-a-string-error-value
      6. template-syntax-error
      7. template-syntax-error-stream
      8. template-syntax-error-line
      9. template-syntax-error-col
    5. Escaping
      1. escape-string
      2. *escape-char-p*
      3. escape-string-minimal
      4. escape-string-minimal-plus-quotes
      5. escape-string-iso-8859-1
      6. escape-string-all
  7. 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.2.

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 '<!--' and directly before '-->' 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:


<!-- TMPL_VAR symbol -->

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 <!-- TMPL_VAR foo -->!")))
    (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!

<!-- TMPL_IF symbol -->text<!-- /TMPL_IF -->
<!-- TMPL_UNLESS symbol -->text<!-- /TMPL_UNLESS -->

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 <!-- TMPL_IF fast -->quick <!-- /TMPL_IF -->brown fox")))
    (fill-and-print-template tp '(:fast t))
    (terpri)
    (fill-and-print-template tp '(:fast nil)))
The quick brown fox
The brown fox

<!-- TMPL_IF symbol -->text<!-- TMPL_ELSE -->text'<!-- /TMPL_IF -->
<!-- TMPL_UNLESS symbol -->text<!-- TMPL_ELSE -->text'<!-- /TMPL_UNLESS -->

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 <!-- TMPL_IF fast -->quick<!-- TMPL_ELSE -->slow<!-- /TMPL_IF --> 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

<!-- TMPL_LOOP symbol -->text<!-- /TMPL_LOOP -->

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
     "<!-- TMPL_LOOP foo -->[<!-- TMPL_VAR bar -->,<!-- TMPL_VAR baz -->]<!-- /TMPL_LOOP -->"))

*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]

<!-- TMPL_REPEAT symbol -->text<!-- /TMPL_REPEAT -->

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 <!-- TMPL_REPEAT three -->very <!-- /TMPL_REPEAT -->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.

<!-- TMPL_INCLUDE pathname -->

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 <!-- TMPL_IF fast -->quick <!-- /TMPL_IF -->brown fox" s))
"The <!-- TMPL_IF fast -->quick <!-- /TMPL_IF -->brown fox"
* (fill-and-print-template "<!-- TMPL_INCLUDE '/tmp/foo' --> 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 "<!-- TMPL_INCLUDE '/tmp/foo' --> 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.

<!-- TMPL_CALL symbol -->

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'><!-- TMPL_VAR text --></p>" s))
"<p class='fancy'><!-- TMPL_VAR text --></p>"
* (with-open-file (s "/tmp/header" :direction :output :if-exists :supersede)
    (write-string "<h1><!-- TMPL_VAR text --></h1>" s))
"<h1><!-- TMPL_VAR text --></h1>"
* (fill-and-print-template "<body><!-- TMPL_CALL parts --></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. 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 <!-- TMPL_VAR speed --> brown fox")
    (funcall (create-template-printer stream) '(:speed "quick")))
The quick brown fox
* (funcall (create-template-printer "The <!-- TMPL_VAR speed --> brown fox") '(:speed "slow"))
The slow brown fox
* (with-open-file (stream "/tmp/foo.tmpl" :direction :output)
    (write-string "The <!-- TMPL_VAR speed --> brown fox" stream))

"The <!-- TMPL_VAR speed --> 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 <!-- TMPL_VAR speed --> brown fox" '(:speed "slow"))
The slow brown fox
* (with-input-from-string (stream "The <!-- TMPL_VAR speed --> 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 <!-- TMPL_VAR speed --> brown fox" stream))

"The <!-- TMPL_VAR speed --> 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 <!-- TMPL_VAR speed --> 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 <!-- TMPL_VAR speed --> brown fox" stream))

"The <!-- TMPL_VAR speed --> 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 <!-- TMPL_VAR speed --> brown fox" '(:speed "slow"))
The slow brown fox
* (with-output-to-string (*default-template-output*)
    (fill-and-print-template "The <!-- TMPL_VAR speed --> 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 <!-- TMPL_VAR speed --> 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 <!-- TMPL_VAR speed --> 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 <!-- TMPL_VAR speed --> 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 <!-- TMPL_VAR speed --> brown fox" '(:speed "<quick>"))
The &lt;quick&gt; brown fox

* (let ((*string-modifier* #'identity))
    (fill-and-print-template "The <!-- TMPL_VAR speed --> 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 <!-- TMPL_VAR speed --> 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>"
"  <!-- TMPL_LOOP row-loop -->"
"  <tr>"
"    <!-- TMPL_LOOP col-loop -->"
"    <td><!-- TMPL_VAR item --></td>"
"    <!-- /TMPL_LOOP -->"
"  </tr>"
"  <!-- /TMPL_LOOP -->"
"</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 <!-- TMPL_VAR number--> 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.59 2015-05-21 21:00:01 edi Exp $

BACK TO MY HOMEPAGE