4.35. Xml::XmlReader Class

4.35. Xml::XmlReader Class
Prev	Chapter 4. System Namespaces and Class Library	Next

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

Table 4.763. XmlReader Class Method Overview

Method	Except?	Description
`XmlReader::constructor(XmlDoc $doc)` `XmlReader::constructor(string $xml)`	Y	Creates the XmlReader object based on the XmlDoc object or XML string passed.
`XmlReader::destructor()`	N	Destroys the XmlReader object.
`XmlReader::copy()`	N	Creates an independent copy of the XmlReader object.
`XmlReader::read() returns bool`	Y	Moves the position of the current instance to the next node in the stream.
`XmlReader::readSkipWhitespace() returns bool`	Y	Moves the position of the current instance to the next node in the stream, skipping any whitespace nodes.
`XmlReader::nodeType() returns int`	N	Returns the node type of the current node; for return values, see XML Node Type Constants.
`XmlReader::nodeTypeName() returns any`	N	Returns a string giving the node type of the current node or NOTHING if the node type name cannot be determined; for possible return values, see the values of the NodeTypeMap constant.
`XmlReader::depth() returns int`	N	Returns the depth of the node in the tree.
`XmlReader::name() returns any`	N	Returns the qualified name of the node (prefix:LocalName) or NOTHING if no name is available.
`XmlReader::value() returns any`	N	Returns the text value of the node or NOTHING if not available.
`XmlReader::hasAttributes() returns bool`	N	Returns `True` if the node has attributes or `False` if not.
`XmlReader::hasValue() returns bool`	N	Returns `True` if the node has a text value or `False` if not.
`XmlReader::isDefault() returns bool`	N	Returns `True` if an attribute node was generated from the default value defined in the DTD or schema, `False` if not.
`XmlReader::isEmptyElement() returns bool`	N	Returns `True` if the current node is empty or `False` if not.
`XmlReader::isNamespaceDecl() returns bool`	N	Returns `True` if the current node is a namespace declaration rather than a regular attribute or `False` if not.
`XmlReader::isValid() returns bool`	N	Returns `True` if the current reader parser context is valid, `False` if not
`XmlReader::toQore() returns any`	Y	Returns a hash corresponding to the XML string from the current node position, including all its children, or a string if the reader is on an element with no children, or NOTHING if there is no more data to read.
`XmlReader::toQoreData() returns any`	Y	Returns a hash corresponding to the XML string from the current node position, including all its children, or a string if the reader is on an element with no children, or NOTHING if there is no more data to read.
`XmlReader::attributeCount() returns int`	N	Returns the number of attributes of the current node
`XmlReader::baseUri() returns any`	N	Returns the base URI of the node if known, NOTHING if not.
`XmlReader::encoding() returns any`	N	Returns the encoding string given in the XML string or NOTHING if none is given.
`XmlReader::localName() returns any`	N	Returns the local name of the node or NOTHING if no name is available.
`XmlReader::namespaceUri() returns any`	N	Returns the URI defining the namespace associated with the node, or NOTHING if not available.
`XmlReader::prefix() returns any`	N	Returns the shorthand reference to the namespace associated with the node, or NOTHING if not available.
`XmlReader::xmlLang() returns any`	N	Returns the xml:lang scope within which the node resides or NOTHING if there is none.
`XmlReader::xmlVersion() returns any`	N	Returns a string giving the XML version of the source document (normally "1.0")
`XmlReader::getAttribute(string $attr) returns any`	Y	Returns the value of the attribute matching the qualified name passed, or NOTHING if no such attribute exists in the current XmlReader.
`XmlReader::getAttributeNs(string $attr, string $ns) returns any`	Y	Returns the value of the given attribute anchored in the given namespace, or NOTHING if no such attribute exists in the current XmlReader.
`XmlReader::getAttributeOffset(softint $offset = 0) returns any`	N	Returns the string value of the attribute with the specified index relative to the containing element, or NOTHING if no such attribute exists in the current XmlReader.
`XmlReader::lookupNamespace() returns any` `XmlReader::lookupNamespace(string $ns) returns any`	N	Returns the namespace corresponding to the given prefix in the scope of the current element as a string or NOTHING if none is found. Called with no argument this function returns the default namespace.
`XmlReader::moveToAttribute(string $attr) returns bool`	Y	Moves the position of the current instance to the attribute with the specified qualified name.
`XmlReader::moveToAttributeNs(string $attr, string $ns) returns bool`	Y	Moves the position of the current instance to the attribute with the specified local name and namespace URI.
`XmlReader::moveToAttributeOffset(int $offset) returns bool`	Y	Moves the position of the current instance to the attribute with the specified index relative to the containing element.
`XmlReader::moveToElement() returns bool`	Y	Moves the position of the current instance to the element node containing the current attribute node.
`XmlReader::moveToFirstAttribute() returns bool`	Y	Moves the position of the current instance to the first attribute of the current node.
`XmlReader::moveToNextAttribute() returns bool`	Y	Moves the position of the current instance to the next attribute of the current node.
`XmlReader::next() returns bool`	Y	Moves the position of the current instance to the next node in the tree at the same level, skipping any subtree.
`XmlReader::getInnerXml() returns any`	N	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.
`XmlReader::getOuterXml() returns any`	N	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.
`XmlReader::relaxNGValidate(string $relaxng) returns nothing`	Y	Set a RelaxNG schema for schema validation while parsing the XML document. This method must be called before the first call to XmlReader::read(). Not available if `HAVE_PARSEXMLWITHRELAXNG` is `False`.
`XmlReader::schemaValidate(string $xsd) returns nothing`	Y	Set an XSD schema for schema validation while parsing the XML document. This method must be called before the first call to XmlReader::read(). Not available if `HAVE_PARSEXMLWITHSCHEMA` is `False`.

