Qore XML Module: Qore::Xml::XmlReader 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::XmlReader Class Reference

The XmlReader class allows XML strings to be iterated and parsed piecewise. More...

## Public Member Functions
int | attributeCount ()
| Returns the number of attributes of the current node. More...
*string | baseUri ()
| Returns the base URI of the node if known, `NOTHING` if not. More...
| constructor (XmlDoc doc)
| Creates the XmlReader object based on an XmlDoc object. More...
| constructor (string xml)
| Creates the XmlReader object based on the string passed; the string will be converted to UTF-8 encoding before parsing if necessary. More...
| copy ()
| Creates an independent copy of the XmlReader object. More...
int | depth ()
| Returns the depth of the node in the tree. More...
*string | encoding ()
| Returns the encoding string given in the original XML string or `NOTHING` if none is given. More...
*string | getAttribute (string attr)
| Returns the value of the attribute matching the qualified name passed, or `NOTHING` if no such attribute exists in the current XmlReader. More...
*string | getAttributeNs (string attr, string ns)
| Returns the value of the given attribute anchored in the given namespace, or `NOTHING` if no such attribute exists in the current XmlReader. More...
*string | getAttributeOffset (softint offset=0)
| Returns the value of the attribute with the specified index relative to the containing element, or `NOTHING` if no such attribute exists in the current XmlReader. More...
*string | getInnerXml ()
| Returns an XML string of the contents of the all current node's child nodes and markup, or `NOTHING` if the current node is neither an element nor an attribute or has no child nodes. More...
*string | getOuterXml ()
| Return an XML string of the contents of the current node and all child nodes and markup, or `NOTHING` if the current node is neither an element nor an attribute or has no child nodes. More...
bool | hasAttributes ()
| Returns `True` if the node has attributes or `False` if not. More...
bool | hasValue ()
| Returns `True` if the node has a text value or `False` if not. More...
bool | isDefault ()
| Returns `True` if an attribute node was generated from the default value defined in the DTD or schema, `False` if not. More...
bool | isEmptyElement ()
| Returns `True` if the current node is empty or `False` if not. More...
bool | isNamespaceDecl ()
| Returns `True` if the current node is a namespace declaration rather than a regular attribute or `False` if not. More...
bool | isValid ()
| Returns `True` if the current reader parser context is valid, `False` if not. More...
*string | localName ()
| Returns the local name of the node or `NOTHING` if no name is available. More...
*string | lookupNamespace ()
| Returns the default namespace in the scope of the current element, or `NOTHING` if none exists. More...
*string | lookupNamespace (string prefix)
| Returns the namespace corresponding to the given prefix in the scope of the current element, or `NOTHING` if none exists. More...
bool | moveToAttribute (string attr)
| Moves the position of the current instance to the attribute with the specified qualified name. More...
bool | moveToAttributeNs (string attr, string ns)
| Moves the position of the current instance to the attribute with the specified local name and namespace URI. More...
bool | moveToAttributeOffset (softint offset)
| Moves the position of the current instance to the attribute with the specified index relative to the containing element. More...
bool | moveToElement ()
| Moves the position of the current instance to the element node containing the current attribute node. More...
bool | moveToFirstAttribute ()
| Moves the position of the current instance to the first attribute of the current node. More...
bool | moveToNextAttribute ()
| Moves the position of the current instance to the next attribute of the current node. More...
*string | name ()
| Returns the qualified name of the node (`prefix:LocalName`) or `NOTHING` if no name is available. More...
*string | namespaceUri ()
| Returns the URI defining the namespace associated with the node, or `NOTHING` if not available. More...
bool | next ()
| Moves the position of the current instance to the next node in the tree at the same level, skipping any subtree. More...
int | nodeType ()
| Returns the node type of the current node. More...
*string | nodeTypeName ()
| Returns a string giving the node type of the current node or `NOTHING` if no current node is available. More...
*string | prefix ()
| Returns the shorthand reference to the namespace associated with the node, or `NOTHING` if not available. More...
bool | read ()
| Moves the position of the current instance to the next node in the stream. More...
bool | readSkipWhitespace ()
| the position of the current instance to the next node in the stream, skipping any whitespace nodes More...
nothing | relaxNGValidate (string relaxng)
| Set a RelaxNG schema for schema validation while parsing the XML document. More...
nothing | schemaValidate (string xsd)
| Set an XSD schema for schema validation while parsing the XML document. More...
any | toQore ()
| Returns Qore data corresponding to the XML starting at the current node position, maintains element order by mangling node names. More...
any | toQoreData ()
| Returns Qore data corresponding to the XML starting at the current node position, collapses duplicate out of order elements to a list. More...
*string | value ()
| Returns the text value of the node or `NOTHING` if not available. More...
*string | xmlLang ()
| Returns the `xml:lang` scope within which the node resides or `NOTHING` if there is none. More...
*string | xmlVersion ()
| Returns a string giving the XML version of the source document (normally `"1.0"`) or `NOTHING` if none is present. More...

## Detailed Description

The XmlReader class allows XML strings to be iterated and parsed piecewise.

## Member Function Documentation

int Qore::Xml::XmlReader::attributeCount | ( |  | ) |

Returns the number of attributes of the current node.

Returns
  the number of attributes of the current node

Code Flags:
  CONSTANT

Example:
  my int $n = $xr.attributeCount();

*string Qore::Xml::XmlReader::baseUri | ( |  | ) |

Returns the base URI of the node if known, `NOTHING` if not.

Returns
  the base URI of the node if known, `NOTHING` if not.

Code Flags:
  CONSTANT

Example:
  my *string $value = $xmlreader.baseUri();

Qore::Xml::XmlReader::constructor | ( | XmlDoc | doc | ) |

Creates the XmlReader object based on an XmlDoc object.

Exceptions

  XML-READER-ERROR | libxml2 returned an error code when creating the XML reader object

Example:
  my XmlReader $xr($xmldoc);

Qore::Xml::XmlReader::constructor | ( | string | xml | ) |

Creates the XmlReader object based on the string passed; the string will be converted to UTF-8 encoding before parsing if necessary.

Example:
  my XmlReader $xr($xmlstr);

Exceptions

  XML-READER-ERROR | libxml2 returned an error code when creating the XML reader object (ex: XML string could not be parsed)
  ENCODING-CONVERSION-ERROR | the string could not be converted to UTF-8 (usually due to an encoding error in the source string)

Qore::Xml::XmlReader::copy | ( |  | ) |

Creates an independent copy of the XmlReader object.

Returns
  an independent copy of the XmlReader object

Example:
  my XmlReader $xrcopy = $xr.copy();

int Qore::Xml::XmlReader::depth | ( |  | ) |

Returns the depth of the node in the tree.

Returns
  the depth of the node in the tree

Code Flags:
  CONSTANT

Example:
  my int $depth = $xr.depth();

*string Qore::Xml::XmlReader::encoding | ( |  | ) |

Returns the encoding string given in the original XML string or `NOTHING` if none is given.

Returns
  the encoding string given in the original XML string or `NOTHING` if none is given

Code Flags:
  CONSTANT

Example:
  my *string $value = $xmlreader.encoding();

Note
  all XML strings are automatically converted to UTF-8 before parsing

*string Qore::Xml::XmlReader::getAttribute | ( | string | attr | ) |

Returns the value of the attribute matching the qualified name passed, or `NOTHING` if no such attribute exists in the current XmlReader.

Code Flags:
  CONSTANT

Parameters

  attr | the name of the attribute to retrieve

Returns
  the value of the attribute matching the qualified name passed, or `NOTHING` if no such attribute exists in the current XmlReader

Example:
  my *string $value = $xmlreader.getAttribute($name);

See Also
  XmlReader::getAttributeNs()

*string Qore::Xml::XmlReader::getAttributeNs | ( | string | attr,
|  | string | ns
| ) |  |

Returns the value of the given attribute anchored in the given namespace, or `NOTHING` if no such attribute exists in the current XmlReader.

Code Flags:
  CONSTANT

Parameters

  attr | the name of the attribute to retrieve
  ns | the namespace URI of the attribute

Returns
  the value of the given attribute anchored in the given namespace, or `NOTHING` if no such attribute exists in the current XmlReader

Example:
  my *string $value = $xmlreader.getAttributeNs($localname, $namespaceuri);

See Also
  XmlReader::getAttribute()

*string Qore::Xml::XmlReader::getAttributeOffset | ( | softint | offset = `0` | ) |

Returns the value of the attribute with the specified index relative to the containing element, or `NOTHING` if no such attribute exists in the current XmlReader.

Code Flags:
  CONSTANT

Parameters

  offset | the attribute number of the attribute to retrieve relative to the containing element starting from 0

Returns
  the value of the attribute with the specified index relative to the containing element, or `NOTHING` if no such attribute exists in the current XmlReader

Example:
  my *string $value = $xmlreader.getAttributeOffset($offset);

See Also
  XmlReader::getAttribute()

*string Qore::Xml::XmlReader::getInnerXml | ( |  | ) |

Returns an XML string of the contents of the all current node's child nodes and markup, or `NOTHING` if the current node is neither an element nor an attribute or has no child nodes.

Returns
  an XML string of the contents of the all current node's child nodes and markup, or `NOTHING` if the current node is neither an element nor an attribute or has no child nodes

Code Flags:
  CONSTANT

Example:
  my *string $value = $xmlreader.getInnerXml();

See Also
  XmlReader::getOuterXml()

*string Qore::Xml::XmlReader::getOuterXml | ( |  | ) |

Return an XML string of the contents of the current node and all child nodes and markup, or `NOTHING` if the current node is neither an element nor an attribute or has no child nodes.

Returns
  an XML string of the contents of the current node and all child nodes and markup, or `NOTHING` if the current node is neither an element nor an attribute or has no child nodes

Code Flags:
  CONSTANT

Example:
  my *string $value = $xmlreader.getOuterXml();

See Also
  XmlReader::getInnerXml()

bool Qore::Xml::XmlReader::hasAttributes | ( |  | ) |

Returns `True` if the node has attributes or `False` if not.

Returns
  `True` if the node has attributes or `False` if not

Code Flags:
  CONSTANT

Example:
  my bool $b = $xr.hasAttributes();

bool Qore::Xml::XmlReader::hasValue | ( |  | ) |

Returns `True` if the node has a text value or `False` if not.

Returns
  `True` if the node has a text value or `False` if not

Code Flags:
  CONSTANT

Example:
  my bool $b = $xr.hasValue();

bool Qore::Xml::XmlReader::isDefault | ( |  | ) |

Returns `True` if an attribute node was generated from the default value defined in the DTD or schema, `False` if not.

Returns
  `True` if an attribute node was generated from the default value defined in the DTD or schema, `False` if not

Code Flags:
  CONSTANT

Example:
  my bool $b = $xr.isDefault();

bool Qore::Xml::XmlReader::isEmptyElement | ( |  | ) |

Returns `True` if the current node is empty or `False` if not.

Returns
  `True` if the current node is empty or `False` if not

Code Flags:
  CONSTANT

Example:
  my bool $b = $xr.isEmptyElement();

bool Qore::Xml::XmlReader::isNamespaceDecl | ( |  | ) |

Returns `True` if the current node is a namespace declaration rather than a regular attribute or `False` if not.

Returns
  `True` if the current node is a namespace declaration rather than a regular attribute or `False` if not

Code Flags:
  CONSTANT

Example:
  my bool $b = $xr.isNamespaceDecl();

bool Qore::Xml::XmlReader::isValid | ( |  | ) |

Returns `True` if the current reader parser context is valid, `False` if not.

Returns
  `True` if the current reader parser context is valid, `False` if not

Code Flags:
  CONSTANT

Example:
  my bool $b = $xr.isValid();

*string Qore::Xml::XmlReader::localName | ( |  | ) |

Returns the local name of the node or `NOTHING` if no name is available.

Returns
  the local name of the node or `NOTHING` if no name is available

Code Flags:
  CONSTANT

Example:
  my *string $value = $xmlreader.localName();

*string Qore::Xml::XmlReader::lookupNamespace | ( |  | ) |

Returns the default namespace in the scope of the current element, or `NOTHING` if none exists.

Returns
  the default namespace in the scope of the current element, or `NOTHING` if none exists

Code Flags:
  CONSTANT

Example:
  my *string $ns = $xr.lookupNamespace();

*string Qore::Xml::XmlReader::lookupNamespace | ( | string | prefix | ) |

Returns the namespace corresponding to the given prefix in the scope of the current element, or `NOTHING` if none exists.

Code Flags:
  CONSTANT

Parameters

  prefix | the namespace prefix to resolve

Returns
  the namespace corresponding to the given prefix in the scope of the current element, or `NOTHING` if none exists

Example:
  my *string $value = $xmlreader.lookupNamespace($prefix);

bool Qore::Xml::XmlReader::moveToAttribute | ( | string | attr | ) |

Moves the position of the current instance to the attribute with the specified qualified name.

If an XML parsing error occurs, an exception is thrown

Parameters

  attr | the qualified name of the attribute to move to

Returns
  `True` in case of success, `False` if not found

Exceptions

  PARSE-XML-EXCEPTION | error parsing XML

Example:
  my bool $b = $xmlreader.moveToAttribute($name);

See Also
  XmlReader::moveToAttributeNs()

bool Qore::Xml::XmlReader::moveToAttributeNs | ( | string | attr,
|  | string | ns
| ) |  |

Moves the position of the current instance to the attribute with the specified local name and namespace URI.

If an XML parsing error occurs, an exception is thrown

