Qore::Xml::XmlDoc Class Reference

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

#include <QC_XmlDoc.dox.h>

Public Member Methods
	constructor (hash data, *hash opts)
	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 (int pflags=XPF_PRESERVE_ORDER)
	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 (*int pflags)
	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	validateDtd (string dtd)
	Validates the XML document against a DTD; if any errors occur, exceptions are thrown.
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

constructor() [1/2]

Qore::Xml::XmlDoc::constructor	(	hash	data,
		*hash	opts
	)

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
opts	optional formatting and other serialization settings; see XML Generation Options for more information

Example:

XmlDoc xd(hash); 

Exceptions

XMLDOC-CONSTRUCTOR-ERROR	error parsing XML string
MAKE-XML-ERROR	An error occurred serializing the Qore data to an XML string
MAKE-XML-OPTS-INVALID	the opts hash passed is not valid; see XML Generation Options for more information

constructor() [2/2]

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:

XmlDoc xd(xml); 

Exceptions

XMLDOC-CONSTRUCTOR-ERROR

error parsing XML string

copy()

Qore::Xml::XmlDoc::copy

(

)

Returns a copy of the current object.

Returns

a copy of the current object

Example:

XmlDoc xdcopy = xd.copy(); 

evalXPath()

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:

list list = xd.evalXPath("//list[2]"); 

getRootElement()

*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:

*XmlNode xn = xd.getRootElement(); 

getVersion()

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:

string xmlver = xd.getVersion(); 

toQore()

hash Qore::Xml::XmlDoc::toQore

(

int

pflags = XPF_PRESERVE_ORDER

)

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.

Code Flags:

RET_VALUE_ONLY

Example:

hash h = xd.toQore(); 

Returns a hash structure correponding to the XML data contained by the XmlDoc object.

Parameters

pflags

XML parsing flags; see XML Parsing Constants for more information; note that this method assumes XPF_PRESERVE_ORDER for backwards-compatibility

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

See also

• parse_xml()
• XmlDoc::toQoreData()

toQoreData()

hash Qore::Xml::XmlDoc::toQoreData

(

*int

pflags

)

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.

Code Flags:

RET_VALUE_ONLY

Example:

hash h = xd.toQoreData(); 

Parameters

pflags

XML parsing flags; see XML Parsing Constants for more information;

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

See also

• parse_xml()
• XmlDoc::toQore()

toString()

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:

string xml = xd.toString(); 

Exceptions

XML-DOC-TOSTRING-ERROR

an error occurred converting the XmlDoc object to an XML string

validateDtd()

nothing Qore::Xml::XmlDoc::validateDtd

(

string

dtd

)

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

Example:

xd.validateDtd(dtd);

Parameters

dtd	the DTD to use to validate the XmlDoc object

Exceptions

DTD-SYNTAX-ERROR	invalid DTD string
DTD-VALIDATION-ERROR	the DTD did not pass validation

validateRelaxNG()

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); 

validateSchema()

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 XSD 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:

• QC_XmlDoc.dox.h