4.35.1. XmlReader::constructor()

Synopsis

Creates the XmlReader object based on the XmlDoc object or XML string passed.

Prototype

XmlReader::constructor(XmlDoc $doc)

XmlReader::constructor(string $xml)

Example

my XmlReader $xmlreader($xml);

Table 4.764. Arguments for XmlReader::constructor()

Argument	Description
`XmlDoc $doc`	The pre-parsed XML document object to iterate through.
`string $xml`	The XML string to parse.

Table 4.765. Exceptions thrown by XmlReader::constructor()

err	desc
`XMLNODE-CONSTRUCTOR-ERROR`	invalid argument, error in XML string, etc

4.35.2. XmlReader::destructor()

Synopsis

Destroys the XmlReader object.

Example

delete $xmlreader;

4.35.3. XmlReader::copy()

Synopsis

Creates an independent copy of the XmlReader object.

Example

my XmlReader $xr = $xmlreader.copy();

4.35.4. XmlReader::read()

Synopsis

Moves the position of the current instance to the next node in the stream. Returns True if the read was successful, False if there are no more nodes to read. If an error occurs parsing the XML string, an exception is raised (see below).

Prototype

XmlReader::read() returns bool

Example

if (!$xmlreader.read())
    break;

Table 4.766. Return Values for XmlReader::read()

Return Type	Description
`bool`	True if the read was successful, `False` if there are no more nodes to read

Table 4.767. Exceptions thrown by XmlReader::read()

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

4.35.5. XmlReader::readSkipWhitespace()

Synopsis

Moves the position of the current instance to the next node in the stream, skipping any whitespace nodes. Returns True if the read was successful, False if there are no more nodes to read. If an error occurs parsing the XML string, an exception is raised (see below).

4.35.6. XmlReader::nodeType()

Synopsis

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

Return Type	Description
`int`	the node type of the current node; for return values, see XML Node Type Constants

4.35.7. XmlReader::nodeTypeName()

Synopsis

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 constant.

Return Type	Description
`string or nothing`	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 constant

4.35.8. XmlReader::depth()

Synopsis

Returns the depth of the node in the tree.

Prototype

XmlReader::depth() returns int

Example

$value = $xmlreader.depth();

Table 4.772. Return Values for XmlReader::depth()

Return Type	Description
`int`	the depth of the node in the tree

4.35.9. XmlReader::name()

Synopsis

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

Return Type	Description
`string or nothing`	the qualified name of the node (prefix:LocalName) or NOTHING if no name is available

4.35.10. XmlReader::value()

Synopsis

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

Prototype

XmlReader::value() returns any

Example

$value = $xmlreader.value();

Table 4.774. Return Values for XmlReader::value()

Return Type	Description
`string or nothing`	the text value of the node or NOTHING if not available

4.35.11. XmlReader::hasAttributes()

Synopsis

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

Prototype

XmlReader::hasAttributes() returns bool

