KXQTS::XMLIndenter Class Reference

Serializes a stream of SAX events into XML, sent to a QIODevice. More...

#include <XMLIndenter.h>

Inheritance diagram for KXQTS::XMLIndenter:

[legend]Collaboration diagram for KXQTS::XMLIndenter:

[legend]List of all members.

Public Member Functions
virtual bool	characters (const QString &ch)
virtual bool	comment (const QString &ch)
virtual bool	endCDATA ()
virtual bool	endDocument ()
virtual bool	endDTD ()
virtual bool	endElement (const QString &namespaceURI, const QString &localName, const QString &qName)
virtual bool	endElement (const QString &qName)
virtual bool	endEntity (const QString &name)
virtual bool	endPrefixMapping (const QString &prefix)
virtual QString	errorString () const
virtual bool	ignorableWhitespace (const QString &ch)
virtual QString	indentString () const
virtual bool	processingInstruction (const QString &target, const QString &data)
virtual void	setDocumentLocator (QXmlLocator *)
virtual void	setIndentString (const QString &indent)
virtual void	setWriter (XMLWriter *handler)
virtual bool	skippedEntity (const QString &name)
virtual bool	startCDATA ()
virtual bool	startDocument ()
virtual bool	startDTD (const QString &name, const QString &publicId, const QString &systemId)
virtual bool	startElement (const QString &namespaceURI, const QString &localName, const QString &qName, const QXmlAttributes &atts)
virtual bool	startElement (const QString &qName, const QXmlAttributes &atts)
virtual bool	startEntity (const QString &name)
virtual bool	startPrefixMapping (const QString &prefix, const QString &namespaceURI)
virtual XMLWriter *	writer () const
	XMLIndenter (XMLWriter *handler=0)
virtual	~XMLIndenter ()
Classes
class	Private

---

Detailed Description

Serializes a stream of SAX events into XML, sent to a QIODevice.

Warning:

This class is incomplete. It's behavior as well as the documentation, except for this paragraph, is undefined. Do not use it. It is here because it might be that it at somepoint will be completed, although nothing is planned.

XMLIndenter is a fast and simple XML serializer which takes care of all the low level details of well-formedness and character escaping, allowing the user to focus on higher level issues and increasing the chances of producing valid, interoperable XML.

The content XMLIndenter produces is sent to a QIODevice, which is either specified in XMLIndenter's constructor or via setDevice(). If writing to the device fails, the content functions such as startElement() returns false.

XMLIndenter sub-classes XMLWriter meaning it can serialize content from any code that produces SAX events. The class can also be used manually, by calling startElement(), endCDATA(), and so forth.

XMLIndenter cannot be used to serialize multiple documents. One instance per document must be used.

XMLIndenter takes care of escaping content into character references as necessary. Thus, it should not be done manually. In fact, it would most likely result in invalid XML or an unintended result. XMLIndenter always serializes into UTF-8.

When compiled in debug mode, XMLIndenter contains several tests that helps ensuring that XMLIndenter produces valid XML. Some of these tests ensures that:

• The xmlns and xml prefixes are used properly
• Content of comments and processing instructions is valid
• Element, attribute and DOCTYPE names are sensible
• Elements are properly nested and balanced
• To some extent that things occur in the proper order. For example, that the document type definition isn't added inside an element
• That namespaces prefixes are declared

Not triggering XMLIndenter's tests does not guarantee valid XML is produced, but they do help catching common mistakes and some of the corner cases in the specifications. When XMLIndenter is compiled in release mode, these tests are not enabled and the error handling in effect is concerning writing to the QIODevice.

Here is an example of using XMLIndenter for creating a simple XHTML document:

QByteArray result;
QBuffer returnBuffer(&result);
XMLWriter writer(&returnBuffer);

writer.startDocument();

writer.startDTD(QLatin1String("html"), QLatin1String("-//W3C//DTD XHTML 1.0 Strict//EN"),
        QLatin1String("http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"));
writer.endDTD();

writer.startPrefixMapping(QString(), QLatin1String("http://www.w3.org/1999/xhtml"));

writer.startElement(QLatin1String("html"), QXmlAttributes());
writer.startElement(QLatin1String("body"), QXmlAttributes());
writer.startElement(QLatin1String("p"), QXmlAttributes());

writer.characters(QLatin1String("Hello World!"));

writer.endElement(QLatin1String("p"));
writer.endElement(QLatin1String("body"));
writer.endElement(QLatin1String("html"));

writer.endDocument();

result now contains the string:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><body><p>Hello World!</p></body></html>

Namespace declarations are added with startPrefixMapping(), not by sending attributes with name xmlns:* to startElement().

See also:

HOWTO Avoid Being Called a Bozo When Producing XML

Extensible Markup Language (XML) 1.0 (Third Edition)

Namespaces in XML

Author:

Frans Englich <frans.englich@telia.com>

Definition at line 84 of file XMLIndenter.h.

---

Constructor & Destructor Documentation

XMLIndenter::XMLIndenter

(

XMLWriter *

handler = 0

)

Creates a XMLIndenter which serializes its received events to outStream.

Note:

XMLIndenter does not claim ownership of outStream. Thus, outStream may not be destroyed as long as this XMLIndenter instance uses it.

Definition at line 47 of file XMLIndenter.cpp.

---

Member Function Documentation

bool XMLIndenter::characters

(

const QString &

ch

)

[virtual]

Returns:

false if failure occurs in writing to the QIODevice, otherwise true

Reimplemented from KXQTS::XMLWriter.

Definition at line 98 of file XMLIndenter.cpp.

References KXQTS::XMLWriter::characters(), and KXQTS::XMLIndenter::Private::contentHandler().

Here is the call graph for this function:

bool XMLIndenter::comment

(

const QString &

ch

)

[virtual]

Creates a comment with content ch. ch is escaped, there's no need to do it manually. For example, calling comment() with ch set to "my comment", results in "<!--my comment-->" in the output.

Note:

if ch contains double hyphen("--"), the produced XML will not be well formed.

Returns:

false if failure occurs in writing to the QIODevice, otherwise true

Reimplemented from KXQTS::XMLWriter.

Definition at line 103 of file XMLIndenter.cpp.

References KXQTS::XMLWriter::comment(), and KXQTS::XMLIndenter::Private::contentHandler().

Here is the call graph for this function:

bool XMLIndenter::endCDATA

(

)

[virtual]

Returns:

false if failure occurs in writing to the QIODevice, otherwise true

Reimplemented from KXQTS::XMLWriter.

Definition at line 113 of file XMLIndenter.cpp.

References KXQTS::XMLIndenter::Private::contentHandler(), and KXQTS::XMLWriter::endCDATA().

Here is the call graph for this function:

bool XMLIndenter::endDocument

(

)

[virtual]

Closes the QIODevice XMLWriter writes to.

Reimplemented from KXQTS::XMLWriter.

Definition at line 140 of file XMLIndenter.cpp.

References KXQTS::XMLIndenter::Private::contentHandler(), and KXQTS::XMLWriter::endDocument().

Here is the call graph for this function:

bool XMLIndenter::endDTD

(

)

[virtual]

Apart from closing the DTD, an new line is also added at end.

Reimplemented from KXQTS::XMLWriter.

Definition at line 125 of file XMLIndenter.cpp.

References KXQTS::XMLIndenter::Private::contentHandler(), and KXQTS::XMLWriter::endDTD().

Here is the call graph for this function:

bool XMLIndenter::endElement	(	const QString &	namespaceURI,
		const QString &	localName,
		const QString &	qName
	)			[virtual]

Behaves essentially as endElement(const QString &qName). This function is used when XMLIndenter is used in SAX code.

namespaceURI and localName are not used.

The call:

 endElement(QString(), QString(), qName);

is equivalent to:

 endElement(qName);

Returns:

false if failure occurs in writing to the QIODevice, otherwise true

Reimplemented from KXQTS::XMLWriter.

Definition at line 75 of file XMLIndenter.cpp.

References KXQTS::XMLIndenter::Private::contentHandler(), and KXQTS::XMLWriter::endElement().

Here is the call graph for this function:

bool XMLIndenter::endElement

(

const QString &

qName

)

[virtual]

Signals the end of an element with name qName. qName must be supplied.

Calls to startElement() and endElement() must always be balanced.

Returns:

false if failure occurs in writing to the QIODevice, otherwise true

Reimplemented from KXQTS::XMLWriter.

Definition at line 82 of file XMLIndenter.cpp.

References KXQTS::XMLIndenter::Private::contentHandler(), and KXQTS::XMLWriter::endElement().

Here is the call graph for this function:

bool XMLIndenter::endPrefixMapping

(

const QString &

prefix

)

[virtual]

This function is not used by XMLWriter, but is implemented in order to satisfy QXmlContentHandler's interface.

Reimplemented from KXQTS::XMLWriter.

Definition at line 155 of file XMLIndenter.cpp.

References KXQTS::XMLIndenter::Private::contentHandler(), and KXQTS::XMLWriter::endPrefixMapping().

Here is the call graph for this function:

QString XMLIndenter::errorString

(

)

const [virtual]

A description of an error if it occured. This is typically QIODevice::errorString(). If no error has occured, an empty string is returned.

Reimplemented from KXQTS::XMLWriter.

Definition at line 145 of file XMLIndenter.cpp.

References KXQTS::XMLIndenter::Private::contentHandler(), and KXQTS::XMLWriter::errorString().

Here is the call graph for this function:

bool XMLIndenter::ignorableWhitespace

(

const QString &

ch

)

[virtual]

Serializes ch as if it was sent to characters().

Returns:

false if failure occurs in writing to the QIODevice, otherwise true

Reimplemented from KXQTS::XMLWriter.

Definition at line 150 of file XMLIndenter.cpp.

References KXQTS::XMLIndenter::Private::contentHandler(), and KXQTS::XMLWriter::ignorableWhitespace().

Here is the call graph for this function:

bool XMLIndenter::processingInstruction	(	const QString &	target,
		const QString &	data
	)			[virtual]

