The cl-template Reference Manual

Table of Contents

The cl-template Reference Manual

This is the cl-template Reference Manual, version 0.0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 10:13:59 2021 GMT+0.

1 Introduction

cl-template: Simple general-purpose template engine for Common Lisp.

Getting cl-template

cl-template will be available on quicklisp sooner or later. Until then, just clone this repo and tell ASDF to find it. cl-template has no dependencies.

Why cl-template?

cl-template is yet another template engine for Common Lisp, taking inspiration from Ruby's ERb module. It differs from other template engines in that:

• It can be used for any output. Most Common Lisp template engines devise some mapping from s-expressions to HTML. cl-template can generate HTML, JSON, CSV, Markdown, or any other text-based format.
• It's just Lisp. The only other output-agnostic template engines that I found, CL-EMB and the somewhat misnamed HTML-TEMPLATE have additional syntax. In the case of HTML-TEMPLATE it doesn't use Lisp at all, only special template directives. CL-EMB mostly uses Lisp, but has special directives like @if and @loop.

Syntax

The most distictive feature of cl-template is that it can infer the outermost set of parenthesis, to make your templates look a little cleaner. For example,

<ul class="person-list">
  <% (loop for person in (@ people) do
    <li><%= (name person) %>
  <% ) %>
</ul>

can be written as

<ul class="person-list">
  <% loop for person in (@ people) do %>
    <li><%= name person %></li>
  <% end %>
</ul>

The only deviations from pure Common Lisp are:

• Parenthesis inferrence
• end can function as a close parenthesis
• progn is automatically inserted into if expressions
• else separates clauses of an if expression

All of these are optional - you can choose not to use them at all. However, they tend to make templates easier to read and are recommended.

The rules for paren inference are:

• If it starts with an open paren, don't do anything.
• In a <%= %> block, if the content consists of sexps separated by spaces, assume it's a function call and add parenthesis at the beginning and end.
• In a <% %> block, always add parenthesis at the beginning and end if they aren't already there.

@ is the macro to get a variable from the data provided at runtime.

Some more examples:

{"articles": [
  <% loop for article in (@ articles) do %>
    {"id": <%= id article %>, "title": <%= title article %>, "body": <%= body article %>}
  <% end %>
]}

<!-- Don't use any optional features, just plain Lisp. Be sure to set clt:*add-progn-to-if* to nil first. -->
<% (if (comments (@ article)) %>
  <% (progn
  <ul id="article-<%= (id (@ article)) %>-comments" class="comments">
    <% (loop for comment in (comments (@ article)) do %>
    <li id="comment-<%= (id comment) %>" class="comment">
      <%= (author comment) %> said
      <p><%= (body comment) %></p>
    </li>
    <% ) %>
  </ul>
  <% ) %>
  <% (progn %>
  No comments! <a href="<%= link :new-comment %>">Add a comment.</a>
  <% ) %>
<% ) %>

API

All of cl-template's functionality is exposed through one function, #'compile-template.

(compile-template string &key (start-delimiter "<%") (start-echo-delimiter "<%=") (end-delimiter "%>"))

This returns a lambda which must be called with a plist as the sole argument, which provides the data for the template. This is available within the template as cl-template::__data but it is not recommended to use directly. (Although it is useful for things like iterating over all data the template gets, but that sort of thing is rare.) A better idea is to use the built-in @ macro, which looks up a keyword version of its argument in the data plist.

Usage example:

(with-open-file (template-file "views/person.html.clt")
  (let ((template (make-string (file-length template-file)))
        (person (get-person-from-database-somehow)))
    (read-sequence template template-file)
    (funcall (cl-template:compile-template template) (list :person person))))

#'compile-template does not yet cache the resulting function.

Additionally, to disable automatically adding a progn to if expressions set *add-progn-to-if* to nil.

cl-template is licensed under the MIT license.
Copyright (c) 2013 Peter Cannici

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 cl-template

Author

Peter Cannici <turkchess123@gmail.com>

License

MIT

Description

A simple output-agnostic templating system for Common Lisp.

Version

0.0.1

Source

cl-template.asd (file)

Components

• packages.lisp (file)
• util.lisp (file)
• cl-template.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 cl-template.asd

Location

cl-template.asd

Systems

cl-template (system)

3.1.2 cl-template/packages.lisp

Parent

cl-template (system)

Location

packages.lisp

Packages

• cl-template-template-symbols
• cl-template

3.1.3 cl-template/util.lisp

Dependency

packages.lisp (file)

Parent

cl-template (system)

Location

util.lisp

Internal Definitions

• match-pairs-ignoring (function)
• scan-between-delimiters (function)
• scan-string-until-ignoring (function)

3.1.4 cl-template/cl-template.lisp

Dependencies

• packages.lisp (file)
• util.lisp (file)

