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.724. XmlDoc Method Overview
Method | Except? | Description |
|---|---|---|
|
| Y | Creates a new XmlDoc object from an XML string or a Qore hash. |
N | Destroys the XmlDoc object. | |
N | Creates a copy of the XmlDoc object. | |
|
| Y | Evaluates an XPath expression and returns a list of matching XmlNode objects; an empty list is returned if there are no matches. |
|
| N | Returns an XmlNode object representing the root element of the document, if any exists, otherwise returns NOTHING. |
|
| N | Returns the XML version of the document (normally 1.0). |
|
| 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. |
|
| 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. |
|
| N | Returns the XML string for the XML document. |
|
| Y | Validates the XML document against a RelaxNG schema; if any errors occur, exceptions are thrown. Not available if |
|
| Y | Validates the XML document against an XSD schema; if any errors occur, exceptions are thrown. Not available if |
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.
XmlDoc::constructor(string $xml)
XmlDoc::constructor(hash $data)
my XmlDoc $xd($xml);
Table 4.725. Arguments for XmlDoc::constructor()
Argument | Description |
|---|---|
| The XML string to use to create the XmlDoc object. |
| 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.726. Exceptions Thrown by XmlDoc::constructor()
err | desc |
|---|---|
| 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().
Destroys the object.
delete $xd;
This method does not throw any exceptions.
Creates a new XmlDoc object, not based on the original.
my XmlDoc $new_doc = $doc.copy();
Evaluates an XPath expression and returns a list of matching XmlNode objects.
XmlDoc::evalXPath(string $xpath) returns list
my $list = $xd.evalXPath("//list[2]");
Table 4.727. Arguments for XmlDoc::evalXPath()
Argument | Description |
|---|---|
| The XPath expression to evaluate on the XmlDoc object. |
Table 4.729. Exceptions Thrown by XmlDoc::evalXPath()
err | desc |
|---|---|
| Missing XPath expression. |
| Cannot create XPath context from the XmlDoc object |
| An error occured evaluating the XPath expression |
Returns an XmlNode object representing the root element of the document, if any exists, otherwise returns NOTHING.
XmlDoc::getRootElement() returns any
my any $node = $xd.getRootElement();
This method does not throw any exceptions.
Returns the XML version of the contained XML document.
XmlDoc::getVersion() returns string
my string $xmlver = $xd.getVersion();
Table 4.731. Return Values for XmlDoc::getVersion()
Return Type | Description |
|---|---|
The XML version of the contained document (normally "1.0"). |
This method does not throw any exceptions.
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().
XmlDoc::toQore() returns hash
my hash $h = $xd.toQore();
Table 4.732. Return Values for XmlDoc::toQore()
Return Type | Description |
|---|---|
The Qore hash corresponding to the data contained in the XML document with out-of-order keys preserved by appending a suffix to hash keys. |
This method does not throw any exceptions.
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().
XmlDoc::toQoreData() returns hash
my hash $h = $xd.toQoreData();
Table 4.733. Return Values for XmlDoc::toQoreData()
Return Type | Description |
|---|---|
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.
Returns the XML string for the XML document
XmlDoc::toString() returns string
my string $xmlstr = $xd.toString();
Table 4.734. Return Values for XmlDoc::toString()
Return Type | Description |
|---|---|
The XML string contained by the XmlDoc object. |
This method does not throw any exceptions.
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.
XmlDoc::validateRelaxNG(string $relaxng) returns nothing
$xd.validateRelaxNG($relaxng);
Table 4.735. Arguments for XmlDoc::validateRelaxNG()
Argument | Description |
|---|---|
| The RelaxNG schema to use to validate the XmlDoc object. |
Table 4.736. Exceptions Thrown by XmlDoc::validateRelaxNG()
err | desc |
|---|---|
| Missing RelaxNG schema string. |
| The RelaxNG schema could not be parsed. |
| The XML document failed RelaxNG validation. |
| This exception is thrown when the function is not available; for maximum portability, check the constant |
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.
XmlDoc::validateSchema(string $xsd) returns nothing
$xd.validateSchema($xsd);
Table 4.737. Arguments for XmlDoc::validateSchema()
Argument | Description |
|---|---|
| The XSD schema to use to validate the XmlDoc object. |
Table 4.738. Exceptions Thrown by XmlDoc::validateSchema()
err | desc |
|---|---|
| Missing XSD schema string. |
| The XSD schema could not be parsed. |
| The XML document failed XSD schema validation. |
| This exception is thrown when the function is not available; for maximum portability, check the constant |