Example

$value = $xmlreader.hasAttributes();

Table 4.775. Return Values for XmlReader::hasAttributes()

Return Type	Description
`bool`	True if the node has attributes, `False` if not

4.35.12. XmlReader::hasValue()

Synopsis

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

Prototype

XmlReader::hasValue() returns bool

Example

$value = $xmlreader.hasValue();

Table 4.776. Return Values for XmlReader::hasValue()

Return Type	Description
`bool`	True if the node has a text value, `False` if not

4.35.13. XmlReader::isDefault()

Synopsis

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

Prototype

XmlReader::isDefault() returns bool

Example

$value = $xmlreader.isDefault();

Table 4.777. Return Values for XmlReader::isDefault()

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

4.35.14. XmlReader::isEmptyElement()

Synopsis

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

Prototype

XmlReader::isEmptyElement() returns bool

Example

$value = $xmlreader.isEmptyElement();

Table 4.778. Return Values for XmlReader::isEmptyElement()

Return Type	Description
`bool`	True if the current node is empty, `False` if not

4.35.15. XmlReader::isNamespaceDecl()

Synopsis

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

Prototype

XmlReader::isNamespaceDecl() returns bool

Example

$value = $xmlreader.isNamespaceDecl();

Table 4.779. Return Values for XmlReader::isNamespaceDecl()

Return Type	Description
`bool`	True if the current node is a namespace declaration rather than a regular attribute, `False` if not

4.35.16. XmlReader::isValid()

Synopsis

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

Prototype

XmlReader::isValid() returns bool

Example

$value = $xmlreader.isValid();

Table 4.780. Return Values for XmlReader::isValid()

Return Type	Description
`bool`	True if the current reader parser context is valid, `False` if not

4.35.17. XmlReader::toQore()

Synopsis

Returns Qore data corresponding to the XML starting at the current node position. If there are sub elements, a hash of the XML is returned, the sub elements representing the current node's children. If duplicate, out-of-order XML elements are found in the input string, they are deserialized to Qore 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 Qore hash as in the input XML string.

If only text is present at the current element, a string is returned. If no information is available, then NOTHING is returned.

Return Type	Description
`hash, string, or nothing`	Returns Qore data corresponding to the XML starting at the current node position. If there are sub elements, a hash of the XML is returned, the sub elements representing the current node's children; XML element order is maintained by appending a suffix to key names. If only text is present at the current element, a string is returned. If no information is available, then NOTHING is returned.

err	desc
`PARSE-XML-EXCEPTION`	error parsing the XML string (exception description string contains details about the error)

4.35.18. XmlReader::toQoreData()

Synopsis

Returns Qore data corresponding to the XML starting at the current node position. If there are sub elements, a hash of the XML is returned, the sub elements representing the current node's children. Note that 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.

If only text is present at the current element, a string is returned. If no information is available, then NOTHING is returned.

Return Type	Description
`hash, string, or nothing`	Returns Qore data corresponding to the XML starting at the current node position. If there are sub elements, a hash of the XML is returned, the sub elements representing the current node's children; does not guarantee to maintain XML element order in the hash as elements at the same level with the same name are collapsed to a Qore list. If only text is present at the current element, a string is returned. If no information is available, then NOTHING is returned.

err	desc
`PARSE-XML-EXCEPTION`	error parsing the XML string (exception description string contains details about the error)

4.35.19. XmlReader::attributeCount()

Synopsis

Returns the number of attributes of the current node

Prototype

XmlReader::attributeCount() returns int

Example

$value = $xmlreader.attributeCount();

Table 4.785. Return Values for XmlReader::attributeCount()

Return Type	Description
`int`	the number of attributes of the current node

4.35.20. XmlReader::baseUri()

Synopsis

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

Prototype

XmlReader::baseUri() returns any

Example

$value = $xmlreader.baseUri();

Table 4.786. Return Values for XmlReader::baseUri()

Return Type	Description
`string or nothing`	the base URI of the node if known, NOTHING if not

4.35.21. XmlReader::encoding()

Synopsis

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

Prototype

XmlReader::encoding() returns any

Example

$value = $xmlreader.encoding();

Table 4.787. Return Values for XmlReader::encoding()

Return Type	Description
`string or nothing`	Returns the encoding string given in the XML string or NOTHING if none is given.

4.35.22. XmlReader::localName()

