4.31. Xml::XmlDoc Class

The XmlDoc class provides access to a parsed XML document by wrapping a C xmlDocPtr from libxml2. Currently this class provides read-only access to XML documents; it is possible that this restriction will be removed in future versions of Qore.

Table 4.995. XmlDoc Method Overview

Method

Except?

Description

XmlDoc::constructor()

Y

Creates a new XmlDoc object from an XML string or a Qore hash.

XmlDoc::destructor()

N

Destroys the XmlDoc object.

XmlDoc::copy()

N

Creates a copy of the XmlDoc object.

XmlDoc::evalXPath()

Y

Evaluates an XPath expression and returns a list of matching XmlNode objects.

XmlDoc::getRootElement()

N

Returns an XmlNode object representing the root element of the document, if any exists.

XmlDoc::getVersion()

N

Returns the XML version of the document (normally 1.0).

XmlDoc::toQore()

N

Returns a Qore hash corresponding to the XML data; multiple out-of-order keys are created in order in the returned hash by appending a suffix to the key names.

XmlDoc::toQoreData()

N

Returns a Qore hash corresponding to the XML data; key order is not guaranteed to be maintained as multiple out-or-order keys are merged into the same Qore list.

XmlDoc::toString()

N

Returns the XML string for the XML document.

XmlDoc::validateRelaxNG()

Y

Validates the XML document against a RelaxNG schema; if any errors occur, exceptions are thrown. Not available if HAVE_PARSEXMLWITHRELAXNG is False.

XmlDoc::validateSchema()

Y

Validates the XML document against an XSD schema; if any errors occur, exceptions are thrown. Not available if HAVE_PARSEXMLWITHSCHEMA is False.


4.31.1. XmlDoc::constructor()

Synopsis

Creates a new XmlDoc object from the XML string or Qore hash valus passed. If a Qore hash value is passed, it must have only one top-level key, as the XML string will be created from the hash.

Usage
new XmlDoc(string | hash)
Example
$xd = new XmlDoc($xml);

Table 4.996. Arguments for XmlDoc::constructor()

Argument

Type

Description

string

String

The XML string to use to create the XmlDoc object.

hash

Hash

The Qore hash will be used to generate the XML string to use to create the XmlDoc object; the Qore hash must have only one top-level key. The XML will be generated according to the rules documented in XML Integration.


Table 4.997. Return Values for XmlDoc::constructor()

Return Type

Description

XmlDoc Object

The new object created.


Table 4.998. Exceptions Thrown by XmlDoc::constructor()

err

desc

XMLDOC-CONSTRUCTOR-ERROR

Missing argument or invalid XML string passed.


Note that if a hash is passed as the argument to the constructor, then the method can throw any of the exceptions documented in makeXMLString().

4.31.2. XmlDoc::destructor()

Synopsis

Destroys the object.

Usage
delete lvalue
Example
delete $xd;

This method does not throw any exceptions.

4.31.3. XmlDoc::copy()

Synopsis

Creates a new XmlDoc object, not based on the original.

Usage
XmlDoc::copy()
Example
$new_gate = $gate.copy();

Table 4.999. Arguments for XmlDoc::copy()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.1000. Return Values for XmlDoc::copy()

Return Type

Description

XmlDoc Object

A new XmlDoc object, not based on the original.


4.31.4. XmlDoc::evalXPath()

Synopsis

Evaluates an XPath expression and returns a list of matching XmlNode objects.

Usage
XmlDoc::evalXPath(xpath_expr)
Example
my $list = $xd.evalXPath("//list[2]");

Table 4.1001. Arguments for XmlDoc::evalXPath()

Argument

Type

Description

xpath_expr

String

The XPath expression to evaluate on the XmlDoc object.


Table 4.1002. Return Values for XmlDoc::evalXPath()

Return Type

Description

List

Returns a list of XmlNode objects that match the XPath expression.


Table 4.1003. Exceptions Thrown by XmlDoc::evalXPath()

err

desc

XMLDOC-EVAL-XPATH-ERROR

Missing XPath expression.

XPATH-CONSTRUCTOR-ERROR

Cannot create XPath context from the XmlDoc object

XPATH-ERROR

An error occured evaluating the XPath expression


4.31.5. XmlDoc::getRootElement()

Synopsis

Returns an XmlNode object representing the root element of the document, if any exists.

Usage
XmlDoc::getRootElement()
Example
my $node = $xd.getRootElement();

Table 4.1004. Arguments for XmlDoc::getRootElement()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.1005. Return Values for XmlDoc::getRootElement()

Return Type

Description

XmlNode object or NOTHING

The XmlNode object for the root element of the XML document, or NOTHING if there is none.


This method does not throw any exceptions.

4.31.6. XmlDoc::getVersion()

Synopsis

Returns the XML version of the contained XML document.

Usage
XmlDoc::getVersion()
Example
my $xmlver = $xd.getVersion();

Table 4.1006. Arguments for XmlDoc::getVersion()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.1007. Return Values for XmlDoc::getVersion()

Return Type

Description

String

The XML version of the contained document (normally "1.0").


This method does not throw any exceptions.

