Qore XML Module  1.5
Qore::Xml::XmlReader Class Reference

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

Public Member Methods

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...
 
 constructor (Qore::InputStream is, *hash opts)
 creates a new XmlReader object from the input stream 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 (int pflags=XPF_PRESERVE_ORDER)
 Returns Qore data corresponding to the XML starting at the current node position, maintains element order by mangling node names. More...
 
any toQoreData (*int pflags)
 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

◆ attributeCount()

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:
int n = xr.attributeCount();

◆ baseUri()

*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:
*string value = xmlreader.baseUri();

◆ constructor() [1/3]

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

Creates the XmlReader object based on an XmlDoc object.

Exceptions
XML-READER-ERRORlibxml2 returned an error code when creating the XML reader object
Example:
XmlReader xr(xmldoc);

◆ constructor() [2/3]

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:
XmlReader xr(xmlstr);
Exceptions
XML-READER-ERRORlibxml2 returned an error code when creating the XML reader object (ex: XML string could not be parsed)
ENCODING-CONVERSION-ERRORthe string could not be converted to UTF-8 (usually due to an encoding error in the source string)

◆ constructor() [3/3]

Qore::Xml::XmlReader::constructor ( Qore::InputStream  is,
*hash  opts 
)

creates a new XmlReader object from the input stream

Parameters
isthe input stream
optsthe following options are accepted:
Example:
XmlReader xr(is);
Exceptions
XML-READER-OPTION-ERRORerror in option hash
XML-READER-ERRORlibxml2 returned an error code when creating the XML reader object
Note
the xml_parse_options option is accepted but ignored in this method; XML parsing options can be used in XmlReader::toQore() and XmlReader::toQoreData()
Since
xml 1.4

◆ copy()

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

Creates an independent copy of the XmlReader object.

Returns
an independent copy of the XmlReader object
Example:
XmlReader xrcopy = xr.copy();

◆ depth()

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:
int depth = xr.depth();

◆ encoding()

*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:
*string value = xmlreader.encoding();
Note
all XML strings are automatically converted to UTF-8 before parsing

◆ getAttribute()

*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
attrthe 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:
*string value = xmlreader.getAttribute(name);
See also
XmlReader::getAttributeNs()

◆ 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
attrthe name of the attribute to retrieve
nsthe 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:
*string value = xmlreader.getAttributeNs(localname, namespaceuri);
See also
XmlReader::getAttribute()

◆ getAttributeOffset()

*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
offsetthe 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:
*string value = xmlreader.getAttributeOffset(offset);
See also
XmlReader::getAttribute()

◆ getInnerXml()

*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:
*string value = xmlreader.getInnerXml();
See also
XmlReader::getOuterXml()

◆ 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:
*string value = xmlreader.getOuterXml();
See also
XmlReader::getInnerXml()

◆ hasAttributes()

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:
bool b = xr.hasAttributes();

◆ hasValue()

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:
bool b = xr.hasValue();

◆ isDefault()

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:
bool b = xr.isDefault();

◆ isEmptyElement()

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:
bool b = xr.isEmptyElement();

◆ isNamespaceDecl()

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:
bool b = xr.isNamespaceDecl();

◆ isValid()

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:
bool b = xr.isValid();

◆ localName()

*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:
*string value = xmlreader.localName();

◆ lookupNamespace() [1/2]

*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:
*string ns = xr.lookupNamespace();

◆ lookupNamespace() [2/2]

*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
prefixthe 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:
*string value = xmlreader.lookupNamespace(prefix);

◆ moveToAttribute()

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
attrthe qualified name of the attribute to move to
Returns
True in case of success, False if not found
Exceptions
PARSE-XML-EXCEPTIONerror parsing XML
Example:
bool b = xmlreader.moveToAttribute(name);
See also
XmlReader::moveToAttributeNs()

◆ 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
attrthe qualified name of the attribute to move to
nsthe namespace URI of the attribute
Returns
True in case of success, False if not found
Exceptions
PARSE-XML-EXCEPTIONerror parsing XML
Example:
bool b = xmlreader.moveToAttributeNs(localname, namespaceuri);
See also
XmlReader::moveToAttribute()

◆ moveToAttributeOffset()

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
offsetthe 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-EXCEPTIONerror parsing XML
Example:
bool b = xmlreader.moveToAttributeOffset(offset);
See also
XmlReader::moveToAttribute()

◆ moveToElement()

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-EXCEPTIONerror parsing XML
Example:
bool b = xmlreader.moveToElement();

◆ moveToFirstAttribute()

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-EXCEPTIONerror parsing XML
Example:
bool b = xmlreader.moveToFirstAttribute();

◆ moveToNextAttribute()

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-EXCEPTIONerror parsing XML
Example:
bool b = xmlreader.moveToNextAttribute();

◆ name()

*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:
*string value = xmlreader.name();
See also
XmlReader::localName()

◆ namespaceUri()

*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:
*string value = xmlreader.namespaceUri();

◆ next()

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-EXCEPTIONerror parsing XML
Example:
bool b = xmlreader.next();

◆ nodeType()

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:
int nt = xr.nodeType();
See also
NodeTypeMap
XmlReader::nodeTypeName()

◆ 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:
*string value = xmlreader.nodeTypeName();
See also
XmlReader::nodeType()

◆ prefix()

*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:
*string value = xmlreader.prefix();

◆ read()

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
Example:
if (!xr.read())
break;
Exceptions
PARSE-XML-EXCEPTIONcannot move to next node due to an error parsing the XML string (exception description string contains details about the error)
See also
XmlReader::readSkipWhitespace()

◆ 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
Example:
if (!xr.readSkipWhitespace())
break;
Exceptions
PARSE-XML-EXCEPTIONcannot move to next node due to an error parsing the XML string (exception description string contains details about the error)
See also
XmlReader::read()

◆ relaxNGValidate()

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.

Parameters
relaxngthe RelaxNG schema string to use to validate the XML document
Exceptions
RELAXNG-SYNTAX-ERRORinvalid RelaxNG string
MISSING-FEATURE-ERRORthis 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);

◆ schemaValidate()

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.

Parameters
xsdthe XSD schema string to use to validate the XML document
Exceptions
XSD-SYNTAX-ERRORinvalid XSD string
MISSING-FEATURE-ERRORthis 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);

◆ toQore()

any Qore::Xml::XmlReader::toQore ( int  pflags = XPF_PRESERVE_ORDER)

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

Code Flags:
RET_VALUE_ONLY
Example:
any data = xr.toQore();
Parameters
pflagsXML parsing flags; see XML Parsing Constants for more information; note that this method assumes XPF_PRESERVE_ORDER for backwards-compatibility
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 parse_xml()
See also
XmlReader::toQoreData()

◆ toQoreData()

any Qore::Xml::XmlReader::toQoreData ( *int  pflags)

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

Code Flags:
RET_VALUE_ONLY
Example:
any data = xr.toQoreData();
Parameters
pflagsXML parsing flags; see XML Parsing Constants for more information
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 parse_xml()
See also
XmlReader::toQore()

◆ value()

*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:
*string val = xr.value();

◆ xmlLang()

*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:
*string value = xmlreader.xmlLang();

◆ xmlVersion()

*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:
*string value = xmlreader.xmlVersion();

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