Parameters

  attr | the qualified name of the attribute to move to
  ns | the namespace URI of the attribute

Returns
  `True` in case of success, `False` if not found

Exceptions

  PARSE-XML-EXCEPTION | error parsing XML

Example:
  my bool $b = $xmlreader.moveToAttributeNs($localname, $namespaceuri);

See Also
  XmlReader::moveToAttribute()

bool Qore::Xml::XmlReader::moveToAttributeOffset | ( | softint | offset | ) |

Moves the position of the current instance to the attribute with the specified index relative to the containing element.

If an XML parsing error occurs, an exception is thrown

Parameters

  offset | the index of the attribute relative to the containing element to move to starting with 0

Returns
  `True` in case of success, `False` if not found

Exceptions

  PARSE-XML-EXCEPTION | error parsing XML

Example:
  my bool $b = $xmlreader.moveToAttributeOffset($offset);

See Also
  XmlReader::moveToAttribute()

bool Qore::Xml::XmlReader::moveToElement | ( |  | ) |

Moves the position of the current instance to the element node containing the current attribute node.

If an XML parsing error occurs, an exception is thrown

Returns
  `True` in case of success, `False` if not found

Exceptions

  PARSE-XML-EXCEPTION | error parsing XML

Example:
  my bool $b = $xmlreader.moveToElement();

bool Qore::Xml::XmlReader::moveToFirstAttribute | ( |  | ) |

Moves the position of the current instance to the first attribute of the current node.

If an XML parsing error occurs, an exception is thrown

Returns
  `True` in case of success, `False` if not found

Exceptions

  PARSE-XML-EXCEPTION | error parsing XML

Example:
  my bool $b = $xmlreader.moveToFirstAttribute();

bool Qore::Xml::XmlReader::moveToNextAttribute | ( |  | ) |

Moves the position of the current instance to the next attribute of the current node.

If an XML parsing error occurs, an exception is thrown

Returns
  `True` in case of success, `False` if not found

Exceptions

  PARSE-XML-EXCEPTION | error parsing XML

Example:
  my bool $b = $xmlreader.moveToNextAttribute();

*string Qore::Xml::XmlReader::name | ( |  | ) |

Returns the qualified name of the node (`prefix:LocalName`) or `NOTHING` if no name is available.

Returns
  the qualified name of the node (`prefix:LocalName`) or `NOTHING` if no name is available

Code Flags:
  CONSTANT

Example:
  my *string $value = $xmlreader.name();

See Also
  XmlReader::localName()

*string Qore::Xml::XmlReader::namespaceUri | ( |  | ) |

Returns the URI defining the namespace associated with the node, or `NOTHING` if not available.

Returns
  the URI defining the namespace associated with the node, or `NOTHING` if not available

Code Flags:
  CONSTANT

Example:
  my *string $value = $xmlreader.namespaceUri();

bool Qore::Xml::XmlReader::next | ( |  | ) |

Moves the position of the current instance to the next node in the tree at the same level, skipping any subtree.

If an XML parsing error occurs, an exception is thrown

Returns
  `True` in case of success, `False` if not found

Exceptions

  PARSE-XML-EXCEPTION | error parsing XML

Example:
  my bool $b = $xmlreader.next();

int Qore::Xml::XmlReader::nodeType | ( |  | ) |

Returns the node type of the current node.

Returns
  the node type of the current node; for return values, see XML Node Type Constants

Code Flags:
  CONSTANT

Example:
  my int $nt = $xr.nodeType();

See Also
  NodeTypeMap
  XmlReader::nodeTypeName()

*string Qore::Xml::XmlReader::nodeTypeName | ( |  | ) |

Returns a string giving the node type of the current node or `NOTHING` if no current node is available.

Returns
  a string giving the node type of the current node or `NOTHING` if no current node is available; for possible return values, see the values of the NodeTypeMap

Code Flags:
  CONSTANT

Example:
  my *string $value = $xmlreader.nodeTypeName();

See Also
  XmlReader::nodeType()

*string Qore::Xml::XmlReader::prefix | ( |  | ) |

Returns the shorthand reference to the namespace associated with the node, or `NOTHING` if not available.

Returns
  the shorthand reference to the namespace associated with the node, or `NOTHING` if not available

Code Flags:
  CONSTANT

Example:
  my *string $value = $xmlreader.prefix();

bool Qore::Xml::XmlReader::read | ( |  | ) |

Moves the position of the current instance to the next node in the stream.

If an error occurs parsing the XML string, an exception is raised

Returns
  `True` if the read was successful, `False` if there are no more nodes to read

Code Flags:
  RET_VALUE_ONLY

