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.994. 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. | |
N | Returns an XmlNode object representing the root element of the document, if any exists. | |
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. | |
Y | Validates the XML document against an XSD schema; if any errors occur, exceptions are thrown. |
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.
new XmlDoc(string | hash
)
$xd = new XmlDoc($xml);
Table 4.995. Arguments for XmlDoc::constructor()
Argument | Type | Description |
---|---|---|
| String | The XML string to use to create the XmlDoc object. |
| 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.996. Return Values for XmlDoc::constructor()
Return Type | Description |
---|---|
XmlDoc Object | The new object created. |
Table 4.997. 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 lvalue
delete $xd;
This method does not throw any exceptions.
Creates a new XmlDoc object, not based on the original.
XmlDoc::copy()
$new_gate = $gate.copy();
Table 4.998. Arguments for XmlDoc::copy()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.999. Return Values for XmlDoc::copy()
Return Type | Description |
---|---|
XmlDoc Object | A new XmlDoc object, not based on the original. |
Table 4.1000. Arguments for XmlDoc::evalXPath()
Argument | Type | Description |
---|---|---|
| String | The XPath expression to evaluate on the XmlDoc object. |
Table 4.1001. Return Values for XmlDoc::evalXPath()
Return Type | Description |
---|---|
List | Returns a list of XmlNode objects that match the XPath expression. |
Table 4.1002. 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.
XmlDoc::getRootElement()
my $node = $xd.getRootElement();
Table 4.1003. Arguments for XmlDoc::getRootElement()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
This method does not throw any exceptions.
Returns the XML version of the contained XML document.
XmlDoc::getVersion()
my $xmlver = $xd.getVersion();
Table 4.1005. Arguments for XmlDoc::getVersion()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.1006. 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.
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 collapsiong 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()
my $h = $xd.toQore();
Table 4.1007. Arguments for XmlDoc::toQore()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.1008. 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.
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()
my $h = $xd.toQoreData();
Table 4.1009. Arguments for XmlDoc::toQoreData()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.1010. 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.
Returns the XML string for the XML document
XmlDoc::toString()
my $xmlstr = $xd.toString();
Table 4.1011. Arguments for XmlDoc::toString()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.1012. Return Values for XmlDoc::toString()
Return Type | Description |
---|---|
String | 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.
XmlDoc::validateRelaxNG(relaxng_schema
)
$xd.validateRelaxNG($relaxng);
Table 4.1013. Arguments for XmlDoc::validateRelaxNG()
Argument | Type | Description |
---|---|---|
| String | The RelaxNG schema to use to validate the XmlDoc object. |
Table 4.1014. 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.1015. Exceptions Thrown by XmlDoc::validateRelaxNG()
err | desc |
---|---|
| Missing RelaxNG schema string. |
| The RelaxNG schema could not be parsed. |
| The XML document failed RelaxNG validation. |
Validates the XML document against an XSD schema; if any errors occur, exceptions are thrown.
XmlDoc::validateSchema(xsd
)
$xd.validateSchema($xsd);
Table 4.1016. Arguments for XmlDoc::validateSchema()
Argument | Type | Description |
---|---|---|
| String | The XSD schema to use to validate the XmlDoc object. |
Table 4.1017. 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.1018. 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. |