Module "xml"
============

A module for accessing XML data

This module currently implements XML, XPath, XSLT (including some EXSLT
extensions), XML Namespaces and a simple interface for modifying XML data.
 
builtin xml_parse(xml_text);
----------------------------

This function parses the XML text passed as parameter and returns an XML
document handler. This document handler can then be used to access the
data in the XML file using XPATH queries. The XPATH queries are used like
array indexes:

	var xmldoc = xml_parse(file_read("demo.xml"));

	foreach[] i (xmldoc["//@*"].nodes)
		debug "Attribute '$i' has the value '${xmldoc[i].data}'.";

Virtual member variables (.nodes and .data in the example above) are used
to specify what kind of data should be accessed. The following virtual
member variables are defined for read accesses:

	.nodes
		Returns an array with references to all nodes in the XML
		tree which do match the XPATH query. This references are
		auto-generated unique identifiers for the nodes which are
		accepted as array indexes just like xpath queries.
		(The 'i' variable in the example above.)

	.node
		Only the first matching node.

	.type
		The type of the XML node (e.g. "element", "attribute",
		"text", "cdata", etc).

	.name
		The name of the XML node (for element and attribute nodes).

	.path
		An auto-generated xpath query to this XML node.

	.data
		The data associated with the first matching XML node. This
		is the content if the match is an element node or text node
		and the value if the match is an attribute node.

	.xml
		The XML text of the first matching XML node and its child
		nodes.

	.innerxml
		The XML text of the child nodes of the first matching XML
		node.

This member variables (except the .nodes variable) do only use the first
match. It is possible to specify a seperator using an additional virtual
index. Then all matches are included in the result set, seperated by the
specified seperator:

	debug "All attributes: ${xmldoc["//@*"].data.[", "]}";

The following virtual memeber variables are supported for writing:

	.data
	.xml
	.innerxml
		This variables are also available for writing and have
		the same meaning as for read accesses.

	.add_xml_before
	.add_xml_after
		This adds new XML text before or after the found matches.

	.add_xml_top
	.add_xml_bottom
		This adds new XML text as new child nodes before of after
		the child nodes of the found matches.

All write queries modify each found match. In cases such as the following
example you need to use an iterator because it contains a combined
read/write access. Without the iterator, the regex would read the first
match, do the substitution once and write the result to all matches:

	foreach[] i (xmldoc["//@year"].nodes)
		xmldoc[i] =~ s/2004/2005/;

The default behavior - if no virtual member varable is specified - is the
behavior of the .data variable.

It is also possible to remove XML nodes using the 'delete' SPL keyword:

	delete xmldoc["//record[@year < 2005]"];

The 'node handlers' returned by the .nodes and .node variables can also
be used directly to make relative xpath queries. So the following two
code snippets are identical:

	foreach[] n (xmldoc["//data"].nodes)
		debug xmldoc["$n/@value"];

	foreach[] n (xmldoc["//data"].nodes)
		debug n["@value"];

Check out the documents on www.w3.org for a detailed description of XML
and the XPath query language.
 

builtin xml_dump(xmldoc);
-------------------------

This function expects an XML document handler (as returned by xml_parse)
as parameter and creates XML text from it.

The xml is dumped with indenting spaces if the named parameter 'format'
is passed and has a 'true' (non-zero) value.

 

builtin xml_xslt_text(xmldoc, stylesheet, %params);
---------------------------------------------------

This function performs an XSLT transformation:

	var xmldoc = xml_parse(file_read("demo.xml"));
	var stylesheet = xml_parse(file_read("demo.xsl"));

	debug xml_xslt_text(xmldoc, stylesheet, foo: "'bar'");

The first parameter is the handler of XML document to be transformed, as
returned by xml_parse(). The 2nd parameter is the XML document
handler for the XSLT stylesheet.

Parameters for the stylesheet are passed as named function parameters. Note
that the parameters are XPath expressions. I.e. a string constant needs to
be passed with quotes.

The return value is the XML text after the transformation.
 

builtin xml_xslt_xml(xmldoc, stylesheet, %params);
--------------------------------------------------

This function works exactly like xml_xslt_text, but it returns a new
XML document handler.
 

object XmlEx
------------

An instance of this object is thrown on XML parser errors.
 

var XmlEx.description;
~~~~~~~~~~~~~~~~~~~~~~

A description text describing the error.
 