Example:
  if (!$xr.read())
  break;

Exceptions

  PARSE-XML-EXCEPTION | cannot move to next node due to an error parsing the XML string (exception description string contains details about the error)

See Also
  XmlReader::readSkipWhitespace()

bool Qore::Xml::XmlReader::readSkipWhitespace | ( |  | ) |

the position of the current instance to the next node in the stream, skipping any whitespace nodes

If an error occurs parsing the XML string, an exception is raised

Returns
  `True` if the read was successful, `False` if there are no more nodes to read

Code Flags:
  RET_VALUE_ONLY

Example:
  if (!$xr.readSkipWhitespace())
  break;

Exceptions

  PARSE-XML-EXCEPTION | cannot move to next node due to an error parsing the XML string (exception description string contains details about the error)

See Also
  XmlReader::read()

nothing Qore::Xml::XmlReader::relaxNGValidate | ( | string | relaxng | ) |

Set a RelaxNG schema for schema validation while parsing the XML document.

This method must be called before the first call to XmlReader::read()

The availability of this method depends on the presence of libxml2's `xmlTextReaderRelaxNGValidate()` function when the xml module was compiled; for maximum portability check the constant HAVE_PARSEXMLWITHRELAXNG before calling this method.

Code Flags:
  RET_VALUE_ONLY

Parameters

  relaxng | the RelaxNG schema string to use to validate the XML document

Exceptions

  RELAXNG-SYNTAX-ERROR | invalid RelaxNG string
  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

Example:
  $xr.relaxNGValidate($relaxng);

nothing Qore::Xml::XmlReader::schemaValidate | ( | string | xsd | ) |

Set an XSD schema for schema validation while parsing the XML document.

This method must be called before the first call to XmlReader::read()

The availability of this method depends on the presence of libxml2's `xmlTextReaderSetSchema()` function when the xml module was compiled; for maximum portability check the constant HAVE_PARSEXMLWITHSCHEMA before calling this method.

Code Flags:
  RET_VALUE_ONLY

Parameters

  xsd | the XSD schema string to use to validate the XML document

Exceptions

  XSD-SYNTAX-ERROR | invalid XSD string
  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

Example:
  $xr.schemaValidate($xsd);

any Qore::Xml::XmlReader::toQore | ( |  | ) |

Returns Qore data corresponding to the XML starting at the current node position, maintains element order by mangling node names.

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.

Returns
  If there are sub elements, a hash of the XML is returned, the sub elements representing the current node's children. If only text is present at the current element, a string is returned. If no information is available, then `NOTHING` is returned.

Note
  This method is functionally similar to parseXML()

Code Flags:
  RET_VALUE_ONLY

Example:
  my any $data = $xr.toQore();

See Also
  XmlReader::toQoreData()

any Qore::Xml::XmlReader::toQoreData | ( |  | ) |

Returns Qore data corresponding to the XML starting at the current node position, collapses duplicate out of order elements to a list.

Data deserialized with this method may not be reserialized to an identical XML string due to the fact that XML elements with the same name are collapsed into Qore lists in the resulting Qore hash irrespective of the order in the original XML string.

Returns
  If there are sub elements, a hash of the XML is returned, the sub elements representing the current node's children. If only text is present at the current element, a string is returned. If no information is available, then `NOTHING` is returned.

Note
  This method is functionally similar to parseXMLAsData()

Code Flags:
  RET_VALUE_ONLY

Example:
  my any $data = $xr.toQoreData();

See Also
  XmlReader::toQore()

*string Qore::Xml::XmlReader::value | ( |  | ) |

Returns the text value of the node or `NOTHING` if not available.

Returns
  the text value of the node or `NOTHING` if not available

Code Flags:
  CONSTANT

Example:
  my *string $val = $xr.value();

*string Qore::Xml::XmlReader::xmlLang | ( |  | ) |

Returns the `xml:lang` scope within which the node resides or `NOTHING` if there is none.

Returns
  the `xml:lang` scope within which the node resides or `NOTHING` if there is none

Code Flags:
  CONSTANT

Example:
  my *string $value = $xmlreader.xmlLang();

*string Qore::Xml::XmlReader::xmlVersion | ( |  | ) |

Returns a string giving the XML version of the source document (normally `"1.0"`) or `NOTHING` if none is present.

Returns
  a string giving the XML version of the source document (normally `"1.0"`) or `NOTHING` if none is present

Code Flags:
  CONSTANT

Example:
  my *string $value = $xmlreader.xmlVersion();

The documentation for this class was generated from the following file:

- /Users/david/src/qore/svn/module-xml/trunk/src/QC_XmlReader.dox.h