2.2 Generating XML Strings

► |  | Scribble as Preprocessor

1 | Text Generation
2 | HTML Generation
| Index

▼ | 2 | HTML Generation

2.1 | Generating HTML Strings
2.2 | Generating XML Strings
2.3 | HTML Resources

On this page:

output-xml
xml->string
xml-writer
make-element
element
element/ not-empty
attribute?
attributes+ body
split-attributes+ body
literal
entity
comment
cdata
define/ provide-elements/ empty
define/ provide-elements/ not-empty
define/ provide-entities

Racket
top contents ← prev up next →

### 2.2 Generating XML Strings🔗ℹ

(require scribble/html/xml) | package: scribble-html-lib

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-&gt;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))
> &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))
> <!--testing123-->

> > 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).
top contents ← prev up next →