Qore XML Module  1.1
 All Classes Namespaces Functions Variables Groups
Qore::Xml::XmlDoc Class Reference

The XmlDoc class provides access to a parsed XML document by wrapping a C xmlDocPtr from libxml2 More...

Public Member Functions

 constructor (hash data)
 creates a new XmlDoc object from the hash value passed More...
 
 constructor (string xml)
 a new XmlDoc object from the XML string passed More...
 
 copy ()
 Returns a copy of the current object. More...
 
list evalXPath (string xpath)
 Evaluates an XPath expression and returns a list of matching XmlNode objects. More...
 
*XmlNode getRootElement ()
 Returns an XmlNode object representing the root element of the document, if any exists, otherwise returns NOTHING. More...
 
string getVersion ()
 Returns the XML version of the contained XML document. More...
 
hash toQore ()
 Returns a hash corresponding to the data contained in the XML document with out-of-order keys preserved by appending a suffix to hash keys. More...
 
hash toQoreData ()
 Returns a 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. More...
 
string toString ()
 Returns the XML string for the XmlDoc object. More...
 
nothing validateRelaxNG (string relaxng)
 Validates the XML document against a RelaxNG schema; if any errors occur, exceptions are thrown. More...
 
nothing validateSchema (string xsd)
 Validates the XML document against an XSD schema; if any errors occur, exceptions are thrown. More...
 

Detailed Description

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 the xml module.

Member Function Documentation

Qore::Xml::XmlDoc::constructor ( hash  data)

creates a new XmlDoc object from the hash value passed

Parameters
datathe must have only one top-level key, as the XML string that will be used for the XmlDoc object will be created directly from the hash
Example:
my XmlDoc $xd($hash);
Exceptions
XMLDOC-CONSTRUCTOR-ERRORerror parsing XML string
Qore::Xml::XmlDoc::constructor ( string  xml)

a new XmlDoc object from the XML string passed

Parameters
xmlthe XML string to use as a basis for the XmlDoc object
Example:
my XmlDoc $xd($xml);
Qore::Xml::XmlDoc::copy ( )

Returns a copy of the current object.

Returns
a copy of the current object
Example:
my XmlDoc $xdcopy = $xd.copy();
list Qore::Xml::XmlDoc::evalXPath ( string  xpath)

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

Code Flags:
RET_VALUE_ONLY
Parameters
xpaththe XPath expression to evaluate against the XmlDoc object
Returns
a list of XmlNode object matching the XPath expression passed as an argument
Exceptions
XPATH-CONSTRUCTOR-ERRORcannot create XPath context from the XmlDoc object (ex: syntax error in xpath string)
XPATH-ERRORan error occured evaluating the XPath expression
Example:
my list $list = $xd.evalXPath("//list[2]");
*XmlNode Qore::Xml::XmlDoc::getRootElement ( )

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

Returns
an XmlNode object representing the root element of the document, if any exists, otherwise returns NOTHING
Code Flags:
CONSTANT
Example:
my *XmlNode $xn = $xd.getRootElement();
string Qore::Xml::XmlDoc::getVersion ( )

Returns the XML version of the contained XML document.

Returns
the XML version of the contained XML document (normally "1.0")
Code Flags:
CONSTANT
Example:
my string $xmlver = $xd.getVersion();
hash Qore::Xml::XmlDoc::toQore ( )

Returns a hash corresponding to the data contained in the XML document with out-of-order keys preserved by appending a suffix to hash keys.

Returns a 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 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 hash as in the input XML string.

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

Returns
a hash corresponding to the data contained in the XML document with out-of-order keys preserved by appending a suffix to hash keys
Exceptions
PARSE-XML-EXCEPTIONerror parsing XML string
Code Flags:
RET_VALUE_ONLY
Example:
my hash $h = $xd.toQore();
See Also
parseXMLAsData() and parseXML()
hash Qore::Xml::XmlDoc::toQoreData ( )

Returns a 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.

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().

Returns
a 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
Exceptions
PARSE-XML-EXCEPTIONerror parsing XML string
Code Flags:
RET_VALUE_ONLY
Example:
my hash $h = $xd.toQoreData();
See Also
parseXMLAsData() and parseXML()
string Qore::Xml::XmlDoc::toString ( )

Returns the XML string for the XmlDoc object.

Returns
the XML string for the XmlDoc object
Exceptions
XML-DOC-TOSTRING-ERRORlibxml2 reported an error while attempting to export the XmlDoc object's contents as an XML string
Code Flags:
RET_VALUE_ONLY
Example:
my string $xml = $xd.toString();
Exceptions
XML-DOC-TOSTRING-ERRORan error occurred converting the XmlDoc object to an XML string
nothing Qore::Xml::XmlDoc::validateRelaxNG ( string  relaxng)

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 this module was compiled; for maximum portability check the constant HAVE_PARSEXMLWITHRELAXNG before running this method.

Parameters
relaxngthe RelaxNG schema to use to validate the XmlDoc object
Exceptions
MISSING-FEATURE-ERRORthis exception is thrown when the function is not available; for maximum portability, check the constant HAVE_PARSEXMLWITHRELAXNG before calling this function
RELAXNG-SYNTAX-ERRORinvalid RelaxNG string
RELAXNG-INTERNAL-ERRORlibxml2 returned an internal error code while validating the document against the RelaxNG schema
RELAXNG-ERRORThe document failed RelaxNG validation
Example:
$xd.validateRelaxNG($relaxng);
nothing Qore::Xml::XmlDoc::validateSchema ( string  xsd)

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 this module was compiled; for maximum portability check the constant Module Option Constants HAVE_PARSEXMLWITHSCHEMA before running this function

Parameters
xsdthe XSD schema to use to validate the XmlDoc object
Exceptions
MISSING-FEATURE-ERRORthis exception is thrown when the function is not available; for maximum portability, check the constant HAVE_PARSEXMLWITHSCHEMA before calling this function
XSD-SYNTAX-ERRORthe RelaxNG schema string could not be parsed
XSD-INTERNAL-ERRORlibxml2 returned an internal error code while validating the document against the XSD schema
XSD-ERRORThe document failed XSD validation
Example:
$xd.validateSchema($xsd);

The documentation for this class was generated from the following file: