KoXmlWriter Class Reference

#include <KoXmlWriter.h>

Inheritance diagram for KoXmlWriter:

Classes
struct	Tag

Public Member Functions
void	addAttribute (const char *attrName, bool value)
void	addAttribute (const char *attrName, const char *value)
void	addAttribute (const char *attrName, const QByteArray &value)
	Overloaded version of the one taking a const char* argument, for convenience.
void	addAttribute (const char *attrName, const QString &value)
void	addAttribute (const char *attrName, double value)
void	addAttribute (const char *attrName, float value)
void	addAttribute (const char *attrName, int value)
void	addAttribute (const char *attrName, uint value)
void	addCompleteElement (QIODevice *dev)
void	addManifestEntry (const QString &fullPath, const QString &mediaType)
void	addTextNode (const char *cstr)
	Adds a text node as a child of the current element.
void	addTextNode (const QByteArray &cstr)
	Overloaded version of the one taking a const char* argument.
void	addTextNode (const QString &str)
void	endDocument ()
	Call this to terminate an XML document.
void	endElement ()
	KoXmlWriter (QIODevice *dev, int indentLevel=0)
	Private (QIODevice *dev_, int indentLevel=0)
void	startDocument (const char *rootElemName, const char *publicId=0, const char *systemId=0)
void	startElement (const char *tagName, bool indentInside=true)
	~KoXmlWriter ()
	Destructor.
	~Private ()

Public Attributes
int	baseIndentLevel
QIODevice *	dev
char *	escapeBuffer
char *	indentBuffer
QStack< Tag >	tags

Private Member Functions
void	closeStartElement (Tag &tag)
char *	escapeForXML (const char *source, int length) const
	KoXmlWriter (const KoXmlWriter &)
KoXmlWriter &	operator= (const KoXmlWriter &)
bool	prepareForChild (bool indentInside=true)
void	prepareForTextNode ()
void	writeChar (char c)
void	writeCString (const char *cstr)
void	writeIndent ()
	Write out followed by the number of spaces required.
Private Member Functions inherited from Private
	Private (KisCanvas2 *c)

Private Attributes
Private *const	d
Private Attributes inherited from Private
KisCanvas2 *	canvas
int	displayedFrame
int	intendedFrame

Detailed Description

A class for writing out XML (to any QIODevice), with a special attention on performance. The XML is being written out along the way, which avoids requiring the entire document in memory (like QDom does).

Definition at line 19 of file KoXmlWriter.cpp.

Constructor & Destructor Documentation

~Private()

KoXmlWriter::~Private ( )

inline

Definition at line 27 of file KoXmlWriter.cpp.

               {
        delete[] indentBuffer;
        delete[] escapeBuffer;
        //TODO: look at if we must delete "dev". For me we must delete it otherwise we will leak it
    }

KoXmlWriter() [1/2]

KoXmlWriter::KoXmlWriter ( QIODevice * dev, int indentLevel = 0 )

explicit

Create a KoXmlWriter instance to write out an XML document into the given QIODevice.

Definition at line 42 of file KoXmlWriter.cpp.

        : d(new Private(dev, indentLevel))
{
    d->indentBuffer = new char[ s_indentBufferLength ];
    memset(d->indentBuffer, ' ', s_indentBufferLength);
    *d->indentBuffer = '\n'; // write newline before indentation, in one go
 
    d->escapeBuffer = new char[s_escapeBufferLen];
    if (!d->dev->isOpen())
        d->dev->open(QIODevice::WriteOnly);
 
}

References d, s_escapeBufferLen, and s_indentBufferLength.

~KoXmlWriter()

KoXmlWriter::~KoXmlWriter

(

)

Destructor.

Definition at line 55 of file KoXmlWriter.cpp.

{
    delete d;
}

References d.

KoXmlWriter() [2/2]

KoXmlWriter::KoXmlWriter ( const KoXmlWriter & )

private

Member Function Documentation

addAttribute() [1/8]

