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

  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 | ( | 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:
  my 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()

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:
  my 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()

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/git/module-xml/src/QC_XmlDoc.dox.h