2.2 Generating XML Strings

2.2 Generating XML Strings🔗ℹ

The scribble/html/xml provides functions for XML representations that XML-render to string form via output-xml or xml->string.

procedure
(output-xml content [port]) → void?
content : outputable/c
port : output-port? = (current-output-port)

Renders content in the same way as output, but using the value of xml-writer as the current writer so that special characters are escaped as needed.

procedure
(xml->string content) → string?
content : outputable/c

Renders content to a string via output-xml.

parameter
(xml-writer) → ((string? output-port? . -> . void))
(xml-writer writer) → void?
writer : ((string? output-port? . -> . void))

A parameter for a function that is used with with-writer by output-xml. The default value is a function that escapes &, <, >, and " to entity form.

procedure
(make-element tag attrs content)
→ (and/c procedure outputable/c?)
  tag : symbol?
  attrs : (listof (cons/c symbol? outputable/c))
  content : outputable/c

Produces a value that XML-renders as XML for the given tag, attributes, and content.

When an attribute in attrs is mapped to #f, then it is skipped. When an attribute is mapped to #t, then it is rendered as present, but without a value.

Examples:

> (output-xml (make-element 'b '() '("Try" #\space "Racket")))
<b>Try Racket</b>
> (output-xml (make-element 'a '((href . "http://racket-lang.org")) "Racket"))
<a href="http://racket-lang.org">Racket</a>
> (output-xml (make-element 'div '((class . "big") (overlay . #t)) "example"))
<div class="big" overlay>example</div>

procedure
(element tag attrs-and-content ...)
→ (and procedure outputable/c?)
tag : symbol?
attrs-and-content : any/c

Like make-element, but the list of attrs-and-content is parsed via attributes+body to separate the attributes and content.

Examples:

> (output-xml (element 'b "Try" #\space "Racket"))
<b>Try Racket</b>
> (output-xml (element 'a 'href: "http://racket-lang.org" "Racket"))
<a href="http://racket-lang.org">Racket</a>
> (output-xml (element 'div 'class: "big" 'overlay: #t "example"))
<div class="big" overlay>example</div>
> (require scribble/html)
> (output-xml (element 'div class: "big" overlay: #t "example"))
<div class="big" overlay>example</div>

procedure
(element/not-empty tag
attrs-and-content ...)
→ (and/c procedure? outputable/c)
tag : symbol?
attrs-and-content : any/c

Like element, but the result always renders with an separate closing tag.

Examples:

> (output-xml (element 'span))
<span />
> (output-xml (element/not-empty 'span))
<span></span>

procedure
(attribute? v) → (or/c #f symbol?)
v : any/c

Returns a symbol without if v is a symbol that ends with :, #f otherwise. When a symbol is returned, it is the same as v, but without the trailing :.

Examples:

> (attribute? 'a:)
'a
> (attribute? 'a)
#f
> (require scribble/html)
> (attribute? a:)
'a

procedure
(attributes+body lst) →
(listof (cons/c symbol? any/c)) list?
lst : list?

Parses lst into an association list mapping attributes to list elements plus a list of remaining elements. The first even-positioned (counting from 0) non-attribute? element of lst is the start of the “remaining elements” list, while each preceding even-positioned attribute is mapped in the association list to the immediately following element of lst. In the association list, the trailing : is stripped for each attribute.

procedure
(split-attributes+body lst) →
list? list?
lst : list?

Like attributes+body, but produces a flat list (of alternating attributes and value) instead of an association list as the first result.

procedure
(literal content ...) → procedure?
content : any/c

Produces a value that XML-renders without escapes for special characters.

Examples:

> (output-xml (literal "a->b"))
a->b
> (output-xml "a->b")
a->b

procedure
(entity v) → procedure?
v : (or/c exact-integer? symbol?)

Produces a value that XML-renders as a numeric or symbolic entity.

Example:

> (output-xml (entity 'gt))
>

procedure
(comment content ... [#:newlines? newlines?]) → procedure?
content : outputable/c
newlines? : any/c = #f

Produces a value that XML-renders as a comment with literal content. If newlines? is true, then newlines are inserted before and after the content.

Example:

> (output-xml (comment "testing" 1 2 3))

procedure
(cdata content
...
[ #:newlines? newlines?
#:line-pfx line-pfx]) → procedure?
  content : outputable/c
  newlines? : any/c = #t
  line-pfx : any/c = #f

Produces a value that XML-renders as CDATA with literal content. If newlines? is true, then newlines are inserted before and after the content. The line-pfx value is rendered before the CDATA opening and closing markers.

Example:

> (output-xml (cdata "testing" 1 2 3))
<![CDATA[
testing123
]]>

syntax
(define/provide-elements/empty tag-id ...)

Defines and exports tag-id as a function that is like element, but with 'tag-id added as the first argument.

syntax
(define/provide-elements/not-empty tag-id ...)

Defines and exports tag-id as a function that is like element/not-empty, but with 'tag-id added as the first argument.

syntax
(define/provide-entities entity-id ...)

Defines and exports entity-id as the result of (entity 'entity-id).

2.1	Generating HTML Strings
2.2	Generating XML Strings
2.3	HTML Resources