Qore XML Module: Qore::Xml::XmlDoc Class Reference

Qore XML Module 1.1

- Main Page
- Modules
- Namespaces
- Classes

- Class List
- Class Members

All Classes Namespaces Functions Variables Groups
Public Member Functions | List of all members
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 ()
| 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 ()
| 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 | ( |  | ) |

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