void KoXmlWriter::addAttribute ( const char * attrName, bool value )

inline

Add an attribute whose value is an bool It is written as "true" or "false" based on value

Definition at line 80 of file KoXmlWriter.h.

                                                               {
        addAttribute(attrName, value ? "true" : "false");
    }

References value().

addAttribute() [2/8]

void KoXmlWriter::addAttribute	(	const char *	attrName,
		const char *	value )

Add an attribute to the current element.

Definition at line 213 of file KoXmlWriter.cpp.

{
    writeChar(' ');
    writeCString(attrName);
    writeCString("=\"");
    char* escaped = escapeForXML(value, -1);
    writeCString(escaped);
    if (escaped != d->escapeBuffer)
        delete[] escaped;
    writeChar('"');
}

References d, escaped, escapeForXML(), value(), writeChar(), and writeCString().

addAttribute() [3/8]

void KoXmlWriter::addAttribute	(	const char *	attrName,
		const QByteArray &	value )

Overloaded version of the one taking a const char* argument, for convenience.

Definition at line 200 of file KoXmlWriter.cpp.

{
    // Same as the const char* one, but here we know the size
    writeChar(' ');
    writeCString(attrName);
    writeCString("=\"");
    char* escaped = escapeForXML(value.constData(), value.size());
    writeCString(escaped);
    if (escaped != d->escapeBuffer)
        delete[] escaped;
    writeChar('"');
}

References d, escaped, escapeForXML(), value(), writeChar(), and writeCString().

addAttribute() [4/8]

void KoXmlWriter::addAttribute ( const char * attrName, const QString & value )

inline

Overloaded version of addAttribute( const char*, const char* ), which is a bit slower because it needs to convert value to utf8 first.

Definition at line 61 of file KoXmlWriter.h.

                                                                         {
        addAttribute(attrName, value.toUtf8());
    }

References value().

addAttribute() [5/8]

void KoXmlWriter::addAttribute	(	const char *	attrName,
		double	value )

Add an attribute whose value is a floating point number The number is written out with the highest possible precision (unlike QString::number and setNum, which default to 6 digits)

Definition at line 225 of file KoXmlWriter.cpp.

{
    addAttribute(attrName, KisDomUtils::toString(value));
}

References addAttribute(), KisDomUtils::toString(), and value().

addAttribute() [6/8]

void KoXmlWriter::addAttribute	(	const char *	attrName,
		float	value )

Add an attribute whose value is a floating point number The number is written out with the highest possible precision (unlike QString::number and setNum, which default to 6 digits)

Definition at line 230 of file KoXmlWriter.cpp.

{
    addAttribute(attrName, KisDomUtils::toString(value));
}

References addAttribute(), KisDomUtils::toString(), and value().

addAttribute() [7/8]

void KoXmlWriter::addAttribute ( const char * attrName, int value )

inline

Add an attribute whose value is an integer

Definition at line 67 of file KoXmlWriter.h.

                                                              {
        addAttribute(attrName, QByteArray::number(value));
    }

References value().

addAttribute() [8/8]

void KoXmlWriter::addAttribute ( const char * attrName, uint value )

inline

Add an attribute whose value is an unsigned integer

Definition at line 73 of file KoXmlWriter.h.

                                                               {
        addAttribute(attrName, QByteArray::number(value));
    }

References value().

addCompleteElement()

void KoXmlWriter::addCompleteElement

(

QIODevice *

dev

)

This is quite a special-purpose method, not for everyday use. It adds a complete element (with its attributes and child elements) as a child of the current element. The iodevice is supposed to be escaped for XML already, so it will usually come from another KoXmlWriter. This is usually used with KTempFile.

Definition at line 128 of file KoXmlWriter.cpp.

