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

### 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.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 '`<!--`' 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 `INTERN`ing 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 `FUNCALL`ing 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`.
> - 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 <!-- 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.56 2007/11/16 21:09:26 edi Exp $

BACK TO MY HOMEPAGE