4.31.7. XmlDoc::toQore()

Synopsis

Returns a Qore hash structure correponding to the XML data contained by the XmlDoc object. If duplicate, out-of-order XML elements are found in the input string, they are deserialized to Qore hash elements with the same name as the XML element but including a caret "^" and a numeric prefix to maintain the same key order in the Qore hash as in the input XML string.

For a similar method not preserving the order of keys in the XML in the resulting Qore hash by collapsing all elements at the same level with the same name to the same Qore list, see XmlDoc::toQoreData(). See also parseXMLAsData() and parseXML().

Usage
XmlDoc::toQore()
Example
my $h = $xd.toQore();

Table 4.1008. Arguments for XmlDoc::toQore()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.1009. Return Values for XmlDoc::toQore()

Return Type

Description

String

The Qore hash corresponding to the data contained in the XML document with out-oforder keys preserved by appending a suffix to hash keys.


This method does not throw any exceptions.

4.31.8. XmlDoc::toQoreData()

Synopsis

Returns a Qore hash structure corresponding to the XML data contained by the XmlDoc object; does not preserve hash order with out-of-order duplicate keys: collapses all to the same list.

Note that data deserialized with this function may not be reserialized to the same input XML string due to the fact that duplicate, out-of-order XML elements are collapsed into lists in the resulting Qore hash, thereby losing the order in the original XML string.

For a similar method preserving the order of keys in the XML in the resulting Qore hash by generating Qore hash element names with numeric suffixes, see XmlDoc::toQore(). See also parseXMLAsData() and parseXML().

Usage
XmlDoc::toQoreData()
Example
my $h = $xd.toQoreData();

Table 4.1010. Arguments for XmlDoc::toQoreData()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.1011. Return Values for XmlDoc::toQoreData()

Return Type

Description

String

The Qore hash corresponding to the data contained in the XML document; out-of-order keys are not preserved but are instead collapsed to the same Qore list.


This method does not throw any exceptions.

4.31.9. XmlDoc::toString()

Synopsis

Returns the XML string for the XML document

Usage
XmlDoc::toString()
Example
my $xmlstr = $xd.toString();

Table 4.1012. Arguments for XmlDoc::toString()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.1013. Return Values for XmlDoc::toString()

Return Type

Description

String

The XML string contained by the XmlDoc object.


This method does not throw any exceptions.

4.31.10. XmlDoc::validateRelaxNG()

Synopsis

Validates the XML document against a RelaxNG schema; if any errors occur, exceptions are thrown.

The availability of this function depends on the presence of libxml2's xmlTextReaderRelaxNGSetSchema() function when Qore was compiled; for maximum portability check the constant HAVE_PARSEXMLWITHRELAXNG before running this method. See Library Option Constants for a list of all option constants.

Usage
XmlDoc::validateRelaxNG(relaxng_schema)
Example
$xd.validateRelaxNG($relaxng);

Table 4.1014. Arguments for XmlDoc::validateRelaxNG()

Argument

Type

Description

relaxng_schema

String

The RelaxNG schema to use to validate the XmlDoc object.


Table 4.1015. Return Values for XmlDoc::validateRelaxNG()

Return Type

Description

n/a

This method does not return any value; if there are any errors, an appropriate exception is thrown.


Table 4.1016. Exceptions Thrown by XmlDoc::validateRelaxNG()

err

desc

XMLDOC-VALIDATERELAXNG-ERROR

Missing RelaxNG schema string.

RELAXNG-ERROR

The RelaxNG schema could not be parsed.

XML-RELAXNG-PARSE-ERROR

The XML document failed RelaxNG validation.

MISSING-FEATURE-ERROR

This exception is thrown when the function is not available; for maximum portability, check the constant HAVE_PARSEXMLWITHRELAXNG before calling this function.


4.31.11. XmlDoc::validateSchema()

Synopsis

Validates the XML document against an XSD schema; if any errors occur, exceptions are thrown.

The availability of this function depends on the presence of libxml2's xmlTextReaderSetSchema() function when Qore was compiled; for maximum portability check the constant HAVE_PARSEXMLWITHSCHEMA before running this function. See Library Option Constants for a list of all option constants.

Usage
XmlDoc::validateSchema(xsd)
Example
$xd.validateSchema($xsd);

Table 4.1017. Arguments for XmlDoc::validateSchema()

Argument

Type

Description

xsd

String

The XSD schema to use to validate the XmlDoc object.


Table 4.1018. Return Values for XmlDoc::validateSchema()

Return Type

Description

n/a

This method does not return any value; if there are any errors, an appropriate exception is thrown.


Table 4.1019. Exceptions Thrown by XmlDoc::validateSchema()

err

desc

XMLDOC-VALIDATESCHEMA-ERROR

Missing XSD schema string.

SCHEMA-ERROR

The XSD schema could not be parsed.

XML-SCHEMA-PARSE-ERROR

The XML document failed XSD schema validation.

MISSING-FEATURE-ERROR

This exception is thrown when the function is not available; for maximum portability, check the constant HAVE_PARSEXMLWITHSCHEMA before calling this function.