{
    prepareForChild();
    const bool wasOpen = indev->isOpen();
    // Always (re)open the device in readonly mode, it might be
    // already open but for writing, and we need to rewind.
    const bool openOk = indev->open(QIODevice::ReadOnly);
    Q_ASSERT(openOk);
    if (!openOk) {
        warnStore << "Failed to re-open the device! wasOpen=" << wasOpen;
        return;
    }
 
    QString indentString;
    indentString.fill((' '), d->tags.size() + d->baseIndentLevel);
    QByteArray indentBuf(indentString.toUtf8());
 
    QByteArray buffer;
    while (!indev->atEnd()) {
        buffer = indev->readLine();
 
        d->dev->write(indentBuf);
        d->dev->write(buffer);
    }
 
    if (!wasOpen) {
        // Restore initial state
        indev->close();
    }
}

References d, prepareForChild(), and warnStore.

addManifestEntry()

void KoXmlWriter::addManifestEntry	(	const QString &	fullPath,
		const QString &	mediaType )

Special helper for writing "manifest" files This is equivalent to startElement/2*addAttribute/endElement This API will probably have to change (or not be used anymore) when we add support for encrypting/signing.

Note

OASIS-specific

Definition at line 316 of file KoXmlWriter.cpp.

{
    startElement("manifest:file-entry");
    addAttribute("manifest:media-type", mediaType);
    addAttribute("manifest:full-path", fullPath);
    endElement();
}

References addAttribute(), endElement(), and startElement().

addTextNode() [1/3]

void KoXmlWriter::addTextNode

(

const char *

cstr

)

Adds a text node as a child of the current element.

This is appends the literal content of str to the contents of the element. E.g. addTextNode( "foo" ) inside a <p> element gives <p>foo</p>, and startElement( "b" ); endElement( "b" ); addTextNode( "foo" ) gives <p><b/>foo</p>

Definition at line 191 of file KoXmlWriter.cpp.

{
    prepareForTextNode();
    char* escaped = escapeForXML(cstr, -1);
    writeCString(escaped);
    if (escaped != d->escapeBuffer)
        delete[] escaped;
}

References d, escaped, escapeForXML(), prepareForTextNode(), and writeCString().

addTextNode() [2/3]

void KoXmlWriter::addTextNode

(

const QByteArray &

cstr

)

Overloaded version of the one taking a const char* argument.

Definition at line 181 of file KoXmlWriter.cpp.

{
    // Same as the const char* version below, but here we know the size
    prepareForTextNode();
    char* escaped = escapeForXML(cstr.constData(), cstr.size());
    writeCString(escaped);
    if (escaped != d->escapeBuffer)
        delete[] escaped;
}

References d, escaped, escapeForXML(), prepareForTextNode(), and writeCString().

addTextNode() [3/3]

void KoXmlWriter::addTextNode ( const QString & str )

inline

Overloaded version of addTextNode( const char* ), which is a bit slower because it needs to convert str to utf8 first.

Definition at line 115 of file KoXmlWriter.h.

                                                {
        addTextNode(str.toUtf8());
    }

closeStartElement()

void KoXmlWriter::closeStartElement ( Tag & tag )

inlineprivate

Definition at line 192 of file KoXmlWriter.h.

                                            {
        if (!tag.openingTagClosed) {
            tag.openingTagClosed = true;
            writeChar('>');
        }
    }

References KoXmlWriter::Tag::openingTagClosed.

endDocument()

void KoXmlWriter::endDocument

(

)

Call this to terminate an XML document.

Definition at line 78 of file KoXmlWriter.cpp.

{
    // just to do exactly like QDom does (newline at end of file).
    writeChar('\n');
    Q_ASSERT(d->tags.isEmpty());
}

References d, and writeChar().

endElement()

void KoXmlWriter::endElement

(

)

Terminate the current element. After this you should start a new one (sibling), add a sibling text node, or close another one (end of siblings).

Definition at line 159 of file KoXmlWriter.cpp.

