1 XML
2 Javascript
On this page:
1.1 XML syntax
xml
xml*
xml-attrs
1.2 Rendering XML and sending XML responses
1.2.1 Rendering XML in string form
xml->string
1.2.2 Sending HTTP responses with XML and XHTML content
make-xml-response
make-html-response
1.3 XML utilities
xhtml-1.0-strict-doctype
xhtml-1.0-transitional-doctype
xhtml-1.0-frameset-doctype
no-cache-http-headers
alist->attributes
1.4 XML abstract syntax tree
xml
atom
block
entity
comment
cdata
pi
raw
element
attribute
Version: 3.99.0.23

 

1 XML

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

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

 

 

|

 

(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)

 

 

 

 

 

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. For example:

  > (let ([content "content"])

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

  #(struct:block

    (#(struct:raw

       ("<span title=\"title\">"))

     #(struct:atom "content")

     #(struct:raw ("</span>"))))

(xml* xml-expr ...)

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

  > (let ([content "content"])

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

  #(struct:element

    span

    (#(struct:attribute

       title

       #(struct:atom "title")))

    #(struct:atom "content"))

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

(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>"

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

  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.

(make-html-response

 [

#:code code

 

 

 

 

 

 

#:message message

 

 

 

 

 

 

#:seconds seconds

 

 

 

 

 

 

#:mime-type mime-type

 

 

 

 

 

 

#:headers headers]

 

 

 

 

 

 

content)

 

 

response

  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:

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

no-cache-http-headers : (listof header?)

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

(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 &amp; pears."

quotable-values include booleans, numbers, strings, symbols, byte strings 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 &amp; pears."

(struct

 

(entity xml)

 

(code))

  code : (U integer symbol)

A character entity with a numeric or symbolic code:

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

  "&#12345;"

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

  "&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.