Creates a processing instruction by name target, and content data.

Returns:

false if failure occurs in writing to the QIODevice, otherwise true

Reimplemented from KXQTS::XMLWriter.

Definition at line 92 of file XMLIndenter.cpp.

References KXQTS::XMLIndenter::Private::contentHandler(), and KXQTS::XMLWriter::processingInstruction().

Here is the call graph for this function:

void XMLIndenter::setDocumentLocator

(

QXmlLocator *

)

[virtual]

This function is not used by XMLWriter, but is implemented in order to satisfy QXmlContentHandler's interface.

Reimplemented from KXQTS::XMLWriter.

Definition at line 165 of file XMLIndenter.cpp.

References KXQTS::XMLIndenter::Private::contentHandler(), and KXQTS::XMLWriter::setDocumentLocator().

Here is the call graph for this function:

bool XMLIndenter::skippedEntity

(

const QString &

name

)

[virtual]

This function is not used by XMLWriter, but is implemented in order to satisfy QXmlContentHandler's interface.

Reimplemented from KXQTS::XMLWriter.

Definition at line 160 of file XMLIndenter.cpp.

References KXQTS::XMLIndenter::Private::contentHandler(), and KXQTS::XMLWriter::skippedEntity().

Here is the call graph for this function:

bool XMLIndenter::startCDATA

(

)

[virtual]

Starts a CDATA section. Content sent with characters() will not be escaped except for ">" if occuring in "]]>".

Returns:

false if failure occurs in writing to the QIODevice, otherwise true

Reimplemented from KXQTS::XMLWriter.

Definition at line 108 of file XMLIndenter.cpp.

References KXQTS::XMLIndenter::Private::contentHandler(), and KXQTS::XMLWriter::startCDATA().

Here is the call graph for this function:

bool XMLIndenter::startDocument

(

)

[virtual]

Returns:

true if opening the output device succeeds, otherwise false

Reimplemented from KXQTS::XMLWriter.

Definition at line 56 of file XMLIndenter.cpp.

References KXQTS::XMLIndenter::Private::contentHandler(), and KXQTS::XMLWriter::startDocument().

Here is the call graph for this function:

bool XMLIndenter::startDTD	(	const QString &	name,
		const QString &	publicId,
		const QString &	systemId
	)			[virtual]

Creates a document type definition.

For example, the code snippet:

 writer.startDTD("html", "-//W3C//DTD XHTML 1.0 Strict//EN",
                 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd");
 writer.endDTD();

would create:

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

Note:

A system identifier must always be specified, but a public identifier may be left out.

A call to startDTD() must be followed by a call to endDTD().

Reimplemented from KXQTS::XMLWriter.

Definition at line 118 of file XMLIndenter.cpp.

References KXQTS::XMLIndenter::Private::contentHandler(), and KXQTS::XMLWriter::startDTD().

Here is the call graph for this function:

bool XMLIndenter::startElement	(	const QString &	namespaceURI,
		const QString &	localName,
		const QString &	qName,
		const QXmlAttributes &	atts
	)			[virtual]

Behaves essentially as startElement(const QString &qName, const QXmlAttributes &atts). This function is used when XMLIndenter is used in SAX code.

The call:

 startElement(QString(), QString(), qName, atts);

is equivalent to:

 startElement(qName, atts);

namespaceURI and localName are not used. This function is used when connecting it with other SAX classes.

Returns:

false if failure occurs in writing to the QIODevice, otherwise true

Reimplemented from KXQTS::XMLWriter.

Definition at line 61 of file XMLIndenter.cpp.

References KXQTS::XMLIndenter::Private::contentHandler(), and KXQTS::XMLWriter::startElement().

Here is the call graph for this function:

bool XMLIndenter::startElement	(	const QString &	qName,
		const QXmlAttributes &	atts
	)			[virtual]

Starts an element with name qName and attributes atts. The prefix in qName must first be declared with startPrefixMapping(), if it has one.

A call to startElement() must always at some point be balanced with a call to endElement().

To declare namespaces, don't put attributes with name xmlns:* in atts, but use startPrefixMapping().

Reimplemented from KXQTS::XMLWriter.

Definition at line 69 of file XMLIndenter.cpp.

References KXQTS::XMLIndenter::Private::contentHandler(), and KXQTS::XMLWriter::startElement().

Here is the call graph for this function:

bool XMLIndenter::startPrefixMapping	(	const QString &	prefix,
		const QString &	namespaceURI
	)			[virtual]

Declares a namespace which maps prefix to namespaceURI. For example, the call:

 startPrefixMapping("xhtml", "http://www.w3.org/1999/xhtml");

would result in:

 xmlns="http://www.w3.org/1999/xhtml"

Reimplemented from KXQTS::XMLWriter.

Definition at line 87 of file XMLIndenter.cpp.

References KXQTS::XMLIndenter::Private::contentHandler(), and KXQTS::XMLWriter::startPrefixMapping().

Here is the call graph for this function:

---

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

• kxqts/lib/XMLIndenter.h
• kxqts/lib/XMLIndenter.cpp

---