Parent

cl-template (system)

Location

cl-template.lisp

Exported Definitions

• *add-progn-to-if* (special variable)
• compile-template (function)

Internal Definitions

• *template-fn-cache* (special variable)
• add-progn-to-if-expression (function)
• compile-echo-expression (function)
• compile-expression (function)
• compile-string (function)
• compile-template-part (function)
• handle-end-expression (function)
• internal-compile-template (function)

4 Packages

Packages are listed by definition order.

4.1 cl-template-template-symbols

Source

packages.lisp (file)

Use List

common-lisp

4.2 cl-template

Source

packages.lisp (file)

Nickname

clt

Use List

common-lisp

Exported Definitions

• *add-progn-to-if* (special variable)
• compile-template (function)

Internal Definitions

• *template-fn-cache* (special variable)
• add-progn-to-if-expression (function)
• compile-echo-expression (function)
• compile-expression (function)
• compile-string (function)
• compile-template-part (function)
• handle-end-expression (function)
• internal-compile-template (function)
• match-pairs-ignoring (function)
• scan-between-delimiters (function)
• scan-string-until-ignoring (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *add-progn-to-if*

Boolean; whether or not to implicitly add a progn to IF expressions.

Package

cl-template

Source

cl-template.lisp (file)

5.1.2 Functions

Function: compile-template STRING &key START-DELIMITER START-ECHO-DELIMITER END-DELIMITER

Compile a string template into a lambda, which can be invoked with
a plist as the only argument and provides data to the template. The
data argument to the lambda is available in the template as
‘cl-template::__data‘, although it’s not recommended to use it
directly. See README.md for examples of the template syntax.
It caches the result of the compilation.
Examples:
(compile-template "the number is <%= (@ number) %>") ; (lambda (__data) ...)
(compile-template "{{= @ mood }} shark" :start-delimiter "{{" :start-echo-delimiter "{{=" :end-delimiter "}}") ; (lambda (__data) ...) (funcall (compile-template "<%= format nil "~@r" (@ number) %>") ’(:number 12)) ; "XII"

Package

cl-template

Source

cl-template.lisp (file)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *template-fn-cache*

Hash table which compiled template functions are cached in.

Package

cl-template

Source

cl-template.lisp (file)

5.2.2 Functions

Function: add-progn-to-if-expression EXPRESSION

Package

cl-template

Source

cl-template.lisp (file)

Function: compile-echo-expression CODE STREAM EXPRESSIONS STACK

Package

cl-template

Source

cl-template.lisp (file)

Function: compile-expression CODE STREAM EXPRESSIONS STACK

Package

cl-template

Source

cl-template.lisp (file)

Function: compile-string STRING STREAM EXPRESSIONS STACK

Package

cl-template

Source

cl-template.lisp (file)

Function: compile-template-part STRING START START-DELIMITER START-ECHO-DELIMITER END-DELIMITER STREAM EXPRESSIONS STACK

Package

cl-template

Source

cl-template.lisp (file)

Function: handle-end-expression EXPRESSIONS STACK

Package

cl-template

Source

cl-template.lisp (file)

Function: internal-compile-template STRING START-DELIMITER START-ECHO-DELIMITER END-DELIMITER STREAM-NAME

Package

cl-template

Source

cl-template.lisp (file)

Function: match-pairs-ignoring STRING PAIR &key IGNORE-LIST START END

Count the occurences of a pair (e.g. []) in a string, ignoring any that occur in between pairs of ‘ignore-list‘. Example:
(match-pairs-ignoring "(something)" ’(#( . #))) ; t
(match-pairs-ignoring "[that <thing]>" ’(#[ . #]) :ignore-list ’((#< . #>))) ; nil

Package

cl-template

Source

util.lisp (file)

Function: scan-between-delimiters STRING START-DELIMITER END-DELIMITER &key IGNORE-LIST START END

Scan a string and return a substring between the two delimiter substrings.
Example:
(scan-between-delimiters "abc <%= thingy %> def" "<%=" "%>") ; " thingy "
(scan-between-delimiters "what{{ever stuff<ignor{{ing>{{now}}xyz" :ignore-list ’((#< . #>)) :start 10) ; "now"

Package

cl-template

Source

util.lisp (file)

Function: scan-string-until-ignoring STRING TERMINATOR &key IGNORE-LIST START END

Scan a string until a substring is encountered, ignoring anything
between ignore-list pairs. Probably not super-useful outside of
CLT. In CLT it is used to scan until the next end delimiter while
ignoring things in quotes.
Example:
(scan-string-until-ignoring "abc|def" "|") ; "abc"
(scan-string-until-ignoring "abc <ignor|ing> def" "|" :ignore-list ’((#< . #>))) ; "abc <ignor|ing> def"

Package

cl-template

Source

util.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types