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

  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:

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