The cl-template Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-template Reference Manual

This is the cl-template Reference Manual, version 0.0.1, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 03:34:57 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

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:

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:

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:

@ 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


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

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

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-template.asd

Location

cl-template.asd

Systems

cl-template (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 cl-template/packages.lisp

Parent

cl-template (system)

Location

packages.lisp

Packages

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 cl-template/util.lisp

Dependency

packages.lisp (file)

Parent

cl-template (system)

Location

util.lisp

Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 cl-template/cl-template.lisp

Dependencies
Parent

cl-template (system)

Location

cl-template.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 cl-template-template-symbols

Source

packages.lisp (file)

Use List

common-lisp


Previous: , Up: Packages   [Contents][Index]

4.2 cl-template

Source

packages.lisp (file)

Nickname

clt

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Previous: , Up: Exported definitions   [Contents][Index]

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)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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)


Previous: , Up: Internal definitions   [Contents][Index]

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)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-template.asd: The cl-template<dot>asd file
cl-template/cl-template.lisp: The cl-template/cl-template<dot>lisp file
cl-template/packages.lisp: The cl-template/packages<dot>lisp file
cl-template/util.lisp: The cl-template/util<dot>lisp file

F
File, Lisp, cl-template.asd: The cl-template<dot>asd file
File, Lisp, cl-template/cl-template.lisp: The cl-template/cl-template<dot>lisp file
File, Lisp, cl-template/packages.lisp: The cl-template/packages<dot>lisp file
File, Lisp, cl-template/util.lisp: The cl-template/util<dot>lisp file

L
Lisp File, cl-template.asd: The cl-template<dot>asd file
Lisp File, cl-template/cl-template.lisp: The cl-template/cl-template<dot>lisp file
Lisp File, cl-template/packages.lisp: The cl-template/packages<dot>lisp file
Lisp File, cl-template/util.lisp: The cl-template/util<dot>lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   A   C   F   H   I   M   S  
Index Entry  Section

A
add-progn-to-if-expression: Internal functions

C
compile-echo-expression: Internal functions
compile-expression: Internal functions
compile-string: Internal functions
compile-template: Exported functions
compile-template-part: Internal functions

F
Function, add-progn-to-if-expression: Internal functions
Function, compile-echo-expression: Internal functions
Function, compile-expression: Internal functions
Function, compile-string: Internal functions
Function, compile-template: Exported functions
Function, compile-template-part: Internal functions
Function, handle-end-expression: Internal functions
Function, internal-compile-template: Internal functions
Function, match-pairs-ignoring: Internal functions
Function, scan-between-delimiters: Internal functions
Function, scan-string-until-ignoring: Internal functions

H
handle-end-expression: Internal functions

I
internal-compile-template: Internal functions

M
match-pairs-ignoring: Internal functions

S
scan-between-delimiters: Internal functions
scan-string-until-ignoring: Internal functions

Jump to:   A   C   F   H   I   M   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*add-progn-to-if*: Exported special variables
*template-fn-cache*: Internal special variables

S
Special Variable, *add-progn-to-if*: Exported special variables
Special Variable, *template-fn-cache*: Internal special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-template: The cl-template system
cl-template: The cl-template package
cl-template-template-symbols: The cl-template-template-symbols package

P
Package, cl-template: The cl-template package
Package, cl-template-template-symbols: The cl-template-template-symbols package

S
System, cl-template: The cl-template system

Jump to:   C   P   S