alpha123 / cl-template

Simple, output-agnostic template engine for Common Lisp, inspired by ERb.

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

cl-template's Issues

Doesn't build -- implicit dependency on Fiveam?

I can't load this without manually loading Fiveam first. It looks like cl-template-tests and cl-template share packages.lisp? Since that file references Fiveam that means the main cl-template system must also depend-on fiveam.

Style warning about unused __data variable.

The example below generates a style warning about the unused variable __data.

(eval-when (:compile-toplevel :load-toplevel :execute)
  (asdf:load-system "cl-template"))

(defpackage "EXAMPLE"
  (:use "COMMON-LISP"))
(in-package "EXAMPLE")

(defun test ()
  (let ((fn (cl-template:compile-template "hey")))
    (funcall fn nil)))

; cl-user> (example::test)
; in: lambda (cl-template::__data)
;     (LAMBDA (CL-TEMPLATE::__DATA)
;       (MACROLET ((@ (VAR)
;                    `(GETF CL-TEMPLATE::__DATA ,#)))
;         (WITH-OUTPUT-TO-STRING (#:G620) (WRITE-STRING "hey" #:G620))))
; 
; caught style-warning:
;   The variable cl-template::__data is defined but never used.
; 
; compilation unit finished
;   caught 1 STYLE-WARNING condition

It would be great if you could add (declare ignorable __data) to compile-template.

Thanks