Synopsis

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

Prototype

XmlReader::localName() returns any

Example

$value = $xmlreader.localName();

Table 4.788. Return Values for XmlReader::localName()

Return Type	Description
`string or nothing`	the local name of the node or NOTHING if no name is available

4.35.23. XmlReader::namespaceUri()

Synopsis

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

Prototype

XmlReader::namespaceUri() returns any

Example

$value = $xmlreader.namespaceUri();

Table 4.789. Return Values for XmlReader::namespaceUri()

Return Type	Description
`string or nothing`	the URI defining the namespace associated with the node or NOTHING if not available

4.35.24. XmlReader::prefix()

Synopsis

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

Prototype

XmlReader::prefix() returns any

Example

$value = $xmlreader.prefix();

Table 4.790. Return Values for XmlReader::prefix()

Return Type	Description
`string or nothing`	the shorthand reference to the namespace associated with the node or NOTHING if not available

4.35.25. XmlReader::xmlLang()

Synopsis

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

Prototype

XmlReader::xmlLang() returns any

Example

$value = $xmlreader.xmlLang();

Table 4.791. Return Values for XmlReader::xmlLang()

Return Type	Description
`string or nothing`	the xml:lang scope within which the node resides or NOTHING if there is none

4.35.26. XmlReader::xmlVersion()

Synopsis

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

Prototype

XmlReader::xmlVersion() returns any

Example

$value = $xmlreader.xmlVersion();

Table 4.792. Return Values for XmlReader::xmlVersion()

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

4.35.27. XmlReader::getAttribute()

Synopsis

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

Argument	Description
`string $attr`	The name of the attribute to retrieve

Return Type	Description
`string or nothing`	the value of the attribute or NOTHING if it does not exist

err	desc
`XMLREADER-GETATTRIBUTE-ERROR`	missing or invalid argument

4.35.28. XmlReader::getAttributeNs()

Synopsis

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

Argument	Description
`string $attr`	The name of the attribute to retrieve
`string $ns`	The name of the namespace URI of the attribute

Return Type	Description
`string or nothing`	the value of the attribute or NOTHING if it does not exist

err	desc
`XMLREADER-GETATTRIBUTENS-ERROR`	missing or invalid argument

4.35.29. XmlReader::getAttributeOffset()

Synopsis

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.

Argument	Description
`softint $offset = 0`	the index of the attribute relative to the containing element

Return Type	Description
`string or nothing`	the value of the attribute or NOTHING if it does not exist

4.35.30. XmlReader::lookupNamespace()

Synopsis

returns the namespace corresponding to the given prefix in the scope of the current element. If no prefix is given, the default namespace is returned.

Prototype

XmlReader::lookupNamespace() returns any

XmlReader::lookupNamespace(string $ns) returns any

Example

$value = $xmlreader.lookupNamespace($prefix);

Table 4.801. Arguments for XmlReader::lookupNamespace()

Argument	Description
`[string $ns]`	The namespace prefix to resolve; if no value is sent for this argument, the default namespace is returned.

Table 4.802. Return Values for XmlReader::lookupNamespace()

Return Type	Description
`string or nothing`	The namespace corresponding to the given prefix in the scope of the current element or NOTHING if the prefix could not be resolved.

4.35.31. XmlReader::moveToAttribute()

Synopsis

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

Argument	Description
`string $attr`	The qualified name of the attribute to move to

err	desc
`XMLREADER-MOVETOATTRIBUTE-ERROR`	missing or invalid argument
`PARSE-XML-EXCEPTION`	error parsing XML

4.35.32. XmlReader::moveToAttributeNs()

Synopsis

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

Argument	Description
`string $attr`	The qualified name of the attribute to move to
`string $ns`	The namespace URI of the attribute

err	desc
`XMLREADER-MOVETOATTRIBUTENS-ERROR`	missing or invalid argument
`PARSE-XML-EXCEPTION`	an error occured parsing the XML string

4.35.33. XmlReader::moveToAttributeOffset()

Synopsis

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

Argument	Description
`softint $offset = 0`	the index of the attribute relative to the containing element to move to

4.35.34. XmlReader::moveToElement()

Synopsis

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

Prototype

XmlReader::moveToElement() returns bool

Example

$value = $xmlreader.moveToElement();

Table 4.812. Return Values for XmlReader::moveToElement()