{
    if (d->tags.isEmpty())
        warnStore << "EndElement() was called more times than startElement(). "
                     "The generated XML will be invalid! "
                     "Please report this bug (by saving the document to another format...)" << Qt::endl;
 
    Tag tag = d->tags.pop();
 
    if (!tag.hasChildren) {
        writeCString("/>");
    } else {
        if (tag.indentInside && !tag.lastChildIsText) {
            writeIndent();
        }
        writeCString("</");
        Q_ASSERT(tag.tagName != 0);
        writeCString(tag.tagName);
        writeChar('>');
    }
}

References d, KoXmlWriter::Tag::hasChildren, KoXmlWriter::Tag::indentInside, KoXmlWriter::Tag::lastChildIsText, KoXmlWriter::Tag::tagName, warnStore, writeChar(), writeCString(), and writeIndent().

escapeForXML()

char * KoXmlWriter::escapeForXML ( const char * source, int length = -1 ) const

private

Definition at line 245 of file KoXmlWriter.cpp.

{
    // we're going to be pessimistic on char length; so lets make the outputLength less
    // the amount one char can take: 6
    char* destBoundary = d->escapeBuffer + s_escapeBufferLen - 6;
    char* destination = d->escapeBuffer;
    char* output = d->escapeBuffer;
    const char* src = source; // src moves, source remains
    for (;;) {
        if (destination >= destBoundary) {
            // When we come to realize that our escaped string is going to
            // be bigger than the escape buffer (this shouldn't happen very often...),
            // we drop the idea of using it, and we allocate a bigger buffer.
            // Note that this if() can only be hit once per call to the method.
            if (length == -1)
                length = qstrlen(source);   // expensive...
            uint newLength = length * 6 + 1; // worst case. 6 is due to " and '
            char* buffer = new char[ newLength ];
            destBoundary = buffer + newLength;
            uint amountOfCharsAlreadyCopied = destination - d->escapeBuffer;
            memcpy(buffer, d->escapeBuffer, amountOfCharsAlreadyCopied);
            output = buffer;
            destination = buffer + amountOfCharsAlreadyCopied;
        }
        switch (*src) {
        case 60: // <
            memcpy(destination, "&lt;", 4);
            destination += 4;
            break;
        case 62: // >
            memcpy(destination, "&gt;", 4);
            destination += 4;
            break;
        case 34: // "
            memcpy(destination, "&quot;", 6);
            destination += 6;
            break;
#if 0 // needed?
        case 39: // '
            memcpy(destination, "&apos;", 6);
            destination += 6;
            break;
#endif
        case 38: // &
            memcpy(destination, "&amp;", 5);
            destination += 5;
            break;
        case 0:
            *destination = '\0';
            return output;
        // Control codes accepted in XML 1.0 documents.
        case 9:
        case 10:
        case 13:
            *destination++ = *src++;
            continue;
        default:
            // Don't add control codes not accepted in XML 1.0 documents.
            if (*src > 0 && *src < 32) {
                ++src;
            } else {
                *destination++ = *src++;
            }
            continue;
        }
        ++src;
    }
    // NOTREACHED (see case 0)
    return output;
}

References d, length(), s_escapeBufferLen, and source().

operator=()

KoXmlWriter & KoXmlWriter::operator= ( const KoXmlWriter & )

private

prepareForChild()

bool KoXmlWriter::prepareForChild ( bool indentInside = true )

private

Definition at line 86 of file KoXmlWriter.cpp.

{
    if (!d->tags.isEmpty()) {
        Tag& parent = d->tags.top();
        if (!parent.hasChildren) {
            closeStartElement(parent);
            parent.hasChildren = true;
            parent.lastChildIsText = false;
        }
        if (parent.indentInside && indentInside) {
            writeIndent();
        }
        return parent.indentInside && indentInside;
    }
    return indentInside;
}

References closeStartElement(), d, and writeIndent().

prepareForTextNode()

void KoXmlWriter::prepareForTextNode ( )

private

Definition at line 103 of file KoXmlWriter.cpp.

{
    if (d->tags.isEmpty())
        return;
    Tag& parent = d->tags.top();
    if (!parent.hasChildren) {
        closeStartElement(parent);
        parent.hasChildren = true;
        parent.lastChildIsText = true;
    }
}

References closeStartElement(), and d.

Private()

KoXmlWriter::Private ( QIODevice * dev_, int indentLevel = 0 )

inline

Definition at line 22 of file KoXmlWriter.cpp.

        : dev(dev_)
        , baseIndentLevel(indentLevel)
    {}

startDocument()

void KoXmlWriter::startDocument	(	const char *	rootElemName,
		const char *	publicId = 0,
		const char *	systemId = 0 )

Start the XML document. This writes out the <?xml?> tag with utf8 encoding, and the DOCTYPE.

Parameters

rootElemName	the name of the root element, used in the DOCTYPE tag.
publicId	the public identifier, e.g. "-//OpenOffice.org//DTD OfficeDocument 1.0//EN"
systemId	the system identifier, e.g. "office.dtd" or a full URL to it.

Definition at line 60 of file KoXmlWriter.cpp.

{
    Q_ASSERT(d->tags.isEmpty());
    writeCString("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n");
    // There isn't much point in a doctype if there's no DTD to refer to
    // (I'm told that files that are validated by a RelaxNG schema cannot refer to the schema)
    if (publicId) {
        writeCString("<!DOCTYPE ");
        writeCString(rootElemName);
        writeCString(" PUBLIC \"");
        writeCString(publicId);
        writeCString("\" \"");
        writeCString(systemId);
        writeCString("\"");
        writeCString(">\n");
    }
}

References d, and writeCString().

startElement()

void KoXmlWriter::startElement	(	const char *	tagName,
		bool	indentInside = true )

Start a new element, as a child of the current element.

Parameters

tagName	the name of the tag.
indentInside	if set to false, there will be no indentation inside this tag. This is useful for elements where whitespace matters.

Definition at line 115 of file KoXmlWriter.cpp.

{
    Q_ASSERT(tagName != 0);
 
    // Tell parent that it has children
    indentInside = prepareForChild(indentInside);
 
    d->tags.push(Tag(tagName, indentInside));
    writeChar('<');
    writeCString(tagName);
    //kDebug(s_area) << tagName;
}

References d, prepareForChild(), writeChar(), and writeCString().

writeChar()

void KoXmlWriter::writeChar ( char c )

private

Definition at line 330 of file KoXmlWriter.cpp.

                                  {
    d->dev->putChar(c);
}

References d.

writeCString()

void KoXmlWriter::writeCString ( const char * cstr )

private

Definition at line 325 of file KoXmlWriter.cpp.

                                               {
    d->dev->write(cstr, qstrlen(cstr));
}

References d.

writeIndent()

void KoXmlWriter::writeIndent ( )

private

Write out
followed by the number of spaces required.

Definition at line 235 of file KoXmlWriter.cpp.

{
    // +1 because of the leading '\n'
    d->dev->write(d->indentBuffer, qMin(d->tags.size() + d->baseIndentLevel + 1,
                                        s_indentBufferLength));
}

References d, and s_indentBufferLength.

Member Data Documentation

baseIndentLevel

int KoXmlWriter::baseIndentLevel

Definition at line 35 of file KoXmlWriter.cpp.

d

Private* const KoXmlWriter::d

private

Definition at line 203 of file KoXmlWriter.h.

dev

QIODevice* KoXmlWriter::dev

Definition at line 33 of file KoXmlWriter.cpp.

escapeBuffer

char* KoXmlWriter::escapeBuffer

Definition at line 39 of file KoXmlWriter.cpp.

indentBuffer

char* KoXmlWriter::indentBuffer

Definition at line 37 of file KoXmlWriter.cpp.

tags

QStack<Tag> KoXmlWriter::tags

Definition at line 34 of file KoXmlWriter.cpp.

---

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

• libs/store/KoXmlWriter.cpp
• libs/store/KoXmlWriter.h