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
	constructor (string xml)
	a new XmlDoc object from the XML string passed
	copy ()
	Returns a copy of the current object.
list	evalXPath (string xpath)
	Evaluates an XPath expression and returns a list of matching XmlNode objects.
*XmlNode	getRootElement ()
	Returns an XmlNode object representing the root element of the document, if any exists, otherwise returns `NOTHING`.
string	getVersion ()
	Returns the XML version of the contained XML document.
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.
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.
string	toString ()
	Returns the XML string for the XmlDoc object.
nothing	validateRelaxNG (string relaxng)
	Validates the XML document against a RelaxNG schema; if any errors occur, exceptions are thrown.
nothing	validateSchema (string xsd)
	Validates the XML document against an XSD schema; if any errors occur, exceptions are thrown.

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:

data	the 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-ERROR error parsing XML string

Qore::Xml::XmlDoc::constructor ( string xml )

a new XmlDoc object from the XML string passed

Parameters:

xml	the 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:

xpath the 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-ERROR	cannot create XPath context from the XmlDoc object (ex: syntax error in xpath string)
XPATH-ERROR	an 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-EXCEPTION error 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-EXCEPTION error 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-ERROR libxml2 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-ERROR an 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:

relaxng the RelaxNG schema to use to validate the XmlDoc object

Exceptions:

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
RELAXNG-SYNTAX-ERROR	invalid RelaxNG string
RELAXNG-INTERNAL-ERROR	libxml2 returned an internal error code while validating the document against the RelaxNG schema
RELAXNG-ERROR	The 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:

xsd	the XSD schema to use to validate the XmlDoc object

Exceptions:

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
XSD-SYNTAX-ERROR	the RelaxNG schema string could not be parsed
XSD-INTERNAL-ERROR	libxml2 returned an internal error code while validating the document against the XSD schema
XSD-ERROR	The document failed XSD validation

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

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

/Users/david/src/qore/svn/module-xml/trunk/src/QC_XmlDoc.dox.h

Public Member Functions

Detailed Description

Member Function Documentation