cl-markup

# CL-MARKUP - Modern markup generation library for Common Lisp

## Features & advantages

* Fast (even faster through compiling the code)
* Safety
* Support for multiple document types (markup, xml, html, html5, xhtml)
* Output with doctype
* Direct output to stream

## Usage

 (html
 (:body
 (:p :id "title" "aiueo")))
 ;=> "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01 Transitional//EN\"
 ; \"http://www.w3.org/TR/html4/loose.dtd\">
 ; <html><body>aiueo</body></html>"

## Installation

## Is this really fast?

Generally CL-MARKUP generates efficient codes which mainly consists of
series of `write-string's as much as possible. See how following two
examples are expanded by macro expansion.

As you can see, the codes are a bit more complicated than that of
CL-WHO because CL-MARKUP alters the destination of output in run-time.

Example A:

 ;; Example A
 (let ((*output-stream* t))
 (loop for (link . title) in '(("http://zappa.com/" . "Frank Zappa")
 ("http://marcusmiller.com/" . "Marcus Miller")
 ("http://www.milesdavis.com/" . "Miles Davis"))
 do (markup (:a :href link
 (:b title))
 (:br))))

 ;; Example A: generated by CL-MARKUP
 (let ((*output-stream* t))
 (loop for (link . title) in '(("http://zappa.com/" . "Frank Zappa")
 ("http://marcusmiller.com/" . "Marcus Miller")
 ("http://www.milesdavis.com/" . "Miles Davis"))
 do (if *output-stream*
 (progn (write-string "<a href=\"" *output-stream*)
 (write-string (escape-string (cl-markup::ensure-string link))
 *output-stream*)
 (write-string "\">" *output-stream*)
 (write-string (escape-string (cl-markup::ensure-string title))
 *output-stream*)
 (write-string "</a> " *output-stream*))
 (with-output-to-string (#:G0)
 (write-string "<a href=\"" #:G0)
 (write-string (escape-string (cl-markup::ensure-string link)) #:G0)
 (write-string "\">" #:G0)
 (write-string (escape-string (cl-markup::ensure-string title)) #:G0)
 (write-string "</a> " #:G0)))))

Example B:

 ;; Example B
 (markup
 (:table :border 0 :cellpadding 4
 (loop for i below 25 by 5
 collect
 (markup
 (:tr :align "right"
 (loop for j from i below (+ i 5)
 collect
 (markup
 (:td :bgcolor
 (if (oddp j)
 "pink"
 "green")
 (format nil "~@R" (1+ j))))))))))

 ;; Example B: generated by CL-MARKUP
 (if *output-stream*
 (progn (write-string "<table border=\"0\" cellpadding=\"4\">"
 *output-stream*)
 (write-string (let ((#:G0
 (loop for i below 25 by 5
 collect (markup
 (:tr
 :align
 "right"
 (loop for j
 from
 i
 below
 (+ i 5)
 collect (markup
 (:td
 :bgcolor
 (if
 (oddp j)
 "pink"
 "green")
 (format
 nil
 "~@r"
 (1+ j))))))))))
 (if (consp #:G0)
 (with-output-to-string (#:G1)
 (dolist (#:G2 #:G0)
 (write-string #:G2 #:G1)))
 #:G0))
 *output-stream*)
 (write-string "</table>" *output-stream*))
 (with-output-to-string (#:G0)
 (write-string "<table border=\"0\" cellpadding=\"4\">"
 #:G0)
 (write-string (let
 ((#:G0
 (loop for i below 25 by 5
 collect (markup
 (:tr
 :align
 "right"
 (loop for j
 from
 i
 below
 (+ i 5)
 collect (markup
 (:td
 :bgcolor
 (if
 (oddp j)
 "pink"
 "green")
 (format
 nil
 "~@r"
 (1+
 j))))))))))
 (if
 (consp #:G0)
 (with-output-to-string
 (#:G1)
 (dolist
 (#:G2 #:G0)
 (write-string #:G2 #:G1)))
 #:G0))
 #:G0)
 (write-string "</table>" #:G0)))

## Markup language

<code>markup</code> is the simplest way to generate HTML.

 (markup (:p "あいうえお"))
 ;=> "あいうえお"

By default, CL-MARKUP follows XHTML valid styling.

 (markup (:br))
 ;=> " "

You can configure the style by setting <code>\*markup-language\*</code>.

 (eval-when (:compile-toplevel :load-toplevel :execute)
 (setf *markup-language* :html))

Don't forget to wrap <code>setf</code> with <code>eval-when</code>
since it is used in compile-time in order to expand
<code>markup</code>. This also means you are **NOT** allowed to write
codes like this:

 ;; THIS IS A WRONG EXAMPLE!!
 (let ((*markup-language* :html))
 (markup (:br)))
 ;=> " "

In case you **really** want to delay the decision until run-time, use
<code>markup*</code>, a functional version of <code>markup</code>.

 ;; This is a correct one.
 ;; But I don't recommend this for performance.
 (let ((*markup-language* :xhtml))
 (markup* '(:br)))
 ;=> " "

Other macros such as <code>html</code>, <code>xhtml</code>,
<code>html5</code>, and <code>xml</code> output DOCTYPE before
<code>markup</code>.

 (html (:p "あいうえお") (:br))
 ;=> "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01 Transitional//EN\" \"http://www.w3.org/TR/html4/loose.dtd\"><html>あいうえお </html>"

 (html5 (:p "あいうえお") (:br))
 ;=> "<!DOCTYPE html><html>あいうえお </html>"

 (xhtml (:p "あいうえお") (:br))
 ;=> "<?xml version=\"1.0\" encoding=\"UTF-8\"?><!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\"><html>あいうえお </html>"

 (xml (:p "あいうえお") (:br))
 ;=> "<?xml version=\"1.0\" encoding=\"UTF-8\"?>あいうえお "

## Escape

Embedded strings are escaped automatically.

 (markup (:p "Tiffany & Co."))
 ;=> "Tiffany &amp; Co."

If you don't want this behavior, set <code>\*auto-escape\*</code> nil
or use <code>raw</code> for temporal suppression.

 (let ((*auto-escape* nil))
 (markup (:p "Tiffany & Co.")))
 ;=> "Tiffany & Co."

 (markup (:p (raw "Tiffany & Co.")))
 ;=> "Tiffany & Co."

Also, when you want to ensure a certain code to be escaped (maybe
inside <code>raw</code>) use <code>esc</code>, which has the similar
syntax as that of <code>raw</code>.

## Direct output to stream

<code>Markup</code> macros returns html as a string. This behavior can
be customized by modifying <code>\*output-stream\*</code> which is
defaulted to <code>\*standard-output\*</code>.

 ;; Default behavior
 (let (*output-stream*)
 (markup (:p "hoge"))
 ;=> "hoge"

 ;; Output to *standard-output* directly
 (let ((*output-stream* t))
 (markup (:p "hoge")))
 ;;=> hoge
 ;=> "hoge"

## Markup syntax

You can embed Lisp code in the body of each tag.

 (markup (:ul (loop for item in '(1 2 3) collect (markup (:li item)))))

For more readability, CL-MARKUP provides a reader macro <code>#M</code>
which can be enabled by <code>(enable-markup-syntax)</code>.

 (enable-markup-syntax)
 #M(:ul (loop for item in '(1 2 3) collect #M(:li item))))

## License

Copyright (c) 2011 Eitarow Fukamachi. 
 
Contributors:

m7d - HTML5 support, April 21, 2012.

Licensed under the LLGPL License.

cl-markup

Upstream URL

Author

License

cl-markup

Version:

License:

Authors:

Dependencies:

cl-markup-test

Dependencies:

Dependencies (1)

Dependents (6)