The cl-markup Reference Manual

Table of Contents

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

The cl-markup Reference Manual

This is the cl-markup Reference Manual, version 0.1, generated automatically by Declt version 2.3 "Robert April" on Tue Feb 20 08:10:07 2018 GMT+0.


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

1 Introduction

CL-MARKUP - Modern markup generation library for Common Lisp

Features & advantages

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><p id=\"title\">aiueo</p></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 "\"><b>" *output-stream*)
                      (write-string (escape-string (cl-markup::ensure-string title))
                                    *output-stream*)
                      (write-string "</b></a><br />" *output-stream*))
               (with-output-to-string (#:G0)
                 (write-string "<a href=\"" #:G0)
                 (write-string (escape-string (cl-markup::ensure-string link)) #:G0)
                 (write-string "\"><b>" #:G0)
                 (write-string (escape-string (cl-markup::ensure-string title)) #:G0)
                 (write-string "</b></a><br />" #: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

markup is the simplest way to generate HTML.

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

By default, CL-MARKUP follows XHTML valid styling.

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

You can configure the style by setting *markup-language*.

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

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

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

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

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

Other macros such as html, xhtml, html5, and xml output DOCTYPE before markup.

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

(html5 (:p "あいうえお") (:br))
;=> "<!DOCTYPE html><html><p>あいうえお</p><br></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><p>あいうえお</p><br /></html>"

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

Escape

Embedded strings are escaped automatically.

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

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

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

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

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

Direct output to stream

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

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

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

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 #M which can be enabled by (enable-markup-syntax).

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

License

Copyright (c) 2011 Eitarow F


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-markup

Author

Eitarow Fukamachi

License

LLGPL

Version

0.1

Source

cl-markup.asd (file)

Component

src (module)


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

3 Modules

Modules are listed depth-first from the system components tree.


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

3.1 cl-markup/src

Parent

cl-markup (system)

Location

src/

Components

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

4 Files

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


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

4.1 Lisp


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

4.1.1 cl-markup.asd

Location

cl-markup.asd

Systems

cl-markup (system)

Packages

cl-markup-asd


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

4.1.2 cl-markup/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

cl-markup


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

4.1.3 cl-markup/src/util.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/util.lisp

Exported Definitions
Internal Definitions

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

4.1.4 cl-markup/src/special.lisp

Dependency

util.lisp (file)

Parent

src (module)

Location

src/special.lisp

Exported Definitions

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

4.1.5 cl-markup/src/markup.lisp

Dependency

special.lisp (file)

Parent

src (module)

Location

src/markup.lisp

Exported Definitions
Internal Definitions

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

4.1.6 cl-markup/src/helper.lisp

Dependency

markup.lisp (file)

Parent

src (module)

Location

src/helper.lisp

Exported Definitions

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

4.1.7 cl-markup/src/readmacro.lisp

Dependency

helper.lisp (file)

Parent

src (module)

Location

src/readmacro.lisp

Exported Definitions

enable-markup-syntax (macro)

Internal Definitions

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

5 Packages

Packages are listed by definition order.


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

5.1 cl-markup-asd

Source

cl-markup.asd

Use List

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

5.2 cl-markup

Source

package.lisp (file)

Nickname

markup

Use List

common-lisp

Exported Definitions
Internal Definitions

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

6 Definitions

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


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

6.1 Exported definitions


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

6.1.1 Special variables

Special Variable: *auto-escape*
Package

cl-markup

Source

util.lisp (file)

Special Variable: *markup-language*

Valid markup languages are :html, :xhtml and :xml

Package

cl-markup

Source

special.lisp (file)

Special Variable: *output-stream*

Stream to output the generated string. If this is nil, then just return as a string the result. T means *standard-output*.

Package

cl-markup

Source

special.lisp (file)


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

6.1.2 Macros

Macro: enable-markup-syntax ()
Package

cl-markup

Source

readmacro.lisp (file)

Macro: esc &rest FORMS
Package

cl-markup

Source

helper.lisp (file)

Macro: html &rest TAGS
Package

cl-markup

Source

markup.lisp (file)

Macro: html5 &rest TAGS
Package

cl-markup

Source

markup.lisp (file)

Macro: markup &rest TAGS
Package

cl-markup

Source

markup.lisp (file)

Macro: raw &rest FORMS
Package

cl-markup

Source

helper.lisp (file)

Macro: xhtml &rest TAGS
Package

cl-markup

Source

markup.lisp (file)

Macro: xml &rest TAGS
Package

cl-markup

Source

markup.lisp (file)


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

6.1.3 Functions

Function: doctype LANG
Package

cl-markup

Source

markup.lisp (file)

Function: escape-string STRING
Package

cl-markup

Source

util.lisp (file)

Function: markup* &rest TAGS
Package

cl-markup

Source

markup.lisp (file)


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

6.2 Internal definitions


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

6.2.1 Macros

Macro: %escape-string-form VAL
Package

cl-markup

Source

markup.lisp (file)

Macro: %write-strings &rest STRINGS
Package

cl-markup

Source

markup.lisp (file)

Macro: with-doctype LANG &body BODY
Package

cl-markup

Source

markup.lisp (file)


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

6.2.2 Functions

Function: %dirty-string-form FORM
Package

cl-markup

Source

markup.lisp (file)

Function: %enable-markup-syntax ()
Package

cl-markup

Source

readmacro.lisp (file)

Function: attributes->string ATTR-PLIST
Package

cl-markup

Source

markup.lisp (file)

Function: ensure-string VAL
Package

cl-markup

Source

util.lisp (file)

Function: map-group-if PRED LIST FN
Package

cl-markup

Source

util.lisp (file)

Function: markup-reader STREAM CHAR ARG
Package

cl-markup

Source

readmacro.lisp (file)

Function: parse-tag TAG
Package

cl-markup

Source

markup.lisp (file)

Function: should-escape-p VAL
Package

cl-markup

Source

util.lisp (file)

Function: substitute-string-by FN STRING
Package

cl-markup

Source

util.lisp (file)

Function: tag->string TAG
Package

cl-markup

Source

markup.lisp (file)

Function: tagp FORM
Package

cl-markup

Source

markup.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   C   F   L   M  
Index Entry  Section

C
cl-markup.asd: The cl-markup<dot>asd file
cl-markup/src: The cl-markup/src module
cl-markup/src/helper.lisp: The cl-markup/src/helper<dot>lisp file
cl-markup/src/markup.lisp: The cl-markup/src/markup<dot>lisp file
cl-markup/src/package.lisp: The cl-markup/src/package<dot>lisp file
cl-markup/src/readmacro.lisp: The cl-markup/src/readmacro<dot>lisp file
cl-markup/src/special.lisp: The cl-markup/src/special<dot>lisp file
cl-markup/src/util.lisp: The cl-markup/src/util<dot>lisp file

F
File, Lisp, cl-markup.asd: The cl-markup<dot>asd file
File, Lisp, cl-markup/src/helper.lisp: The cl-markup/src/helper<dot>lisp file
File, Lisp, cl-markup/src/markup.lisp: The cl-markup/src/markup<dot>lisp file
File, Lisp, cl-markup/src/package.lisp: The cl-markup/src/package<dot>lisp file
File, Lisp, cl-markup/src/readmacro.lisp: The cl-markup/src/readmacro<dot>lisp file
File, Lisp, cl-markup/src/special.lisp: The cl-markup/src/special<dot>lisp file
File, Lisp, cl-markup/src/util.lisp: The cl-markup/src/util<dot>lisp file

L
Lisp File, cl-markup.asd: The cl-markup<dot>asd file
Lisp File, cl-markup/src/helper.lisp: The cl-markup/src/helper<dot>lisp file
Lisp File, cl-markup/src/markup.lisp: The cl-markup/src/markup<dot>lisp file
Lisp File, cl-markup/src/package.lisp: The cl-markup/src/package<dot>lisp file
Lisp File, cl-markup/src/readmacro.lisp: The cl-markup/src/readmacro<dot>lisp file
Lisp File, cl-markup/src/special.lisp: The cl-markup/src/special<dot>lisp file
Lisp File, cl-markup/src/util.lisp: The cl-markup/src/util<dot>lisp file

M
Module, cl-markup/src: The cl-markup/src module

Jump to:   C   F   L   M  

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

A.2 Functions

Jump to:   %  
A   D   E   F   H   M   P   R   S   T   W   X  
Index Entry  Section

%
%dirty-string-form: Internal functions
%enable-markup-syntax: Internal functions
%escape-string-form: Internal macros
%write-strings: Internal macros

A
attributes->string: Internal functions

D
doctype: Exported functions

E
enable-markup-syntax: Exported macros
ensure-string: Internal functions
esc: Exported macros
escape-string: Exported functions

F
Function, %dirty-string-form: Internal functions
Function, %enable-markup-syntax: Internal functions
Function, attributes->string: Internal functions
Function, doctype: Exported functions
Function, ensure-string: Internal functions
Function, escape-string: Exported functions
Function, map-group-if: Internal functions
Function, markup*: Exported functions
Function, markup-reader: Internal functions
Function, parse-tag: Internal functions
Function, should-escape-p: Internal functions
Function, substitute-string-by: Internal functions
Function, tag->string: Internal functions
Function, tagp: Internal functions

H
html: Exported macros
html5: Exported macros

M
Macro, %escape-string-form: Internal macros
Macro, %write-strings: Internal macros
Macro, enable-markup-syntax: Exported macros
Macro, esc: Exported macros
Macro, html: Exported macros
Macro, html5: Exported macros
Macro, markup: Exported macros
Macro, raw: Exported macros
Macro, with-doctype: Internal macros
Macro, xhtml: Exported macros
Macro, xml: Exported macros
map-group-if: Internal functions
markup: Exported macros
markup*: Exported functions
markup-reader: Internal functions

P
parse-tag: Internal functions

R
raw: Exported macros

S
should-escape-p: Internal functions
substitute-string-by: Internal functions

T
tag->string: Internal functions
tagp: Internal functions

W
with-doctype: Internal macros

X
xhtml: Exported macros
xml: Exported macros

Jump to:   %  
A   D   E   F   H   M   P   R   S   T   W   X  

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

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*auto-escape*: Exported special variables
*markup-language*: Exported special variables
*output-stream*: Exported special variables

S
Special Variable, *auto-escape*: Exported special variables
Special Variable, *markup-language*: Exported special variables
Special Variable, *output-stream*: Exported special variables

Jump to:   *  
S  

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

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-markup: The cl-markup system
cl-markup: The cl-markup package
cl-markup-asd: The cl-markup-asd package

P
Package, cl-markup: The cl-markup package
Package, cl-markup-asd: The cl-markup-asd package

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

Jump to:   C   P   S