You are looking at historical revision 18816 of this page. It may differ significantly from its current revision.

sxml-serializer

Serialize SXML to XML and HTML.

Overview

The SXML serializer writes SXML documents to a port, filename or string as XML or HTML. It supports comment nodes, processing instruction nodes, namespace nodes and ampersand entities such as (& 955). As an example, you can parse an XML document with the ssax egg using ssax:xml->sxml and write a valid copy back out with serialize-sxml.

Please refer to the serialization section of the SXML tools tutorial for further discussion and examples. We have made some changes to the interface, but it is close enough and the serialization results are the same.

Interface

[procedure] (serialize-sxml doc #!key keys)

Serialize the SXML document DOC, an SXML node or nodeset, to XML or HTML. Returns the result string if the serialization was done to a string, or an unspecified value if serializing to file or port.

serialize-sxml accepts the following keyword arguments:

output

[default #f] An output port or filename to write the output to, or #f to write it to a string.

cdata-section-elements

[default '()] A list of SXML element names, as symbols, which will have their contents serialized to CDATA.

indent

[default, two spaces] Indentation level to apply to XML elements, as a string or #f. When a string, a newline is written when a new tag is opened, and the tag is indented by printing the string x times for indentation level x. When #f, indentation is totally disabled and no newline is printed. To print all tags left-aligned, use the empty string.

method

[default 'xml] Serialization method, 'xml or 'html. When 'html, an end-tag is not output for empty HTML elements; character escaping is not performed for the content of script and style elements; "<" characters in attribute values are not escaped; whitespace is not added inside a formatted element; and boolean attributes are output in minimized form. HTML output is provided for completeness; using sxml-transforms may give better results.

ns-prefixes

[default conventional-ns-prefixes] An alist mapping namespace prefixes (symbols) to URIs, which allows the application to specify the mapping between namespace URIs and the corresponding namespace prefixes to be used for serialization. When no namespace prefix assignment is provided for some namespace URI, the serializer generates an XML prefix name by itself. This is the analogue of the namespace prefix alist in the ssax:xml->sxml parser, but allows you to add mappings not provided at original parse time.

[constant] conventional-ns-prefixes

An alist mapping well-known namespace prefixes to URIs. Typically used when augmenting the serializer's existing namespace map:

;; add zb: to list of existing namespaces
(serialize-sxml doc ns-prefixes: `((zb . "http://3e8.org/zb")
                                   ,@conventional-ns-prefixes))

Changes from stock

• srl:parameterizable has been renamed to serialize-sxml and it now uses keyword arguments instead of (key . value) pairs.
• The optional port-or-filename argument became the output keyword. The ns-prefix-assig option was renamed to ns-prefixes. Otherwise, keywords retain their original names.
• omit-xml-declaration, standalone and version have been dropped. Add a (*PI* xml "version='1.0'") node to your SXML document instead. The old way didn't support an encoding attribute and will output a duplicate declaration if there already is one in your SXML document.
• srl:conventional-ns-prefixes had its srl: prefix stripped, and it contains many more prefixes.
• srl:sxml->xml and srl:sxml->xml-noindent (and their html variants) were dropped as they provide little benefit over serialize-sxml:

(srl:sxml->xml doc)          ==> (serialize-sxml doc)
(srl:sxml->xml-noindent doc) ==> (serialize-sxml doc indent: #f)
(srl:sxml->html doc)         ==> (serialize-sxml doc method: 'html)

Limitations

The serializer does not support setting the default XML namespace via xmlns="...", so if you read in a document that uses a default namespace, upon writing it back out its elements will be fully qualified. This is perfectly legal but verbose and, conceivably, some parsers may not like the result.

About this egg

Author

Dmitry Lizorkin wrote the bulk of the code. The Chicken port is by Jim Ursetto.

Version history

0.1

Initial import from sxml-tools CVS 1.7 @ Fri Nov 7 08:36:28 2008 UTC

License

BSD. The serializer code by Dmitry Lizorkin is public domain.