Spinneret

Spinneret allows you to generate HTML5 documents using Common Lisp macros. The primary entry point is with-html, which writes to the *html* stream, and with-html-string, which returns the generated HTML as a string.

Tags are represented by keywords in function position. You can use a selector-like syntax for IDs and classes (e.g., :div#id :div.class). Attributes are provided as keyword-value pairs following the tag.

(in-package #:spinneret)

(defun shopping-list ()
  (with-html-string
    (:header
     (:h1 "Home page"))
    (:section
     (:p "Hello World")))) ; => <header><h1>Home page</h1></header><section><p>Hello World</p></section>

If the spinneret/cl-markdown system is loaded, strings in a function position are treated as Markdown. The Markdown is compiled and then passed to format as a control string. This is ideal for quick inline formatting like links.

(with-html
  ("Here is some copy, with [a link](~a)" link))

To use Spinneret in a Parenscript environment, load the spinneret/ps system.

Behavioral Differences in Parenscript:

• with-html returns a DocumentFragment instead of a string.
• with-html-string is not available.
• get-html-path is not implemented.
• :ATTRS and :TAG are not available.
• If Markdown support is enabled, strings in function position are parsed as Markdown, but supplying arguments triggers an error (as Parenscript lacks format).

To embed Parenscript code inside Spinneret HTML, you must wrap the ps macro with :raw to prevent the generated JavaScript from being escaped.

Example of embedding script:

(with-html-string
  (:script
    (:raw (ps
            (defun greeting ()
              (alert "Hello"))))))

(load "spinneret/ps")

You can control how Spinneret formats its output by binding the *html-style* variable. This is useful for controlling indentation and predictability.

• :human (default): Attempts to produce human-readable, idiomatic HTML.
• :tree: Prints every element as a block element and every run of text on a new line. This ensures all tags are explicitly closed and is highly predictable.

(let ((*html-style* :tree) (*print-pretty* nil))
  (with-html-string
    (:div
      (:p "Text " (:a "link text") " more text"))))
;; => "<div><p>Text <a>link text</a> more text</p></div>"

Spinneret performs compile-time validation of tags and attributes.

• Valid Tags: Standard HTML5 tags or custom elements (names starting with an ASCII alphabetic character and containing a hyphen).
• Custom Elements: Attributes are not validated for custom elements.

Managing Validation Warnings:

1. Disable validation for specific prefixes (e.g., for frameworks like Angular using ng-):

   (pushnew "ng-" *unvalidated-attribute-prefixes* :test #'equal)

2. Disable attribute validation entirely:

   (setf *unvalidated-attribute-prefixes* '(""))

When using the ps macro to generate JavaScript within a Spinneret HTML block, always wrap the ps call in (:raw ...) to ensure the generated code is not escaped.

Example:

(with-html-string
  (:div :onclick (:raw (ps (alert "Hello")))))
;; <div onclick="alert('Hello');"></div>

(with-html-string
  (:script
    (:raw (ps
            (defun greeting ()
              (alert "Hello"))))))

If Spinneret makes poor line-breaking decisions for your custom types, you can specialize the html-length generic function. This tells the pretty-printer how long the object will be when rendered.

(defmethod html-length ((uri puri:uri))
  (length (puri:render-uri uri nil)))

The get-html-path function returns a list of currently open HTML tags, ordered from the most recent (innermost) to the earliest (outermost). This is useful for conditional rendering, such as deciding whether to wrap content in a <table> tag based on whether a table is already open.

Note that get-html-path returns a freshly-consed list every time it is called.

Example of conditional wrapping:

(defun tabulate (&rest rows)
  (with-html
    (flet ((tabulate ()
             (loop for row in rows do
               (:tr (loop for cell in row do
                 (:td cell))))))
      (if (find :table (get-html-path))
          (tabulate)
          (:table (:tbody (tabulate)))))))

(get-html-path) ;-> '(:table :section :body :html)

You can use interpret-html-tree to parse a Lisp s-expression representing HTML structure into actual HTML output. Note that this interpreter is still under development and supports a subset of Spinneret syntax.

(interpret-html-tree `(:div :id "dynamic!"))
;; => <div id="dynamic!"></div>