1 XML
The XML language in mirrors allows the programatically assembly of syntactically correct 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:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Builds a block of XML, optimising any chunks of static markup into raw blocks. For example:
| |||||
|
The same as xml except that no markup optimisation is performed:
| ||||||
|
It takes slightly longer to render the XML trees produced with xml* as strings, but the full structure of the tree is preserved.
Builds a list of attribute structures. Useful in conjunction with the unquote-splicing form of attr-expr:
| ||
"<a title=\"title\" href=\"href\">text</a>" |
1.2 Rendering XML and sending XML responses
(require (planet untyped/mirrors/xml/xml)) |
1.2.1 Rendering XML in string form
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:
|
(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:
|
(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:
| ||||||||||||||||||||||||||||||||||||||||||
code : integer = 200 | ||||||||||||||||||||||||||||||||||||||||||
message : string = "OK" | ||||||||||||||||||||||||||||||||||||||||||
seconds : integer = (current-seconds) | ||||||||||||||||||||||||||||||||||||||||||
mime-type : (U string bytes) = #"text/xml; charset=utf-8" | ||||||||||||||||||||||||||||||||||||||||||
headers : (alistof symbol string) = null | ||||||||||||||||||||||||||||||||||||||||||
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.
| ||||||||||||||||||||||||||||||||||||||||||
code : integer = 200 | ||||||||||||||||||||||||||||||||||||||||||
message : string = "OK" | ||||||||||||||||||||||||||||||||||||||||||
seconds : integer = (current-seconds) | ||||||||||||||||||||||||||||||||||||||||||
mime-type : (U string bytes) = #"text/html; charset=utf-8" | ||||||||||||||||||||||||||||||||||||||||||
headers : (alistof symbol string) = null | ||||||||||||||||||||||||||||||||||||||||||
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:
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"> |
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"> |
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"> |
The default HTTP headers generated by make-html-response, make-xml-response and make-js-response, designed to prevent the browser caching any dynamically generated pages:
> (display no-cache-http-headers) |
(#<header> #<header> #<header>) |
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:
|
XML data. This is an abstract type: concrete subtypes exist for the XML constructs such as elements, entities, CDATA sections and comments (see below).
| |||||
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 and URLs from the net/url library.
| |||||
children : (listof xml) |
A list of XML nodes. Blocks can be arbitrarily nested, and produce no markup other than that of their children:
| ||||
"Apples & pears." |
| |||||
code : (U integer symbol) |
A character entity with a numeric or symbolic code:
> (xml->string (make-entity 12345)) |
"〹" |
> (xml->string (make-entity 'nbsp)) |
" " |
| |||||
data : quotable-value |
A comment:
> (xml->string (make-comment "Apples & pears")) |
"<!--Apples & pears-->" |
| |||||
data : quotable-value |
A CDATA (unparsed character data) section:
> (xml->string (make-cdata "Apples & pears")) |
"<![CDATA[Apples & pears]]>" |
| |||||
data : quotable-value |
A processing instruction:
> (xml->string (make-pi "Apples & pears")) |
"<?Apples & pears?>" |
| |||||
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>" |
| |||||
tag : symbol | |||||
attributes : (listof attribute) | |||||
child : xml |
An XML element:
| ||||
"<span title=\"attribute\">child element</span>" |
| |||||
name : symbol | |||||
value : quotable-value |
An element attribute.