The QXmlStreamReader class provides a fast parser for reading well-formed XML via a simple streaming API. More...
#include <qxmlstream.h>
Public Types | |
| enum | TokenType { NoToken = 0 , Invalid , StartDocument , EndDocument , StartElement , EndElement , Characters , Comment , DTD , EntityReference , ProcessingInstruction } |
| enum | ReadElementTextBehaviour { ErrorOnUnexpectedElement , IncludeChildElements , SkipChildElements } |
| enum | Error { NoError , UnexpectedElementError , CustomError , NotWellFormedError , PrematureEndOfDocumentError } |
Detailed Description
The QXmlStreamReader class provides a fast parser for reading well-formed XML via a simple streaming API.
\inmodule QtCore \reentrant
- Since
- 4.3
QXmlStreamReader provides a simple streaming API to parse well-formed XML. It is an alternative to first loading the complete XML into a DOM tree (see \l QDomDocument). QXmlStreamReader reads data either from a QIODevice (see setDevice()), or from a raw QByteArray (see addData()).
Qt provides QXmlStreamWriter for writing XML.
The basic concept of a stream reader is to report an XML document as a stream of tokens, similar to SAX. The main difference between QXmlStreamReader and SAX is how these XML tokens are reported. With SAX, the application must provide handlers (callback functions) that receive so-called XML events from the parser at the parser's convenience. With QXmlStreamReader, the application code itself drives the loop and pulls tokens from the reader, one after another, as it needs them. This is done by calling readNext(), where the reader reads from the input stream until it completes the next token, at which point it returns the tokenType(). A set of convenient functions including isStartElement() and text() can then be used to examine the token to obtain information about what has been read. The big advantage of this pulling approach is the possibility to build recursive descent parsers with it, meaning you can split your XML parsing code easily into different methods or classes. This makes it easy to keep track of the application's own state when parsing XML.
A typical loop with QXmlStreamReader looks like this:
QXmlStreamReader is a well-formed XML 1.0 parser that does not include external parsed entities. As long as no error occurs, the application code can thus be assured that the data provided by the stream reader satisfies the W3C's criteria for well-formed XML. For example, you can be certain that all tags are indeed nested and closed properly, that references to internal entities have been replaced with the correct replacement text, and that attributes have been normalized or added according to the internal subset of the DTD.
If an error occurs while parsing, atEnd() and hasError() return true, and error() returns the error that occurred. The functions errorString(), lineNumber(), columnNumber(), and characterOffset() are for constructing an appropriate error or warning message. To simplify application code, QXmlStreamReader contains a raiseError() mechanism that lets you raise custom errors that trigger the same error handling described.
The \l{QXmlStream Bookmarks Example} illustrates how to use the recursive descent technique to read an XML bookmark file (XBEL) with a stream reader.
Definition at line 216 of file qxmlstream.h.
Member Enumeration Documentation
◆ Error
This enum specifies different error cases
\value NoError No error has occurred.
\value CustomError A custom error has been raised with raiseError()
\value NotWellFormedError The parser internally raised an error due to the read XML not being well-formed.
\value PrematureEndOfDocumentError The input stream ended before a well-formed XML document was parsed. Recovery from this error is possible if more XML arrives in the stream, either by calling addData() or by waiting for it to arrive on the device().
\value UnexpectedElementError The parser encountered an element that was different to those it expected.
| Enumerator | |
|---|---|
| NoError | |
| UnexpectedElementError | |
| CustomError | |
| NotWellFormedError | |
| PrematureEndOfDocumentError | |
Definition at line 312 of file qxmlstream.h.
◆ ReadElementTextBehaviour
This enum specifies the different behaviours of readElementText().
\value ErrorOnUnexpectedElement Raise an UnexpectedElementError and return what was read so far when a child element is encountered.
\value IncludeChildElements Recursively include the text from child elements.
\value SkipChildElements Skip child elements.
- Since
- 4.6
| Enumerator | |
|---|---|
| ErrorOnUnexpectedElement | |
| IncludeChildElements | |
| SkipChildElements | |
Definition at line 283 of file qxmlstream.h.
◆ TokenType
This enum specifies the type of token the reader just read.
\value NoToken The reader has not yet read anything.
\value Invalid An error has occurred, reported in error() and errorString().
\value StartDocument The reader reports the XML version number in documentVersion(), and the encoding as specified in the XML document in documentEncoding(). If the document is declared standalone, isStandaloneDocument() returns true; otherwise it returns false.
\value EndDocument The reader reports the end of the document.
\value StartElement The reader reports the start of an element with namespaceUri() and name(). Empty elements are also reported as StartElement, followed directly by EndElement. The convenience function readElementText() can be called to concatenate all content until the corresponding EndElement. Attributes are reported in attributes(), namespace declarations in namespaceDeclarations().
\value EndElement The reader reports the end of an element with namespaceUri() and name().
\value Characters The reader reports characters in text(). If the characters are all white-space, isWhitespace() returns true. If the characters stem from a CDATA section, isCDATA() returns true.
\value Comment The reader reports a comment in text().
\value DTD The reader reports a DTD in text(), notation declarations in notationDeclarations(), and entity declarations in entityDeclarations(). Details of the DTD declaration are reported in in dtdName(), dtdPublicId(), and dtdSystemId().
\value EntityReference The reader reports an entity reference that could not be resolved. The name of the reference is reported in name(), the replacement text in text().
\value ProcessingInstruction The reader reports a processing instruction in processingInstructionTarget() and processingInstructionData().
| Enumerator | |
|---|---|
| NoToken | |
| Invalid | |
| StartDocument | |
| EndDocument | |
| StartElement | |
| EndElement | |
| Characters | |
| Comment | |
| DTD | |
| EntityReference | |
| ProcessingInstruction | |
Definition at line 219 of file qxmlstream.h.
Constructor & Destructor Documentation
◆ QXmlStreamReader() [1/5]
| QXmlStreamReader::QXmlStreamReader | ( | ) |
Constructs a stream reader.
- See also
- setDevice(), addData()
Definition at line 395 of file qxmlstream.cpp.
◆ QXmlStreamReader() [2/5]
|
explicit |
Creates a new stream reader that reads from device.
- See also
- setDevice(), clear()
Definition at line 404 of file qxmlstream.cpp.
◆ QXmlStreamReader() [3/5]
|
explicit |
Creates a new stream reader that reads from data.
- See also
- addData(), clear(), setDevice()
Definition at line 415 of file qxmlstream.cpp.
◆ QXmlStreamReader() [4/5]
Creates a new stream reader that reads from data.
- See also
- addData(), clear(), setDevice()
Definition at line 427 of file qxmlstream.cpp.
◆ QXmlStreamReader() [5/5]
|
explicit |
Creates a new stream reader that reads from data.
- See also
- addData(), clear(), setDevice()
Definition at line 441 of file qxmlstream.cpp.
◆ ~QXmlStreamReader()
| QXmlStreamReader::~QXmlStreamReader | ( | ) |
Destructs the reader.
Definition at line 451 of file qxmlstream.cpp.
Member Function Documentation
◆ addData() [1/3]
Adds more data for the reader to read. This function does nothing if the reader has a device().
- See also
- readNext(), clear()
Definition at line 532 of file qxmlstream.cpp.
◆ addData() [2/3]
| void QXmlStreamReader::addData | ( | const QByteArray & | data | ) |
Adds more data for the reader to read. This function does nothing if the reader has a device().
- See also
- readNext(), clear()
Definition at line 501 of file qxmlstream.cpp.
◆ addData() [3/3]
Adds more data for the reader to read. This function does nothing if the reader has a device().
- See also
- readNext(), clear()
Definition at line 517 of file qxmlstream.cpp.
◆ addExtraNamespaceDeclaration()
| void QXmlStreamReader::addExtraNamespaceDeclaration | ( | const QXmlStreamNamespaceDeclaration & | extraNamespaceDeclaration | ) |
- Since
- 4.4
Adds an extraNamespaceDeclaration. The declaration will be valid for children of the current element, or - should the function be called before any elements are read - for the entire XML document.
Definition at line 2073 of file qxmlstream.cpp.
◆ addExtraNamespaceDeclarations()
| void QXmlStreamReader::addExtraNamespaceDeclarations | ( | const QXmlStreamNamespaceDeclarations & | extraNamespaceDeclarations | ) |
- Since
- 4.4
Adds a vector of declarations specified by extraNamespaceDeclarations.
Definition at line 2088 of file qxmlstream.cpp.
◆ atEnd()
| bool QXmlStreamReader::atEnd | ( | ) | const |
Returns true if the reader has read until the end of the XML document, or if an error() has occurred and reading has been aborted. Otherwise, it returns false.
When atEnd() and hasError() return true and error() returns PrematureEndOfDocumentError, it means the XML has been well-formed so far, but a complete XML document has not been parsed. The next chunk of XML can be added with addData(), if the XML is being read from a QByteArray, or by waiting for more data to arrive if the XML is being read from a QIODevice. Either way, atEnd() will return false once more data is available.
- See also
- hasError(), error(), device(), QIODevice::atEnd()
Definition at line 569 of file qxmlstream.cpp.
◆ attributes()
| QXmlStreamAttributes QXmlStreamReader::attributes | ( | ) | const |
Returns the attributes of a StartElement.
Definition at line 2262 of file qxmlstream.cpp.
◆ characterOffset()
| qint64 QXmlStreamReader::characterOffset | ( | ) | const |
Returns the current character offset, starting with 0.
- See also
- lineNumber(), columnNumber()
Definition at line 1918 of file qxmlstream.cpp.
◆ clear()
| void QXmlStreamReader::clear | ( | ) |
Removes any device() or data from the reader and resets its internal state to the initial state.
- See also
- addData()
Definition at line 543 of file qxmlstream.cpp.
◆ columnNumber()
| qint64 QXmlStreamReader::columnNumber | ( | ) | const |
Returns the current column number, starting with 0.
- See also
- lineNumber(), characterOffset()
Definition at line 1908 of file qxmlstream.cpp.
◆ device()
| QIODevice * QXmlStreamReader::device | ( | ) | const |
Returns the current device associated with the QXmlStreamReader, or \nullptr if no device has been assigned.
- See also
- setDevice()
Definition at line 488 of file qxmlstream.cpp.
◆ documentEncoding()
| QStringView QXmlStreamReader::documentEncoding | ( | ) | const |
- Since
- 4.4
If the tokenType() is \l StartDocument, this function returns the encoding string as specified in the XML declaration. Otherwise an empty string is returned.
Definition at line 2760 of file qxmlstream.cpp.
◆ documentVersion()
| QStringView QXmlStreamReader::documentVersion | ( | ) | const |
- Since
- 4.4
If the tokenType() is \l StartDocument, this function returns the version string as specified in the XML declaration. Otherwise an empty string is returned.
Definition at line 2745 of file qxmlstream.cpp.
◆ dtdName()
| QStringView QXmlStreamReader::dtdName | ( | ) | const |
- Since
- 4.4
If the tokenType() is \l DTD, this function returns the DTD's name. Otherwise an empty string is returned.
Definition at line 1971 of file qxmlstream.cpp.
◆ dtdPublicId()
| QStringView QXmlStreamReader::dtdPublicId | ( | ) | const |
- Since
- 4.4
If the tokenType() is \l DTD, this function returns the DTD's public identifier. Otherwise an empty string is returned.
Definition at line 1986 of file qxmlstream.cpp.
◆ dtdSystemId()
| QStringView QXmlStreamReader::dtdSystemId | ( | ) | const |
- Since
- 4.4
If the tokenType() is \l DTD, this function returns the DTD's system identifier. Otherwise an empty string is returned.
Definition at line 2001 of file qxmlstream.cpp.
◆ entityDeclarations()
| QXmlStreamEntityDeclarations QXmlStreamReader::entityDeclarations | ( | ) | const |
If the tokenType() is \l DTD, this function returns the DTD's unparsed (external) entity declarations. Otherwise an empty vector is returned.
The QXmlStreamEntityDeclarations class is defined to be a QList of QXmlStreamEntityDeclaration.
Definition at line 1956 of file qxmlstream.cpp.
◆ entityExpansionLimit()
| int QXmlStreamReader::entityExpansionLimit | ( | ) | const |
- Since
- 5.15
Returns the maximum amount of characters a single entity is allowed to expand into. If a single entity expands past the given limit, the document is not considered well formed.
- See also
- setEntityExpansionLimit
Definition at line 2018 of file qxmlstream.cpp.
◆ entityResolver()
| QXmlStreamEntityResolver * QXmlStreamReader::entityResolver | ( | ) | const |
- Since
- 4.4
Returns the entity resolver, or \nullptr if there is no entity resolver.
- See also
- setEntityResolver()
Definition at line 260 of file qxmlstream.cpp.
◆ error()
| QXmlStreamReader::Error QXmlStreamReader::error | ( | ) | const |
Returns the type of the current error, or NoError if no error occurred.
- See also
- errorString(), raiseError()
Definition at line 2176 of file qxmlstream.cpp.
◆ errorString()
| QString QXmlStreamReader::errorString | ( | ) | const |
Returns the error message that was set with raiseError().
- See also
- error(), lineNumber(), columnNumber(), characterOffset()
Definition at line 2164 of file qxmlstream.cpp.
◆ hasError()
|
inline |
Returns true if an error has occurred, otherwise false.
- See also
- errorString(), error()
Definition at line 323 of file qxmlstream.h.
◆ isCDATA()
| bool QXmlStreamReader::isCDATA | ( | ) | const |
Returns true if the reader reports characters that stem from a CDATA section; otherwise returns false.
- See also
- isCharacters(), text()
Definition at line 2717 of file qxmlstream.cpp.
◆ isCharacters()
|
inline |
Returns true if tokenType() equals \l Characters; otherwise returns false.
- See also
- isWhitespace(), isCDATA()
Definition at line 265 of file qxmlstream.h.
◆ isComment()
|
inline |
Returns true if tokenType() equals \l Comment; otherwise returns false.
Definition at line 268 of file qxmlstream.h.
◆ isDTD()
|
inline |
Returns true if tokenType() equals \l DTD; otherwise returns false.
Definition at line 269 of file qxmlstream.h.
◆ isEndDocument()
|
inline |
Returns true if tokenType() equals \l EndDocument; otherwise returns false.
Definition at line 262 of file qxmlstream.h.
◆ isEndElement()
|
inline |
Returns true if tokenType() equals \l EndElement; otherwise returns false.
Definition at line 264 of file qxmlstream.h.
◆ isEntityReference()
|
inline |
Returns true if tokenType() equals \l EntityReference; otherwise returns false.
Definition at line 270 of file qxmlstream.h.
◆ isProcessingInstruction()
|
inline |
Returns true if tokenType() equals \l ProcessingInstruction; otherwise returns false.
Definition at line 271 of file qxmlstream.h.
◆ isStandaloneDocument()
| bool QXmlStreamReader::isStandaloneDocument | ( | ) | const |
Returns true if this document has been declared standalone in the XML declaration; otherwise returns false.
If no XML declaration has been parsed, this function returns false.
Definition at line 2731 of file qxmlstream.cpp.
◆ isStartDocument()
|
inline |
Returns true if tokenType() equals \l StartDocument; otherwise returns false.
Definition at line 261 of file qxmlstream.h.
◆ isStartElement()
|
inline |
Returns true if tokenType() equals \l StartElement; otherwise returns false.
Definition at line 263 of file qxmlstream.h.
◆ isWhitespace()
| bool QXmlStreamReader::isWhitespace | ( | ) | const |
Returns true if the reader reports characters that only consist of white-space; otherwise returns false.
- See also
- isCharacters(), text()
Definition at line 2706 of file qxmlstream.cpp.
◆ lineNumber()
| qint64 QXmlStreamReader::lineNumber | ( | ) | const |
Returns the current line number, starting with 1.
- See also
- columnNumber(), characterOffset()
Definition at line 1898 of file qxmlstream.cpp.
◆ name()
| QStringView QXmlStreamReader::name | ( | ) | const |
Returns the local name of a StartElement, EndElement, or an EntityReference.
- See also
- namespaceUri(), qualifiedName()
Definition at line 2209 of file qxmlstream.cpp.
◆ namespaceDeclarations()
| QXmlStreamNamespaceDeclarations QXmlStreamReader::namespaceDeclarations | ( | ) | const |
If the tokenType() is \l StartElement, this function returns the element's namespace declarations. Otherwise an empty vector is returned.
The QXmlStreamNamespaceDeclarations class is defined to be a QList of QXmlStreamNamespaceDeclaration.
Definition at line 2054 of file qxmlstream.cpp.
◆ namespaceProcessing()
| bool QXmlStreamReader::namespaceProcessing | ( | ) | const |
the namespace-processing flag of the stream reader.
This property controls whether or not the stream reader processes namespaces. If enabled, the reader processes namespaces, otherwise it does not.
By default, namespace-processing is enabled.
Definition at line 759 of file qxmlstream.cpp.
◆ namespaceUri()
| QStringView QXmlStreamReader::namespaceUri | ( | ) | const |
Returns the namespaceUri of a StartElement or EndElement.
- See also
- name(), qualifiedName()
Definition at line 2220 of file qxmlstream.cpp.
◆ notationDeclarations()
| QXmlStreamNotationDeclarations QXmlStreamReader::notationDeclarations | ( | ) | const |
If the tokenType() is \l DTD, this function returns the DTD's notation declarations. Otherwise an empty vector is returned.
The QXmlStreamNotationDeclarations class is defined to be a QList of QXmlStreamNotationDeclaration.
Definition at line 1941 of file qxmlstream.cpp.
◆ prefix()
| QStringView QXmlStreamReader::prefix | ( | ) | const |
- Since
- 4.4
Returns the prefix of a StartElement or EndElement.
- See also
- name(), qualifiedName()
Definition at line 2253 of file qxmlstream.cpp.
◆ processingInstructionData()
| QStringView QXmlStreamReader::processingInstructionData | ( | ) | const |
Returns the data of a ProcessingInstruction.
Definition at line 2196 of file qxmlstream.cpp.
◆ processingInstructionTarget()
| QStringView QXmlStreamReader::processingInstructionTarget | ( | ) | const |
Returns the target of a ProcessingInstruction.
Definition at line 2187 of file qxmlstream.cpp.
◆ qualifiedName()
| QStringView QXmlStreamReader::qualifiedName | ( | ) | const |
Returns the qualified name of a StartElement or EndElement;
A qualified name is the raw name of an element in the XML data. It consists of the namespace prefix, followed by colon, followed by the element's local name. Since the namespace prefix is not unique (the same prefix can point to different namespaces and different prefixes can point to the same namespace), you shouldn't use qualifiedName(), but the resolved namespaceUri() and the attribute's local name().
- See also
- name(), prefix(), namespaceUri()
Definition at line 2238 of file qxmlstream.cpp.
◆ raiseError()
Raises a custom error with an optional error message.
- See also
- error(), errorString()
Definition at line 2153 of file qxmlstream.cpp.
◆ readElementText()
| QString QXmlStreamReader::readElementText | ( | ReadElementTextBehaviour | behaviour = ErrorOnUnexpectedElement | ) |
Convenience function to be called in case a StartElement was read. Reads until the corresponding EndElement and returns all text in-between. In case of no error, the current token (see tokenType()) after having called this function is EndElement.
The function concatenates text() when it reads either \l Characters or EntityReference tokens, but skips ProcessingInstruction and \l Comment. If the current token is not StartElement, an empty string is returned.
The behaviour defines what happens in case anything else is read before reaching EndElement. The function can include the text from child elements (useful for example for HTML), ignore child elements, or raise an UnexpectedElementError and return what was read so far (default).
- Since
- 4.6
Definition at line 2112 of file qxmlstream.cpp.
◆ readNext()
| QXmlStreamReader::TokenType QXmlStreamReader::readNext | ( | ) |
Reads the next token and returns its type.
With one exception, once an error() is reported by readNext(), further reading of the XML stream is not possible. Then atEnd() returns true, hasError() returns true, and this function returns QXmlStreamReader::Invalid.
The exception is when error() returns PrematureEndOfDocumentError. This error is reported when the end of an otherwise well-formed chunk of XML is reached, but the chunk doesn't represent a complete XML document. In that case, parsing can be resumed by calling addData() to add the next chunk of XML, when the stream is being read from a QByteArray, or by waiting for more data to arrive when the stream is being read from a device().
- See also
- tokenType(), tokenString()
Definition at line 602 of file qxmlstream.cpp.
◆ readNextStartElement()
| bool QXmlStreamReader::readNextStartElement | ( | ) |
Reads until the next start element within the current element. Returns true when a start element was reached. When the end element was reached, or when an error occurred, false is returned.
The current element is the element matching the most recently parsed start element of which a matching end element has not yet been reached. When the parser has reached the end element, the current element becomes the parent element.
This is a convenience function for when you're only concerned with parsing XML elements. The \l{QXmlStream Bookmarks Example} makes extensive use of this function.
- Since
- 4.6
- See also
- readNext()
Definition at line 658 of file qxmlstream.cpp.
◆ setDevice()
Sets the current device to device. Setting the device resets the stream to its initial state.
Definition at line 470 of file qxmlstream.cpp.
◆ setEntityExpansionLimit()
| void QXmlStreamReader::setEntityExpansionLimit | ( | int | limit | ) |
- Since
- 5.15
Sets the maximum amount of characters a single entity is allowed to expand into to limit. If a single entity expands past the given limit, the document is not considered well formed.
The limit is there to prevent DoS attacks when loading unknown XML documents where recursive entity expansion could otherwise exhaust all available memory.
The default value for this property is 4096 characters.
- See also
- entityExpansionLimit
Definition at line 2039 of file qxmlstream.cpp.
◆ setEntityResolver()
| void QXmlStreamReader::setEntityResolver | ( | QXmlStreamEntityResolver * | resolver | ) |
- Since
- 4.4
Makes resolver the new entityResolver().
The stream reader does not take ownership of the resolver. It's the callers responsibility to ensure that the resolver is valid during the entire life-time of the stream reader object, or until another resolver or \nullptr is set.
- See also
- entityResolver()
Definition at line 247 of file qxmlstream.cpp.
◆ setNamespaceProcessing()
| void QXmlStreamReader::setNamespaceProcessing | ( | bool | enable | ) |
◆ skipCurrentElement()
| void QXmlStreamReader::skipCurrentElement | ( | ) |
Reads until the end of the current element, skipping any child nodes. This function is useful for skipping unknown elements.
The current element is the element matching the most recently parsed start element of which a matching end element has not yet been reached. When the parser has reached the end element, the current element becomes the parent element.
- Since
- 4.6
Definition at line 680 of file qxmlstream.cpp.
◆ text()
| QStringView QXmlStreamReader::text | ( | ) | const |
Returns the text of \l Characters, \l Comment, \l DTD, or EntityReference.
Definition at line 1928 of file qxmlstream.cpp.
◆ tokenString()
| QString QXmlStreamReader::tokenString | ( | ) | const |
Returns the reader's current token as string.
- See also
- tokenType()
Definition at line 769 of file qxmlstream.cpp.
◆ tokenType()
| QXmlStreamReader::TokenType QXmlStreamReader::tokenType | ( | ) | const |
Returns the type of the current token.
The current token can also be queried with the convenience functions isStartDocument(), isEndDocument(), isStartElement(), isEndElement(), isCharacters(), isComment(), isDTD(), isEntityReference(), and isProcessingInstruction().
- See also
- tokenString()
Definition at line 635 of file qxmlstream.cpp.
The documentation for this class was generated from the following files:
- src/corelib/serialization/qxmlstream.h
- src/corelib/serialization/qxmlstream.cpp
