Qore XML Module  1.5
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 Methods

 constructor (hash data, *hash opts)
 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 (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. More...
 
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. More...
 
string toString ()
 Returns the XML string for the XmlDoc object. More...
 
nothing validateDtd (string dtd)
 Validates the XML document against a DTD; if any errors occur, exceptions are thrown. 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

◆ constructor() [1/2]

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

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
optsoptional formatting and other serialization settings; see XML Generation Options for more information
Example:
XmlDoc xd(hash);
Exceptions
XMLDOC-CONSTRUCTOR-ERRORerror parsing XML string
MAKE-XML-ERRORAn error occurred serializing the Qore data to an XML string
MAKE-XML-OPTS-INVALIDthe 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
xmlthe XML string to use as a basis for the XmlDoc object
Example:
XmlDoc xd(xml);
Exceptions
XMLDOC-CONSTRUCTOR-ERRORerror 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
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:
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
pflagsXML 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-EXCEPTIONerror parsing XML string
See also

◆ 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
pflagsXML 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-EXCEPTIONerror parsing XML string
See also

◆ 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-ERRORlibxml2 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-ERRORan 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
dtdthe DTD to use to validate the XmlDoc object
Exceptions
DTD-SYNTAX-ERRORinvalid DTD string
DTD-VALIDATION-ERRORthe 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
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);

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