1 XML

The XML language in mirrors allows the programatic assembly of syntactically valid XML and XHTML, without the problems of traditional list-representations:

• the data type of an element is distinct from the data type of a block of nodes;

• blocks can be arbitrarily nested without using forms such as append, quasiquote and unquote-splicing;

• raw blocks of unprocessed text can be inserted into an otherwise well-formed XML document;

• many XHTML browser bugs are automatically worked around;

• blocks of Javascript are automatically rendered as appropriately quoted attribute values and text;

• static blocks of output are pre-rendered to strings at macro expansion time.

XML syntax describes the syntax for creating blocks of XML, Rendering XML and sending XML responses describes how to send XML responses in the PLT web server, XML utilities describes some useful blocks of XML such as a DOCTYPES, and XML abstract syntax tree describes the underlying AST representation.

1.1 XML syntax

(require (planet untyped/mirrors/xml/syntax))

Mirrors proides two macros for building XML. Both of these forms have the same syntax, which is inspired by the list syntax used in Neil van Dyke’s HtmlPrag package:

(xml xml-expr ...)

xml-expr   =   quotable-value     |   (custom-syntax-id xml-expr ...)     |   (tag xml-expr ...)     |   (tag (@ attr-expr ...) xml-expr ...)     |   (& code-expr)     |   (!comment value-expr)     |   (!cdata value-expr)     |   (!pi value-expr)     |   (!raw value-expr)     |   ,xml     |   ,@(listof xml)           custom-syntax-id   =   id           tag   =   id           code-expr   =   id     |   integer     |   ,(U symbol integer)           value-expr   =   quotable-value     |   ,quotable-value           attr-expr   =   (id quotable-value)     |   (id ,quotable-value)     |   ,attribute     |   ,@(listof attribute)

Builds a block of XML, optimising any chunks of static markup into raw blocks.

Examples:

> (let ([content "content"])       (pretty-print (xml (span (@ [title "title"]) ,content))))

#s((block xml 0)      (#s((raw xml 0)          ("<span title=\"title\">"))       #s((atom xml 0) "content")       #s((raw xml 0) ("</span>"))))

custom-syntax-id indicates an identifier bound with define-xml-syntax.

(xml* xml-expr ...)

The same as xml except that no markup optimisation is performed:

> (let ([content "content"])       (pretty-print (xml* (span (@ [title "title"]) ,content))))

#s((element xml 0)      span      (#s(attribute          title          #s((atom xml 0) "title")))      #s((atom xml 0) "content"))

It takes slightly longer to render the XML trees produced with xml* as strings, but the full structure of the tree is preserved.

(define-xml-syntax (id arg ...) xml-expr)

(define-xml-syntax id xml-transformer)

(define-xml-syntax id xml-transformer expr-transformer)

Defines a custom syntactic form for use in xml and xml* blocks.

The first form above behaves like define-syntax-rule. xml-expr should be a regular xml block.

Examples:

> (define-xml-syntax (!linkto url)       (xml (a (@ [href url]) url)))

> (xml->string (xml (!linkto "http://www.plt-scheme.org")))

"<a href=\"http://www.plt-scheme.org\">http://www.plt-scheme.org</a>"

> (!linkto "http://www.plt-scheme.org")

eval:6:0: !linkto: must be used as an xml expression in:

(!linkto "http://www.plt-scheme.org")

The second and third forms behave like define-match-expander. xml-transformer is a syntax transformer procedure used during XML expansion, which accepts an XML form as an input and returns a complete xml or xml* block representing the expansion. expr-transformer is a transformer procedure that is used in regular Scheme expansion. When xml-transformer is omitted, use of the syntax form outside of a XML block results in a syntax error.

Examples:

> (define-xml-syntax !linkto       (lambda (stx)         (syntax-case stx ()           [(_ url) #'(xml (a (@ [href url]) url))]))       (lambda (stx)         (syntax-case stx ()           [(_ url) #'url])))

> (xml->string (xml (!linkto "http://www.plt-scheme.org")))

"<a href=\"http://www.plt-scheme.org\">http://www.plt-scheme.org</a>"

> (!linkto "http://www.plt-scheme.org")

"http://www.plt-scheme.org"

(xml-attrs attr-expr ...)

Builds a list of attribute structures. Useful in conjunction with the unquote-splicing form of attr-expr:

> (let ([attrs (xml-attrs [title "title"] [href "href"])])       (xml->string (xml (a (@ ,@attrs) "text"))))

"<a title=\"title\" href=\"href\">text</a>"

(opt-xml boolean-expr xml-expr ...)

Syntactic shorthand for:

(if boolean-expr

(xml xml-expr ...)

(xml))

Examples:

> (xml->string (opt-xml #t (span "This span will be printed....")))

"<span>This span will be printed....</span>"

> (xml->string (opt-xml #f (span "...but this span won't.")))

""

(opt-xml-attr id)

(opt-xml-attr boolean-expr id)

(opt-xml-attr boolean-expr id expr)

Syntactic shorthand for including an optional XML attribute. The full three-argument form expands to:

(if boolean-expr

(xml-attrs [id ,expr])

(xml-attrs))

The two- and one-argument forms are specialisations of the above. The two-argument form expands to:

(if boolean-expr

(xml-attrs [id ,id])

(xml-attrs))

and the one-argument form expands to:

(if id

(xml-attrs [id ,id])

(xml-attrs))

Examples:

> (xml->string      (xml ,@(for/list ([item (in-range 1 4)])               (define class (if (even? item) "even" #f))               (xml (li (@ ,(opt-xml-attr class)) "Item " ,item)))))

"<li>Item 1</li><li class=\"even\">Item 2</li><li>Item 3</li>"

1.2 Rendering XML and sending XML responses

(require (planet untyped/mirrors/xml/xml))

1.2.1 Rendering XML in string form

(xml->string val) → string?

val : xml?

Renders an XML item as a compact string, with no line breaks and no indentation.

Mirrors does not contain a procedure for rendering XML as a multi-line string. This is largely because such a facility would be at odds with the pre-rendering behaviour of the xml macro. Please email the author if you feel this feature would be useful. If you want to debug the XML or XHTML output of our web application, you may want to try one of the variety of HTML and XML prettification add-ons that are available for Firefox.

1.2.2 Sending HTTP responses with XML and XHTML content

The PLT web server has built-in support for the “xexpr” representation of the PLT xml package. This lets you write request handling procedures in short-hand:

#lang scheme/base

(require web-server/servlet

xml/xml)

; request -> xexpr

(define (start initial-request)

'(head (body "Hello world.")))

instead of manually creating an HTTP response using make-respone/full:

#lang scheme/base

(require web-server/servlet

xml/xml)

; request -> response

(define (start initial-request)

(make-response/full

200

"Okay"

(current-seconds)

#"text/html; charset=utf-8"

null

(list (xexpr->string '(head (body "Hello world."))))))

Naturally, the PLT web server does not have built-in support for Mirrors XML expressions. Mirrors provides a couple of useful procedures to help you send responses:

(make-xml-response  [ #:code code             #:message message             #:seconds seconds             #:mime-type mime-type             #:headers headers]             content)   →   response/full?

code : integer? = 200

message : (U string? bytes?) = #"OK"

seconds : integer? = (current-seconds)

mime-type : (U string? bytes?) = #"text/xml; charset=utf-8"

headers : (alistof symbol? string?) = no-cache-http-headers

content : xml?

Takes an xml expression argument and wraps it in an HTTP response object that can be used with the PLT web server (including procedures such as send/suspend and send/suspend/dispatch). The keyword arguments correspond to the first five arguments of make-response/full.

(make-html-response  [ #:code code             #:message message             #:seconds seconds             #:mime-type mime-type             #:headers headers]             content)   →   response/full?

code : integer? = 200

message : (U string? bytes?) = #"OK"

seconds : integer? = (current-seconds)

mime-type : (U string? bytes?) = #"text/html; charset=utf-8"

headers : (alistof symbol? string?) = no-cache-http-headers

content : xml?

Like make-xml-response but with a default MIME type of "text/html".

1.3 XML utilities

(require (planet untyped/mirrors/xml/util))

The following XML expressions are defined for convenience:

xhtml-1.0-strict-doctype : xml?

The HTML 1.0 transitional DOCTYPE, complete with newline character:

> (display (xml->string xhtml-1.0-strict-doctype))

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

xhtml-1.0-transitional-doctype : xml?

The HTML 1.0 transitional DOCTYPE, complete with newline character:

> (display (xml->string xhtml-1.0-transitional-doctype))

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

xhtml-1.0-frameset-doctype : xml?

The HTML 1.0 frameset DOCTYPE, complete with newline character:

> (display (xml->string xhtml-1.0-frameset-doctype))

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">

(alist->attributes [alistof]) → (listof attribute?)

alistof : symbol? = quotable-value?

Converts an association list to a list of attributes.

1.4 XML abstract syntax tree

(require (planet untyped/mirrors/xml/struct))

The xml and xml* macros expand into trees of structures of the following types. You shouldn’t normally have to manipulate these types explicitly unless you want to build or manipulate XML without the syntax layer:

(struct xml ())

XML data. This is an abstract type: concrete subtypes exist for the XML constructs such as elements, entities, CDATA sections and comments (see below).

(struct (atom xml) (data))

data : quotable-value

An atomic datum. The rendered form of an atom is simply its data, appropriately quoted so it cannot be considered markup:

> (xml->string (make-atom 12345))

"12345"

> (xml->string (make-atom #t))

"yes"

> (xml->string (make-atom "Apples & pears."))

"Apples & pears."

quotable-values include booleans, numbers, strings, symbols, byte strings, SRFI 19 times (UTC and TAI types only) and URLs from the net/url library.

(struct (block xml) (children))

children : (listof xml)

A list of XML nodes. Blocks can be arbitrarily nested, and produce no markup other than that of their children:

> (xml->string (make-block                   (list (make-atom "Apples ")                         (make-atom "&")                         (make-atom " pears."))))

"Apples & pears."

(struct (entity xml) (code))

code : (U integer symbol)

A character entity with a numeric or symbolic code:

> (xml->string (make-entity 12345))

"〹"

> (xml->string (make-entity 'nbsp))

" "

(struct (comment xml) (data))

data : quotable-value

A comment:

> (xml->string (make-comment "Apples & pears"))

"<!--Apples & pears-->"

(struct (cdata xml) (data))

data : quotable-value

A CDATA (unparsed character data) section:

> (xml->string (make-cdata "Apples & pears"))

"<![CDATA[Apples & pears]]>"

(struct (pi xml) (data))

data : quotable-value

A processing instruction:

> (xml->string (make-pi "Apples & pears"))

"<?Apples & pears?>"

(struct (raw xml) (data))

data : quotable-value

A block of raw XML, equivalent to a CDATA section without the opening and closing markup:

> (xml->string (make-raw "<ul><li>Apples</li><li>Pears</li></ul>"))

"<ul><li>Apples</li><li>Pears</li></ul>"

(struct (element xml) (tag attributes child))

tag : symbol

attributes : (listof attribute)

child : xml

An XML element:

> (xml->string (make-element                   'span                   (list (make-attribute 'title "attribute"))                   (make-atom "child element")))

"<span title=\"attribute\">child element</span>"

(struct attribute (name value))

name : symbol

value : quotable-value

An element attribute.