# SPL Module Reference: xml

load "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);
builtin xml_dump(xmldoc);
builtin xml_xslt_text(xmldoc, stylesheet, %params);
builtin xml_xslt_xml(xmldoc, stylesheet, %params);

object XmlEx
{
var description;
}

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.

Generated by SPLDOC. | http://www.clifford.at/spl/