Return Type	Description
`bool`	True in case of success, `False` if not found; if an XML parsing error occurs, an exception is thrown.

Table 4.813. Exceptions thrown by XmlReader::moveToElement()

err	desc
`PARSE-XML-EXCEPTION`	an error occured parsing the XML string

4.35.35. XmlReader::moveToFirstAttribute()

Synopsis

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

Prototype

XmlReader::moveToFirstAttribute() returns bool

Example

$value = $xmlreader.moveToFirstAttribute();

Table 4.814. Return Values for XmlReader::moveToFirstAttribute()

Return Type	Description
`bool`	True in case of success, `False` if not found; if an XML parsing error occurs, an exception is thrown.

Table 4.815. Exceptions thrown by XmlReader::moveToFirstAttribute()

err	desc
`PARSE-XML-EXCEPTION`	an error occured parsing the XML string

4.35.36. XmlReader::moveToNextAttribute()

Synopsis

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

Prototype

XmlReader::moveToNextAttribute() returns bool

Example

$value = $xmlreader.moveToNextAttribute();

Table 4.816. Return Values for XmlReader::moveToNextAttribute()

Return Type	Description
`bool`	True in case of success, `False` if not found; if an XML parsing error occurs, an exception is thrown.

Table 4.817. Exceptions thrown by XmlReader::moveToNextAttribute()

err	desc
`PARSE-XML-EXCEPTION`	an error occured parsing the XML string

4.35.37. XmlReader::next()

Synopsis

Moves the position of the current instance to the next node in the tree at the same level, skipping any subtree. Returns True if the operation succeeded, False if there are no more nodes to read. If an error occurs parsing the XML string, an exception is raised.

Prototype

XmlReader::next() returns bool

Example

$value = $xmlreader.next();

Table 4.818. Return Values for XmlReader::next()

Return Type	Description
`bool`	True in case of success, `False` if not found; if an XML parsing error occurs, an exception is thrown.

Table 4.819. Exceptions thrown by XmlReader::next()

err	desc
`PARSE-XML-EXCEPTION`	an error occured parsing the XML string

4.35.38. XmlReader::getInnerXml()

Synopsis

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.

4.35.39. XmlReader::getOuterXml()

Synopsis

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.

4.35.40. XmlReader::relaxNGValidate()

Synopsis

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 function depends on the presence of libxml2's xmlTextReaderRelaxNGValidate() function when Qore was compiled; for maximum portability check the constant HAVE_PARSEXMLWITHRELAXNG before calling this method. See Library Option Constants for a list of all option constants.

If any errors occur, an exception is thrown (see below).

Prototype

XmlReader::relaxNGValidate(string $relaxng) returns nothing

Example

$xmlreader.relaxNGValidate($rng);

Table 4.822. Arguments for XmlReader::relaxNGValidate()

Argument	Description
`string $relaxng`	The RelaxNG schema to use to validate the XML string while parsing.

Table 4.823. Exceptions thrown by XmlReader::relaxNGValidate()

err	desc
`XMLREADER-RELAXNGVALIDATE-ERROR`	missing or invalid argument
`XMLREADER-RELAXNG-ERROR`	invalid RelaxNG schema or method called after the first call to XmlReader::read()
`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.

4.35.41. XmlReader::schemaValidate()

Synopsis

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 function depends on the presence of libxml2's xmlTextReaderSchemaValidate() function when Qore was compiled; for maximum portability check the constant HAVE_PARSEXMLWITHSCHEMA before calling this method. See Library Option Constants for a list of all option constants.

If any errors occur, an exception is thrown (see below).

Prototype

XmlReader::schemaValidate(string $xsd) returns nothing

Example

$xmlreader.schemaValidate($xsd);

Table 4.824. Arguments for XmlReader::schemaValidate()

Argument	Description
`string xsd`	The XSD schema to use to validate the XML string while parsing.

Table 4.825. Exceptions thrown by XmlReader::schemaValidate()

err	desc
`XMLREADER-SCHEMAVALIDATE-ERROR`	missing or invalid argument
`XMLREADER-XSD-ERROR`	invalid RelaxNG schema or method called after the first call to XmlReader::read()
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available; for maximum portability, check the constan t `HAVE_PARSEXMLWITHSCHEMA` before calling this function.

Prev	Up	Next
4.34. Xml::XmlNode Class	Home	Chapter 5. Command-Line Parsing